claude-code - 💡(How to fix) Fix MCP HTTP transport: SDK attempts OAuth discovery even when Bearer token headers are configured [1 comments, 2 participants]

Description

When an MCP server is configured with type: http and explicit headers: { Authorization: "Bearer ..." }, the SDK still attempts OAuth discovery by probing /.well-known/oauth-authorization-server at the server root. If the server returns anything other than a definitive 404 (e.g., empty JSON {}), the SDK caches an authServer discovery state and repeatedly attempts OAuth flow on reconnect, ignoring the configured Bearer token.

Reproduction

1. Configure an HTTP MCP server with Bearer token auth:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "http://example:8888/mcp/endpoint",
      "headers": {
        "Authorization": "Bearer my-api-key"
      }
    }
  }
}

1. The server does NOT support OAuth but returns {} (empty JSON) for unknown paths instead of 404.

2. On connect, SDK probes http://example:8888/.well-known/oauth-authorization-server, gets {}, caches authServer: http://example:8888/, then attempts OAuth token exchange which fails with 404.

3. Result: server shows "needs authentication" despite valid Bearer token in config.

4. Workaround: claude mcp remove + claude mcp add clears the cached discovery state temporarily, but it recurs on next session or reconnect.

Expected Behavior

When headers.Authorization is already configured with a Bearer token, the SDK should:

• Skip OAuth discovery entirely, OR
• Only attempt OAuth if the initial request with the configured headers returns 401

Observed Behavior

• SDK probes for OAuth metadata regardless of existing auth headers
• If the probe returns anything parseable (even empty {}), it caches discovery state
• Subsequent connection attempts use OAuth flow instead of the configured headers
• The hindsight-user server with identical config sometimes works while hindsight-shared fails (timing/race condition in discovery)

Environment

• Claude Code CLI v1.0.x
• macOS
• MCP server: Hindsight API (Streamable HTTP transport)

MCP Log Evidence

{"debug":"Saving discovery state (authServer: http://hindclaw:8888/)","timestamp":"..."}
{"debug":"No client info found","timestamp":"..."}
{"debug":"SDK auth error: HTTP 404: Invalid OAuth error response: ZodError: [...]"}

Workaround

Server-side: return explicit 404 for /.well-known/oauth-authorization-server Client-side: remove and re-add the MCP server config