[mcp-adapters] MultiServerMCPClient should enhance MCPClientError to expose WWW-Authenticate header when receiving a 401 error

[embesozzi]

Feature Description

The MCP Server is protected by OAuth 2.0 [1] and typically acts as an OAuth 2.0 resource server. According to the OAuth 2.0 standard, when the resource server returns an error, it should include a WWW-Authenticate header [2].

[1] https://modelcontextprotocol.io/specification/2025-03-26
[2] https://www.rfc-editor.org/rfc/rfc6750.html

Use Case

When the MCP Server fails, it currently returns a MCPClientError just with generic 401 error without exposing the WWW-Authenticate header. This makes it difficult for clients to understand the reason for the failure and to react accordingly -such as initiating step-up authentication or requesting additional scopes. The server should expose the header so that the MCP client can properly handle the error in compliance with the OAuth 2.0 specification.

Proposed Solution

Add to error the WWW-Authenticate header.

if (error.name === "MCPClientError") {
   // Handle connection issues
   console.error(`Connection error (${error.serverName}):`, error.message , error.headers);
}

[benjamincburns]

Thanks for the excellent write-up, @embesozzi! I'll try to get to this within the week, unless someone beats me to it with a PR first.

[benjamincburns]

Migrating issues over to langchainjs monorepo, as we've moved this project over there.

[benjamincburns]

@embesozzi unfortunately the TypeScript MCP SDK does not expose HTTP response headers when it throws errors related to HTTP response codes. It instead allows for OAuth authentication via a different mechanism, the authProvider option on StreamableHTTPClientTransport and SSEClientTransport.

See changes in #8239 for more info.

[embesozzi]

@benjamincburns OK, I'll explore those approaches. In parallel, I created a new discussion in the MCP repo to highlight that, since we're talking about OAuth 2.0, this will likely be a common requirement to support as a feature.