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
- Lenguaje dominante
- Python
- Estrellas
- 145k
- Forks
- 23.1k
- Métricas de merge de PR
- Métricas de PR pendientes
Descripción
### 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.
Guía de contribución
No hay ninguna guía de contribución indexada para este repositorio
Línea de trabajo
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.
Escrito por el modelo de indexación a partir del texto del issue.
Evaluación
- Área
- api, cli
- Tipo de issue
- Error
- Dificultad
- 4/5
- Tiempo estimado
- 3-5 días
- Estado de actividad
- Activo
- Claridad
- Bastante claro
- Aptitud para principiantes
- 52/100