[Davien21]

Fixes #2969

The 400 comes from the client header merge, not the server. _commonHeaders() in src/client/streamableHttp.ts and src/client/sse.ts spreads the transport headers and requestInit.headers into one plain object, so mcp-protocol-version and a caller's MCP-Protocol-Version both survive and the Headers constructor joins them.

Before: with requestInit.headers: { 'MCP-Protocol-Version': '2025-03-26' } and 2025-11-25 negotiated, the client sends mcp-protocol-version: 2025-11-25, 2025-03-26 and the server answers 400.
After: it sends 2025-03-26, the same as a lowercase mcp-protocol-version already did.

The fix builds a Headers from the transport values and set()s the caller's headers on top, so names compare case-insensitively. I kept the v1.x precedence where the caller's value wins. main (#2475) puts transport headers last instead, but that also changes which Authorization gets sent, which seemed too much for a v1.x patch. With this in, #2975's server-side change isn't needed for SDK clients.

Tested: a new e2e requirement, typescript:client-transport:http:custom-header-case, connects a real client to the SDK server with a mixed-case MCP-Protocol-Version in requestInit. On v1.x it fails with the same 400 as the issue; with the change it passes. The SSE client gets a unit test for the same merge. npm test (1859), npm run test:e2e (1136), npm run typecheck, npm run lint and npm run build pass.

[changeset-bot]

🦋 Changeset detected

Latest commit: 7009366

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@modelcontextprotocol/sdk@3105

commit: 7009366

[arhancanli]

Checked the merge in plain Node (Headers semantics, same as the runtime this runs in): new Headers(transportHeaders) then new Headers(requestInit.headers).forEach(set) fixes the MCP-Protocol-Version vs mcp-protocol-version case as described.

One behaviour difference I could reproduce: when requestInit.headers is an array of tuples with the same name twice, the old normalizeHeaders went through Object.fromEntries, so the last pair won. The Headers constructor appends instead:

new Headers([['x-a','1'],['X-A','2']])            // x-a: '1, 2'
const m = new Headers({'mcp-protocol-version':'2025-11-25'});
new Headers([['MCP-Protocol-Version','a'],['mcp-protocol-version','b']]).forEach((v,k)=>m.set(k,v));
// mcp-protocol-version: 'a, b'

So a caller who passes duplicates in tuple form now sends a comma-joined value, which for mcp-protocol-version is the same 400 this PR fixes. That input is unusual, so it may be fine to leave; if you want to keep last-wins, build the caller side with normalizeHeaders first and then set each entry onto the Headers. A test with a tuple-array requestInit.headers would pin whichever behaviour you choose.

[Davien21]

Good catch @arhancanli, thank you.
Both transports now pass requestInit.headers through normalizeHeaders before setting each entry on the merged Headers, so a name repeated in tuple form keeps last-wins like before, and a case-only duplicate of a transport header still replaces it. Added a tuple-array test for SSE and Streamable HTTP that asserts the last value wins (0ca1f0b).

[arhancanli]

Read 0ca1f0b: routing both through normalizeHeaders and then merged.set per entry restores last-wins for tuple arrays, and since Headers.set is case-insensitive the [[MCP-Protocol-Version, a], [mcp-protocol-version, b]] case ends on b, which is what the new test asserts in both transports. That also covers a plain object with case-only duplicates ({A: 1, a: 2}), because Object.entries keeps insertion order.

One thing I could not tell from the diff: does normalizeHeaders still copy a Headers instance by iterating it (so values already comma-joined by the caller stay as one string), or does it read it differently? If it is the former, a test with a Headers input holding a repeated name would pin that path down too.

[Davien21]

@arhancanli Yes, the former: normalizeHeaders copies a Headers instance with Object.fromEntries(headers.entries()), so a name the caller appended twice arrives as the single comma-joined value Headers already holds, same as before this PR. Added a test for that in both transports (7009366).

[arhancanli]

Read 7009366: both tests append X-Trace twice with different casing and assert get('x-trace') is a, b, so the Headers-instance path is pinned in SSE and Streamable HTTP. That matches the runtime semantics (Headers joins on append with ", " and entries() yields the joined string), so nothing further from my side on the header merge.