Repository navigation
SDK overwrites custom Accept headers unconditionally #1646
Description
Bug Report: MCP SDK Overwrites Custom Accept Headers
Summary
The MCP SDK unconditionally overwrites custom Accept headers provided in MCP server configurations, breaking API endpoints that require specific Accept header values.
Environment
- SDK Version: 1.17.4
- Package:
@modelcontextprotocol/sdk - File:
package/dist/esm/client/streamableHttp.js - Line: Variable (exact line varies by version)
Bug Description
When configuring MCP servers with custom headers (e.g., specific Accept headers for different API endpoints), the SDK overwrites these headers with its own default value:
headers.set("accept", "application/json, text/event-stream");This happens regardless of any custom headers provided in the MCP server configuration.
Steps to Reproduce
- Configure an MCP server with custom Accept headers:
{
"mcpServers": {
"example-api": {
"url": "https://api.example.com/mcp",
"headers": {
"Accept": "application/vnd.example.v1+json"
}
}
}
}-
The SDK will overwrite the Accept header to:
"accept": "application/json, text/event-stream" -
This breaks APIs that require specific Accept header values.
Expected Behavior
Custom Accept headers provided in MCP server configurations should be preserved and not overwritten by the SDK.
Actual Behavior
The SDK overwrites custom Accept headers with its own default value, breaking API compatibility.
Impact
This bug affects:
- MCP servers that require specific Accept headers
- Custom API integrations
- Vision and specialized AI tools that depend on specific media types
Affected Code
File: node_modules/@modelcontextprotocol/sdk/package/dist/esm/client/streamableHttp.js
Snippet:
// This line overwrites custom Accept headers
headers.set("accept", "application/json, text/event-stream");Proposed Solutions
Option 1: Conditionally Set Accept Header
Only set the default Accept header if none is already present:
if (!headers.has("accept")) {
headers.set("accept", "application/json, text/event-stream");
}Option 2: Allow Configuration Override
Add a configuration option to control whether the SDK should set default headers.
Option 3: Merge Headers
Merge SDK headers with custom headers instead of overwriting them.
Additional Context
This bug affects zai-cli and other tools that rely on MCP servers with custom Accept headers. The issue impacts vision analysis, specialized AI tools, and custom API integrations.
Activity
russianoracle commentedon Mar 8, 2026
This issue was also identified by the zai-cli team. We've documented the workaround in: https://github.com/numman-ali/zai-cli/blob/main/packages/zai-cli/STREAMABLE_HTTP_PATCH.md
owendevereaux commentedon Mar 21, 2026
Option 1 (
if (!headers.has("accept"))) is the right fix — simple, non-breaking, and follows the principle of least surprise.The current behavior violates standard header semantics: user-provided configuration should take precedence over library defaults. It's unexpected that explicit config gets silently overwritten.
I checked the code path in
streamableHttp.ts— the fix is a one-liner. Happy to submit a PR if that'd be helpful.felixweinberger commentedon Mar 26, 2026
The
Acceptheader on these requests is spec-mandated. POST needsapplication/json, text/event-streamand GET SSE needstext/event-streamfor the transport to function. Letting users replace it outright (as in #1655) would make it easy to break the connection.That said, if your gateway needs
application/vnd.example.v1+jsonto route the request, an append approach could work: the SDK would send both your value and the required MCP types. The C# SDK does this.Could you share more about the setup? Specifically:
Accept: application/vnd.example.v1+json, application/json, text/event-stream(both values) work for your case?nielskaspers commentedon Mar 27, 2026
Thanks for the feedback @felixweinberger — the append approach makes total sense.
To answer your questions:
Use case: The custom Accept header is needed by API gateways/proxies sitting in front of MCP servers. For example, versioned APIs that route requests based on Accept headers (e.g.
application/vnd.example.v1+json) or content negotiation layers that need to see specific media types to forward correctly. The MCP server itself still needs the standard types to function.Would append work? Yes —
Accept: application/vnd.example.v1+json, application/json, text/event-streamis exactly what's needed. The gateway sees its required type, and the MCP transport still gets the spec-mandated types.I've updated #1655 to use the append approach (matching what the C# SDK does), added a changeset, and all 260 tests pass.
fix(client): preserve user-supplied Accept header instead of overwrit…
lanxevo3 commentedon Mar 28, 2026
Fixed in PR #1804 — added conditional check so custom Accept headers are preserved instead of being unconditionally overwritten.