modelcontextprotocol / modelcontextprotocol/conformance

Add conformance tests for client session renegotiation on 404

Open
#76 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
127
Forks
101
Avg merge
6d 1h
Merged PRs (30d)
7

Description

Background

From Discord discussion: Many client applications do not properly handle session renegotiation when a server returns 404 for an invalid/expired session. The spec is clear on the expected behavior:

The server MAY terminate the session at any time, after which it MUST respond to requests containing that session ID with HTTP 404 Not Found.

When a client receives HTTP 404 in response to a request containing an MCP-Session-Id, it MUST start a new session by sending a new InitializeRequest without a session ID attached.

Problem

In practice, many major clients "brick" the server for the rest of a trajectory when this happens, rather than renegotiating the session. This affects:

  • Remote servers that are redeployed (especially with in-memory sessions that don't persist on restarts)
  • Servers that invalidate sessions when tools change on deploy
  • Any server that needs to terminate sessions for operational reasons

Requested Conformance Tests

Add client conformance tests that verify:

  1. Session 404 handling: When a server returns 404 for a request with MCP-Session-Id, the client MUST:

    • Start a new session by sending InitializeRequest without a session ID
    • Continue operating normally after renegotiation
  2. Mid-trajectory session loss: Client should handle session termination gracefully during an active agent trajectory, not fail permanently

SDK Status

  • Python SDK: Appears to explicitly emit an error on 404 rather than auto-reconnect (code)
  • TypeScript SDK: Behavior unclear, may have been missed

There's a question of whether auto-reconnect should happen at the SDK level or be an SDK consumer decision. Either way, conformance tests would help clarify expectations and catch clients that don't handle this correctly.

Related

This is distinct from the optional GET request/SSE support - proper 404 handling should work without those features.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the existing client conformance tests in this TypeScript repository, then compare their session setup with the Python SDK path src/mcp/client/streamable_http.py around lines 309-317. Add coverage for a 404 response carrying MCP-Session-Id and for session loss during an active trajectory, with completion defined by a new InitializeRequest without the old session ID and continued operation.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, typescript
Domain
api, testing-qa
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.