HTTP MCP servers with bearer tokens

HTTP MCP servers are the right transport when you want a server that multiple machines or users can share — a remote API endpoint rather than a local subprocess. Authentication over HTTP means bearer tokens. This guide covers how to wire them up in Claude Code and how to handle tokens correctly so they don't become a security liability.

How HTTP MCP transport works

Instead of spawning a subprocess and using stdin/stdout, Claude Code sends JSON-RPC requests as HTTP POST bodies to a fixed URL. The server responds with JSON (or a server-sent event stream for streaming tools). The session still starts with an initialize handshake, then tools/list, then individual tools/call requests — the same protocol, different transport.

The main operational difference from stdio: the server is always running somewhere else. You don't manage its process. You manage only the URL and the credentials that authenticate your requests.

Register an HTTP server

claude mcp add --transport http <name> <url>

For a server that accepts unauthenticated requests (rare in practice, common in local dev):

claude mcp add --transport http local-test http://localhost:8765

For a server that requires a bearer token:

claude mcp add --transport http promenow-tools https://promenow.app/api/mcp \
  --header "Authorization: Bearer pn_live_abc123xyz"

Claude Code stores the header in your config alongside the server registration. It is sent with every JSON-RPC request for that server.

Token security model

The token you pass is a long-lived credential. Treat it exactly like an API key. That means a few concrete rules:

Never commit it. The --headerflag stores it in your Claude Code settings. Check which scope you're using: if you used --scope project, the token may end up in .claude/settings.json, which is committed. Use --scope local (the default) so it lands in .claude/settings.local.json, which is gitignored.
Never store it in localStorage or session storage on a web client. Those are readable by any JavaScript on the page. For server-side config like Claude Code, env vars or gitignored files are fine.
Use a token per context. If you use the same server from your laptop and your VPS, generate separate tokens so you can revoke one without affecting the other.

How well-designed servers store tokens

A server that handles tokens correctly never stores the raw token. When you generate a token, the server:

Computes a SHA-256 hash of the token.
Stores only the hash (plus metadata: created date, label, last-used).
On each request, hashes the incoming token and compares to stored hashes.

This means if the server's database is compromised, attackers get hashes — not usable tokens. It also means the server cannot show you a token after creation. Copy it when it's generated; after that it's gone.

Servers that follow this pattern also record an audit event per MCP call: timestamp, tool name, token identity (but not the raw token). You can inspect the log to see exactly which tools your Claude Code session invoked and when.

Revoking a token

Revocation is straightforward: go to the server's account panel, find the token by its label or created date, and delete it. The hash is removed from the database. The next request with that token gets a 401. Claude Code will report the error the next time it tries to call a tool on that server.

After revoking, update your Claude Code registration:

claude mcp remove promenow-tools
claude mcp add --transport http promenow-tools https://promenow.app/api/mcp \
  --header "Authorization: Bearer pn_live_newtoken"

Multiple headers

Some servers expect additional headers beyond Authorization — a tenant ID, an API version, or a client identifier. Pass multiple --header flags:

claude mcp add --transport http my-server https://api.example.com/mcp \
  --header "Authorization: Bearer tok_abc" \
  --header "X-Tenant-ID: org_123"

Testing the connection before registering

Before running claude mcp add, confirm the server is reachable with a manual initialize request. This saves debugging time if the URL or token is wrong:

curl -s -X POST https://promenow.app/api/mcp \
  -H "Authorization: Bearer pn_live_abc123" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}'

A working server returns a JSON object with result.protocolVersion and result.serverInfo. A 401 means the token is wrong or missing. A 404 means the URL path is wrong. No response at all means the server isn't running or isn't reachable from your network.

Note the Accept: application/json, text/event-stream header — some HTTP MCP servers require this to route correctly between JSON and SSE response modes.

Scope recommendation for HTTP servers with tokens

Always use --scope local (the default) when registering HTTP servers that carry bearer tokens. This keeps the header out of committed files. If you need a server available across all your projects, use --scope user — that stores it in your home directory config, also not committed.

See Inside the promenow-tools MCP server for a real example of what happens after the handshake, and Build your first MCP server if you want to run the server side of this yourself.