Clarify JSON-RPC error code for 'session not found' responses

[maxisbey]

Summary

The Python SDK and TypeScript SDK use different JSON-RPC error codes for "session not found" responses (HTTP 404). The MCP specification does not define which error code to use, and there are deeper questions about whether MCP should be using certain error code ranges at all.

This issue tracks the need for spec clarification and subsequent SDK alignment.

---

Current State

What the Spec Says

The Streamable HTTP transport spec defines the HTTP status code but not the JSON-RPC error code:

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.

The spec is silent on what JSON-RPC error code (if any) should be in the response body.

SDK Implementations

SDK	HTTP Status	JSON-RPC Error Code	id Field
TypeScript	404	-32001	null
Python	404	-32600 (INVALID_REQUEST)	"server-error"

TypeScript SDK (packages/server/src/server/streamableHttp.ts, validateSession method):

if (sessionId !== this.sessionId) {
    // Reject requests with invalid session ID with 404 Not Found
    return this.createJsonErrorResponse(404, -32_001, 'Session not found');
}

Where createJsonErrorResponse always sets id: null.

Python SDK (src/mcp/server/streamable_http_manager.py, lines 244-250):

# Unknown or expired session ID - return 404 per MCP spec
# TODO: Align error code once spec clarifies
# See: https://github.com/modelcontextprotocol/python-sdk/issues/1821
error_response = JSONRPCError(
    jsonrpc="2.0",
    id="server-error",
    error=ErrorData(
        code=INVALID_REQUEST,  # -32600
        message="Session not found",
    ),
)

The id Field Problem

In addition to the error code divergence, the Python SDK uses id: "server-error" which appears to violate the JSON-RPC 2.0 specification:

If there was an error in detecting the id in the Request object (e.g. Parse error/Invalid Request), it MUST be Null.

When rejecting a request at the session/transport level (before parsing individual JSON-RPC messages), the server cannot determine a request id. Per the spec, id MUST be null in this case. The TypeScript SDK correctly uses null.

---

The Deeper Problem

JSON-RPC Error Code Ranges

Per the JSON-RPC 2.0 specification:

Range	Reserved For
-32700 to -32600	Standard JSON-RPC errors (Parse error, Invalid Request, etc.)
-32000 to -32099	Implementation-defined server errors (i.e., JSON-RPC library implementations)
Everything else	Application-defined errors

The Issue with MCP's Error Codes

Spec Issue #509 points out that MCP incorrectly uses error codes in the -32000 to -32099 range. This range is reserved for JSON-RPC library implementations, not applications like MCP. Since MCP is an application built on top of JSON-RPC, it should use codes outside this reserved range.

However, both SDKs already use this range:

• TypeScript: -32000 (ConnectionClosed), -32001 (RequestTimeout / Session not found)
• Python: -32000 (CONNECTION_CLOSED), -32042 (URL_ELICITATION_REQUIRED)

Current Error Codes in Schema (2025-11-25)

The MCP schema only defines these error codes:

// Standard JSON-RPC (correct usage)
export const PARSE_ERROR = -32700;
export const INVALID_REQUEST = -32600;
export const METHOD_NOT_FOUND = -32601;
export const INVALID_PARAMS = -32602;
export const INTERNAL_ERROR = -32603;

// MCP-specific (in the problematic reserved range)
export const URL_ELICITATION_REQUIRED = -32042;

No error code is defined for "session not found".

Note: The draft schema (via merged PR #2038) now adds typed interfaces (ParseError, InvalidRequestError, MethodNotFoundError, InvalidParamsError, InternalError) with doc comments for each standard error code, but does not add any new MCP-specific error codes.

---

Related Issues and PRs

MCP Spec Repo

Issue/PR	Title	Status
#509	spec defines improper error codes	Open
#1545	Change invalid resource URI error code from -32002 to -32602	Open
#2164	SEP-2164: Standardize resource not found error code (-32602)	Open
#1549	Make schema.ts source of truth for error codes	Closed (superseded by #2038, merged)
#2038	Upgrade Schema Reference page (typed error interfaces)	Merged
#1398	Streamable HTTP: clarification for error cases	Open
#1442	SEP: Make MCP Stateless (proposes -32001 for session errors)	Open

Python SDK

Issue/PR	Title	Status
#1727	StreamableHTTPSessionManager returns 400 instead of 404	Closed (fixed by #1808)
#1808	fix: return HTTP 404 for unknown session IDs	Merged

TypeScript SDK

Issue/PR	Title	Status
#389	Examples use incorrect status for invalid session IDs	Open
#85	SDK errors should use -32000 to -32099	Closed

---

Questions for Spec Clarification

1. What JSON-RPC error code should be used for "session not found"?

   • TypeScript uses -32001
   • Python uses -32600 (INVALID_REQUEST)
   • SEP-1442 proposes -32001

2. Should MCP define a dedicated error code for session errors?

   • If so, should it be in the -32000 to -32099 range (current practice) or outside it (per JSON-RPC spec)?

3. What should the id field be in the error response?

   • TypeScript uses null (correct per JSON-RPC 2.0 spec)
   • Python uses "server-error" (likely a violation — see "The id Field Problem" above)
   • JSON-RPC spec says null when request ID is unknown

---

Action Items

1. Spec team: Clarify the expected JSON-RPC error code for session-related errors in the transport spec or schema
2. SDK teams: Align implementations once spec guidance is provided
3. This SDK: Fix id field to use null instead of "server-error", and update error code once spec guidance is provided

---

References

• JSON-RPC 2.0 Specification
• MCP Streamable HTTP Transport Spec
• MCP Schema (2025-11-25)