René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Clarify JSON-RPC error code for 'session not found' responses","articleBody":"## Summary\n\nThe 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.\n\nThis issue tracks the need for spec clarification and subsequent SDK alignment.\n\n---\n\n## Current State\n\n### What the Spec Says\n\nThe [Streamable HTTP transport spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) defines the HTTP status code but not the JSON-RPC error code:\n\n\u003e 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**.\n\nThe spec is silent on what JSON-RPC error code (if any) should be in the response body.\n\n### SDK Implementations\n\n| SDK | HTTP Status | JSON-RPC Error Code | `id` Field |\n|-----|-------------|---------------------|------------|\n| **TypeScript** | 404 | `-32001` | `null` |\n| **Python** | 404 | `-32600` (INVALID_REQUEST) | `\"server-error\"` |\n\n**TypeScript SDK** (`packages/server/src/server/streamableHttp.ts`, [`validateSession` method](https://github.com/modelcontextprotocol/typescript-sdk/blob/b0ef89ffaf6db8b3c52cd8919e8949b0f1da9ca4/packages/server/src/server/streamableHttp.ts#L829)):\n```typescript\nif (sessionId !== this.sessionId) {\n    // Reject requests with invalid session ID with 404 Not Found\n    return this.createJsonErrorResponse(404, -32_001, 'Session not found');\n}\n```\n\nWhere `createJsonErrorResponse` always sets `id: null`.\n\n**Python SDK** (`src/mcp/server/streamable_http_manager.py`, [lines 244-250](https://github.com/modelcontextprotocol/python-sdk/blob/b38716e/src/mcp/server/streamable_http_manager.py#L244-L250)):\n```python\n# Unknown or expired session ID - return 404 per MCP spec\n# TODO: Align error code once spec clarifies\n# See: https://github.com/modelcontextprotocol/python-sdk/issues/1821\nerror_response = JSONRPCError(\n    jsonrpc=\"2.0\",\n    id=\"server-error\",\n    error=ErrorData(\n        code=INVALID_REQUEST,  # -32600\n        message=\"Session not found\",\n    ),\n)\n```\n\n### The `id` Field Problem\n\nIn addition to the error code divergence, the Python SDK uses `id: \"server-error\"` which appears to violate the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification):\n\n\u003e If there was an error in detecting the id in the Request object (e.g. Parse error/Invalid Request), it **MUST** be Null.\n\nWhen 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`.\n\n---\n\n## The Deeper Problem\n\n### JSON-RPC Error Code Ranges\n\nPer the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification):\n\n| Range | Reserved For |\n|-------|--------------|\n| -32700 to -32600 | Standard JSON-RPC errors (Parse error, Invalid Request, etc.) |\n| -32000 to -32099 | **Implementation-defined server errors** (i.e., JSON-RPC library implementations) |\n| Everything else | Application-defined errors |\n\n### The Issue with MCP's Error Codes\n\n[Spec Issue #509](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/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.\n\nHowever, both SDKs already use this range:\n- TypeScript: `-32000` (ConnectionClosed), `-32001` (RequestTimeout / Session not found)\n- Python: `-32000` (CONNECTION_CLOSED), `-32042` (URL_ELICITATION_REQUIRED)\n\n### Current Error Codes in Schema (2025-11-25)\n\nThe MCP schema only defines these error codes:\n```typescript\n// Standard JSON-RPC (correct usage)\nexport const PARSE_ERROR = -32700;\nexport const INVALID_REQUEST = -32600;\nexport const METHOD_NOT_FOUND = -32601;\nexport const INVALID_PARAMS = -32602;\nexport const INTERNAL_ERROR = -32603;\n\n// MCP-specific (in the problematic reserved range)\nexport const URL_ELICITATION_REQUIRED = -32042;\n```\n\nNo error code is defined for \"session not found\".\n\nNote: The draft schema (via merged [PR #2038](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/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.\n\n---\n\n## Related Issues and PRs\n\n### MCP Spec Repo\n| Issue/PR | Title | Status |\n|----------|-------|--------|\n| [#509](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/509) | spec defines improper error codes | Open |\n| [#1545](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1545) | Change invalid resource URI error code from -32002 to -32602 | Open |\n| [#2164](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2164) | SEP-2164: Standardize resource not found error code (-32602) | Open |\n| [#1549](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1549) | Make schema.ts source of truth for error codes | Closed (superseded by [#2038](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2038), merged) |\n| [#2038](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2038) | Upgrade Schema Reference page (typed error interfaces) | Merged |\n| [#1398](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1398) | Streamable HTTP: clarification for error cases | Open |\n| [#1442](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1442) | SEP: Make MCP Stateless (proposes `-32001` for session errors) | Open |\n\n### Python SDK\n| Issue/PR | Title | Status |\n|----------|-------|--------|\n| [#1727](https://github.com/modelcontextprotocol/python-sdk/issues/1727) | StreamableHTTPSessionManager returns 400 instead of 404 | Closed (fixed by #1808) |\n| [#1808](https://github.com/modelcontextprotocol/python-sdk/pull/1808) | fix: return HTTP 404 for unknown session IDs | Merged |\n\n### TypeScript SDK\n| Issue/PR | Title | Status |\n|----------|-------|--------|\n| [#389](https://github.com/modelcontextprotocol/typescript-sdk/issues/389) | Examples use incorrect status for invalid session IDs | Open |\n| [#85](https://github.com/modelcontextprotocol/typescript-sdk/issues/85) | SDK errors should use -32000 to -32099 | Closed |\n\n---\n\n## Questions for Spec Clarification\n\n1. **What JSON-RPC error code should be used for \"session not found\"?**\n   - TypeScript uses `-32001`\n   - Python uses `-32600` (INVALID_REQUEST)\n   - SEP-1442 proposes `-32001`\n\n2. **Should MCP define a dedicated error code for session errors?**\n   - If so, should it be in the `-32000` to `-32099` range (current practice) or outside it (per JSON-RPC spec)?\n\n3. **What should the `id` field be in the error response?**\n   - TypeScript uses `null` (correct per JSON-RPC 2.0 spec)\n   - Python uses `\"server-error\"` (likely a violation — see \"The `id` Field Problem\" above)\n   - JSON-RPC spec says `null` when request ID is unknown\n\n---\n\n## Action Items\n\n1. **Spec team**: Clarify the expected JSON-RPC error code for session-related errors in the transport spec or schema\n2. **SDK teams**: Align implementations once spec guidance is provided\n3. **This SDK**: Fix `id` field to use `null` instead of `\"server-error\"`, and update error code once spec guidance is provided\n\n---\n\n## References\n\n- [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)\n- [MCP Streamable HTTP Transport Spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management)\n- [MCP Schema (2025-11-25)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-11-25/schema.ts)\n","author":{"url":"https://github.com/maxisbey","@type":"Person","name":"maxisbey"},"datePublished":"2025-12-31T13:47:11.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":1},"url":"https://github.com/1821/python-sdk/issues/1821"}