MCP HTTP transport: SDK attempts OAuth discovery even when Bearer token headers are configured

Resolved 💬 3 comments Opened May 5, 2026 by julgr Closed May 9, 2026

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.
  1. 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.
  1. Result: server shows "needs authentication" despite valid Bearer token in config.
  1. 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

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗