Skip to main content

API Key Access

Most people connect Claude with a one-click OAuth sign-in. But the Hgraph MCP server also accepts a plain API key, which is the right choice when:

  • Your client can't do the OAuth flow, or only lets you paste a URL.
  • You're connecting a script, agent, or backend — no human in the loop, no browser.
  • You want a connection that isn't tied to an interactive sign-in.

Both approaches reach the same server and the same live Hedera data. The only difference is how you authenticate.

Hgraph MCP URL

https://mcp.hgraph.com/mcp

Prerequisites​

Hgraph Publishable API Key (free)

  • Create a free account at app.hgraph.com — no credit card required.
  • Open API Keys in the sidebar and copy your Publishable Key. It starts with pk_prod_ (e.g. pk_prod_abc123xyz...).
Publishable vs. secret keys

Use your publishable key (pk_prod_) for MCP access — it's designed to be embedded in URLs and client config, is read-only, and is rate-limited by your plan. Keep your secret key (sk_) for server-side REST/GraphQL calls; don't put it in a connector URL.

Option A — Key in the URL​

For any client that lets you paste a connector URL (and offers a "No Authentication" option), put your publishable key in the path:

https://mcp.hgraph.com/v1/YOUR_PUBLISHABLE_KEY/mcp

Example:

https://mcp.hgraph.com/v1/pk_prod_abc123xyz789/mcp

The key in the path authenticates the request, so select No Authentication in the client's connector form. This is the method the ChatGPT setup guide uses, and it also works as a non-OAuth alternative in Claude's custom-connector form.

Claude Code (CLI, no OAuth)​

Add the connector with the key baked into the URL instead of authenticating interactively:

claude mcp add --scope user --transport http hgraph https://mcp.hgraph.com/v1/YOUR_PUBLISHABLE_KEY/mcp

Verify it's connected:

claude mcp list

Option B — Key in a header (programmatic)​

For code — scripts, agents, backends — send the key in a header to https://mcp.hgraph.com/mcp. Either header works:

  • Authorization: Bearer YOUR_PUBLISHABLE_KEY
  • X-API-KEY: YOUR_PUBLISHABLE_KEY

The MCP server uses Streamable HTTP transport (MCP spec 2025-06-18), so a request must accept both JSON and SSE responses. Here's the opening initialize handshake with curl:

curl -s -X POST https://mcp.hgraph.com/mcp \
  -H "Authorization: Bearer YOUR_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "my-app", "version": "1.0" }
    }
  }'

A successful response returns the server's capabilities and an Mcp-Session-Id header. Send that session id back on subsequent requests via the Mcp-Session-Id header. Most MCP client libraries handle the session and transport for you — point them at https://mcp.hgraph.com/mcp and set the Authorization (or X-API-KEY) header.

Good to know​

  • Read-only. The MCP server only reads publicly available blockchain data; it can't modify or write anything.
  • Rate limits follow your plan. Requests are attributed to the key's organization and rate-limited by its subscription; responses include X-RateLimit-Limit and X-Hgraph-Subscription headers so you can see which plan applied.
  • Streamable HTTP only. The server does not support the deprecated dual-endpoint SSE transport. Any client that speaks Streamable HTTP (Claude, ChatGPT, the MCP SDKs) works.

Next Steps​

Need help? Visit our support page or join our Discord community