anthropics / anthropics/claude-code

[BUG] HTTP MCP client appears to send an unexpected MCP-Protocol-Version header after initialize, causing spec-compliant servers to reject all follow-up requests

Aperta
#92,835 1 commento 0 reazioni 0 assegnatari Vedi su GitHub
area:mcp bug has repro platform:vscode platform:windows
Lingua principale
Python
Stelle
145k
Fork
23.1k
Metriche di merge delle PR
Metriche PR in attesa

Descrizione

### Preflight Checklist

- [x] I have searched [existing issues](https://github.com/anthropics/claude-code/issues?q=is%3Aissue%20state%3Aopen%20label%3Abug) and this hasn't been reported yet
- [x] This is a single bug report (please file separate reports for different bugs)
- [x] I am using the latest version of Claude Code

### What's Wrong?

Claude Code successfully completes the `initialize` handshake with an HTTP MCP server, but subsequent MCP requests fail because the protocol version used after initialization does not match the version negotiated during `initialize`.

In our case, the HelpNDoc 10.8.0.452 built-in MCP server negotiates:

`protocolVersion: "2024-11-05"`

and issues an `Mcp-Session-Id`.

However, subsequent requests such as `tools/list` are rejected with HTTP 400, with the server reporting that the request uses `MCP-Protocol-Version: 2025-11-25` instead of the negotiated `2024-11-05`.

As a result, `claude mcp list` reports the server as "Connected", but zero HelpNDoc tools become available inside an actual interactive Claude Code session.

We did not capture Claude Code's raw outgoing request headers directly, so we cannot state with certainty exactly how the header is constructed. However, the server consistently reports `2025-11-25` as the request-header protocol version after successfully negotiating `2024-11-05` during `initialize`.

### What Should Happen?

After `initialize` successfully negotiates a protocol version with an MCP server, Claude Code's HTTP MCP client should use that negotiated protocol version for subsequent requests in the same session.

In this case, after the server negotiates `protocolVersion: "2024-11-05"`, subsequent requests such as `tools/list` should use:

`MCP-Protocol-Version: 2024-11-05`

The server should remain usable after initialization, and its tools should appear and be callable inside the interactive Claude Code session.

### Error Messages/Logs

```shell
Without forcing a custom MCP-Protocol-Version header, the HelpNDoc MCP server rejects the follow-up request with:

{"error": "Protocol version mismatch: request header \"2025-11-25\" does not match the version \"2024-11-05\" negotiated for this session"}

We also tried forcing the negotiated version using:

claude mcp add --transport http HelpNDoc http://localhost:8933/mcp -H "MCP-Protocol-Version: 2024-11-05"

After doing this, `claude mcp list` fails with:

HTTP 400: Error POSTing to endpoint: {"error": "Unsupported protocol version: 2025-11-25, 2024-11-05"}

This is consistent with Claude Code adding its own `2025-11-25` value in addition to the explicitly configured header rather than replacing it.
```

### Steps to Reproduce

1. Install HelpNDoc 10.8.0.452 on Windows and open a HelpNDoc project.

2. Start its built-in MCP server on the default port 8933 (Tools → Start MCP server).

3. Register the server in Claude Code:

claude mcp add --transport http HelpNDoc http://localhost:8933/mcp

4. Run:

claude mcp list

The server is reported as "Connected".

5. Start an interactive Claude Code session. No HelpNDoc MCP tools appear or can be called.

6. Test the MCP endpoint manually. The `initialize` request succeeds, the server returns HTTP 200, negotiates:

protocolVersion: "2024-11-05"

and returns an `Mcp-Session-Id`.

7. Send a subsequent `tools/list` request for the same session without manually specifying an `MCP-Protocol-Version` header.

The server returns HTTP 400 and reports:

{"error": "Protocol version mismatch: request header \"2025-11-25\" does not match the version \"2024-11-05\" negotiated for this session"}

8. Repeat the same manual `tools/list` request, but explicitly send:

MCP-Protocol-Version: 2024-11-05

The request succeeds with HTTP 200 and the full HelpNDoc tool list is returned.

9. As an additional test, try configuring Claude Code with the negotiated protocol version explicitly:

claude mcp add --transport http HelpNDoc http://localhost:8933/mcp -H "MCP-Protocol-Version: 2024-11-05"

Claude Code then fails with:

HTTP 400: Error POSTing to endpoint: {"error": "Unsupported protocol version: 2025-11-25, 2024-11-05"}

### Claude Model

Sonnet (default)

### Is this a regression?

I don't know

### Last Working Version

_No response_

### Claude Code Version

2.1.263

### Platform

Anthropic API

### Operating System

Windows

### Terminal/Shell

VS Code integrated terminal

### Additional Information

Server environment:

- MCP server: HelpNDoc 10.8.0.452 built-in MCP server
- Server-negotiated MCP protocol version: `2024-11-05`
- Transport: Streamable HTTP (`--transport http`)
- MCP endpoint: `http://localhost:8933/mcp`
- OS: Windows Server 2022
- Claude Code and HelpNDoc run on the same Windows Server machine and communicate over localhost.
- Claude Code is used both through the CLI and the VS Code extension.
- The same behavior was reproduced with Claude Code 2.1.191 before upgrading to 2.1.263.

HelpNDoc is a real third-party MCP server, not a custom test implementation.

The fact that a manually issued `tools/list` request succeeds immediately when `MCP-Protocol-Version: 2024-11-05` is explicitly supplied suggests that the server and its tools are otherwise functioning correctly.

We can provide additional request/response logs or perform further protocol-level diagnostics if needed.

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

Direzione di ricerca

Start by tracing the HTTP MCP client from the initialize request to the subsequent tools/list request, using the reproduced HelpNDoc endpoint and protocol-version mismatch logs. Compare the negotiated version with the headers sent afterward, including the case with a manually configured header. Done means follow-up requests use the negotiated version and do not send duplicate conflicting values.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Ambito
api, cli
Tipo di issue
Bug
Difficoltà
4/5
Tempo stimato
3-5 giorni
Stato di attività
Attiva
Chiarezza
Abbastanza chiara
Idoneità per principianti
52/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.