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
- 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"
}
}
}
}
- The server does NOT support OAuth but returns
{}(empty JSON) for unknown paths instead of 404.
- On connect, SDK probes
http://example:8888/.well-known/oauth-authorization-server, gets{}, cachesauthServer: http://example:8888/, then attempts OAuth token exchange which fails with 404.
- Result: server shows "needs authentication" despite valid Bearer token in config.
- Workaround:
claude mcp remove+claude mcp addclears 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-userserver with identical config sometimes works whilehindsight-sharedfails (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
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗