MCP headers config ignored when server has OAuth discovery

If you connect from Cursor and your server publishes OAuth discovery metadata

1. 1 Cursor spells a static credential as headers on an mcpServers entry with a url, and resolves ${env:NAME} in command, args, env, url and headers. That part is documented and correct — the problem is what wins.
2. 2 Cursor staff confirmed the precedence on the bug report: when the server answers the OAuth discovery endpoints, Cursor starts the OAuth flow before it sends the POST that would have carried your header, and there is no logic to skip OAuth when Authorization is already set. Staff re-confirmed it reproducing on 3.5.17 on 2026-05-22, with no fix shipped; re-test on your build before assuming it still bites.
3. 3 The downstream symptom is often a registration error rather than an auth error — Incompatible auth server: does not support dynamic client registration — because Cursor is now running a flow you never asked for.
4. 4 The workaround Cursor staff endorsed is server-side: return 404 for every OAuth discovery path on the route that expects a static header. The snippet below is adapted from the Caddyfile in the thread.
5. 5 If what you actually want is OAuth and the failure is registration rather than the header, add an auth object with CLIENT_ID (and CLIENT_SECRET) to skip Dynamic Client Registration.

# Caddy: force the client off the discovery path for this route
@oauth_discovery path /.well-known/oauth-protected-resource* /.well-known/oauth-authorization-server* /.well-known/openid-configuration*
respond @oauth_discovery 404

@mcp path /mcp*
handle @mcp {
  reverse_proxy https://your-mcp-server.internal
}

If you configure the server in VS Code

1. 1 Put the credential in .vscode/mcp.json or the user-profile mcp.json, under servers.<name>.headers, on an entry whose type is http. The documented form for a secret is an inputs entry referenced as ${input:<id>} — VS Code prompts once and stores the value.
2. 2 Do not use the open-plugins .mcp.json format for a header-authenticated server. It has no inputs support, which VS Code closed as out of scope because .mcp.json follows the open-plugins spec, and until 1.124.0 it discarded static headers outright — producing an OAuth registration prompt for a server that worked fine from the user mcp.json.
3. 3 On 1.124.0 or later with the header still missing from the wire, run Developer: Set Log Level > Trace and read the MCP output. That is the exact check VS Code used to verify the fix.
4. 4 Add an oauth object with clientId only when you actually want the OAuth flow; it is a separate field from headers, not a fallback for it.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "api-token",
      "description": "MCP server API token",
      "password": true
    }
  ],
  "servers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:api-token}"
      }
    }
  }
}

If you connect from Claude Code

1. 1 Add the header at the CLI with claude mcp add --transport http <name> <url> --header "Authorization: Bearer your-token"; -t and -H are the short forms. In .mcp.json the same thing is headers on an entry whose type is http, and ${VAR} or ${VAR:-default} expand from the environment.
2. 2 The documented precedence is the opposite of Cursor's: if you configured headers.Authorization and the server rejects it, Claude Code reports the connection as failed instead of falling back to OAuth. A configured header that is not working therefore means a bad token or the wrong endpoint — or remove the header if you meant to use OAuth.
3. 3 An entry with a url and no type is read as a stdio server and skipped, with MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry. A header on a skipped server is never sent at all.
4. 4 Reports that the header never reaches the wire have come in twice, and they ended differently: anthropics/claude-code #33817, for headers, was fixed and closed in April 2026, so upgrade before you debug it. #64894, for headersHelper, was closed as stale in July 2026 without a fix. Read your own server log to see which requests actually arrive before you go looking for a server-side cause.
5. 5 For a token that must be minted per connection use headersHelper, a command that prints a JSON object of headers to stdout. Dynamic headers override static headers of the same name.

claude mcp add --transport http internal-api https://mcp.internal.example.com/mcp \
  --header "Authorization: Bearer $INTERNAL_API_KEY"

If the client is Claude, Claude Desktop, or Cowork connecting as a custom connector

1. 1 A custom connector does take static headers — the Request headers section of the Add custom connector dialog, in beta at the time of writing and rolled out per customer. An organisation administrator enters the value once, Claude sends it verbatim on every request, and the name has to come from an allowlist that includes authorization, x-api-key and x-auth-token. Up to four.
2. 2 Headers and OAuth are not exclusive: a header configured on an OAuth connection is sent alongside the bearer token, which is how a routing or tenant header reaches a gateway. Authorization is the documented exception — "OAuth owns that header, so it cannot be configured as a request header on an OAuth connection". That is this error, in the one place the vendor writes it down: if the server advertises discovery, the connector authenticates with OAuth and your Authorization value is not sent.
3. 3 So pick one per connection. For a shared service account, stop advertising OAuth discovery on that route and configure authorization as a request header. For per-user identity, use OAuth and move the static credential to a different header name.
4. 4 Claude sends the value exactly as entered and adds no scheme, so an authorization header needs Bearer typed in front of the token, including the space.
5. 5 The connection is made from Anthropic's cloud, not from the machine running the app, so an internal server also has to be reachable from there.

If your server is built on the MCP Python SDK and you want it to accept static keys

1. 1 token_verifier= and auth=AuthSettings(...) are what publish discovery. Passing them mounts /.well-known/oauth-protected-resource/mcp and makes an unauthenticated request answer 401 with WWW-Authenticate: Bearer error="invalid_token", …, resource_metadata="…". That pointer is exactly what clients follow instead of your header.
2. 2 Drop both. They have to travel together — pass one without the other and the constructor raises ValueError — so an API-key check belongs in ASGI middleware in front of the MCP app, with no auth= at all.
3. 3 Answer an unauthenticated request with a plain 401, and if you send WWW-Authenticate at all, send Bearer with no resource_metadata parameter.
4. 4 The class is MCPServer in v2 (2.0.0rc1) and FastMCP in the 1.x line, which is still the recommended production release; the token_verifier= / auth=AuthSettings(...) pair is the same in both.

# Publishes discovery — clients will follow it instead of your header
mcp = MCPServer(
    "Notes",
    token_verifier=StaticTokenVerifier(),
    auth=AuthSettings(
        issuer_url=AnyHttpUrl("https://auth.example.com"),
        resource_server_url=AnyHttpUrl("https://mcp.example.com/mcp"),
        required_scopes=["notes:read"],
    ),
)

# Static-key server: no auth=, no token_verifier=, no well-known route
mcp = MCPServer("Notes")

If your server is built on the MCP TypeScript SDK

1. 1 Two calls put you in the discovery flow. resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(mcpServerUrl) on requireBearerAuth is what stamps resource_metadata onto the 401 challenge, and the SDK docs say plainly that this challenge is what starts a client's OAuth flow.
2. 2 mcpAuthMetadataRouter({ oauthMetadata, resourceServerUrl }) is what serves the documents, at /.well-known/oauth-protected-resource/mcp and a root /.well-known/oauth-authorization-server mirror for clients that probe the origin directly. Mount neither on a route that expects a static key — verify the key in your own middleware and return a 401 with no resource_metadata.
3. 3 For a server that must serve both, keep the metadata router and the token-gated route on one path and the key-checked route on another. Then confirm the root authorization-server mirror is not answering for the key-checked path, because a root document is found for every path on the host.
4. 4 On web-standard hosts — Workers, Deno, Bun, Hono — the same two pieces are requireBearerAuth from @modelcontextprotocol/server and oauthMetadataResponse.

// This is the line that advertises discovery on the 401
const auth = requireBearerAuth({
  verifier,
  requiredScopes: ['mcp'],
  resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(mcpServerUrl)
});

// Static-key route: omit resourceMetadataUrl, and do not mount
// mcpAuthMetadataRouter on this path.

Something else

Every client that can present a static header has to choose between it and whatever discovery says, and no spec text settles the order — so fix this on the server, not in the client. Decide per route: a route authenticated by a static header publishes no protected-resource metadata and puts no resource_metadata on its 401, and a route running the spec OAuth flow does both. Then check whatever sits in front of the server — a proxy, an ingress rule, framework middleware — is not serving a root /.well-known/oauth-protected-resource document, because a root document is found for every path on the host.