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 (PR #1808)	404	-32600 (INVALID_REQUEST)	"server-error"

TypeScript SDK (src/server/streamableHttp.ts:779-791):

} else if (sessionId \!== this.sessionId) {
    res.writeHead(404).end(
        JSON.stringify({
            jsonrpc: '2.0',
            error: {
                code: -32001,
                message: 'Session not found'
            },
            id: null
        })
    );
}

Python SDK (PR #1808 in src/mcp/server/streamable_http_manager.py):

error_response = JSONRPCError(
    jsonrpc="2.0",
    id="server-error",
    error=ErrorData(
        code=INVALID_REQUEST,  # -32600
        message="Session not found",
    ),
)

---

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".

---

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
#1549	Make schema.ts source of truth for error codes	Draft
#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	Open
#1808	fix: return HTTP 404 for unknown session IDs	Open

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 PR 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
   • Python PR uses "server-error"
   • 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: Update PR fix: return HTTP 404 for unknown session IDs instead of 400 #1808 or follow-up PR to match spec guidance

---

References

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