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 API Key (free)

  • Create a free account at app.hgraph.com — no credit card required.
  • Go to Projects in the sidebar, open your project, and reveal your key. Use the Publishable Key value, which starts with pk_prod_ (e.g. pk_prod_abc123xyz...).
Your API key is a secret, including in a connector URL

Both of a key's values (pk_prod_ and sk_prod_) currently grant the same access — the publishable key is not read-only and is not restricted. A key placed in a connector URL is a live credential: anyone who can read that URL, your client config, or a shared screenshot has full access to your account's data under your plan's limits.

If your client supports OAuth, prefer the one-click sign-in — it needs no API key at all. If you do paste a key into a URL, treat that URL as a password: don't share it, don't commit it, and don't put it anywhere a browser or third party can read it.

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