Repository navigation
Description
Summary
The server packages answer several transport-level failures with JSON-RPC code -32000, including on the 2026-07-28 path. That revision marks -32000 to -32019 as legacy and says new implementations should not use it.
Spec
MCP 2026-07-28, Overview › Error Codes:
-32000to-32019— legacy. Codes in this sub-range were allocated by implementations before this policy was introduced. New codes MUST NOT be allocated in this sub-range, and new implementations SHOULD NOT use codes from this sub-range at all. Apart from-32002(see below), receivers MUST NOT assume any specific meaning for these codes.
and, for codes with no defined meaning:
New error codes for purposes not defined by this specification SHOULD be allocated outside the JSON-RPC reserved range (
-32768to-32000); the remainder of the integer space is available for application-defined errors.
The body is optional in both cases below: Streamable HTTP › Security & Endpoint says the 403 body "MAY comprise a JSON-RPC error response that has no id", and Backward Compatibility asks only for 405 Method Not Allowed on GET or DELETE.
Where
Seen in @modelcontextprotocol/server 2.4.0, @modelcontextprotocol/express 2.0.2 and @modelcontextprotocol/node 2.1.2 (dist/):
server:modernOnlyStrictRejection→new ProtocolError(-32e3, "Method not allowed.")for a non-POST request on a modern-only endpoint, andjsonRpcErrorResponse(405, -32e3, "Method not allowed.")on the dual-era handler.expressandnode: the host and origin validation middleware answer 403 withcode: -32e3.server: the handshake-era streamable transport uses-32e3for 400 / 403 / 406 / 409 / 413 / 415 responses. That is legacy behaviour and probably has to stay for those revisions.
Reproduce
Serve any server with createMcpHandler behind createMcpExpressApp({ host: '127.0.0.1' }), then:
curl -i -X GET http://127.0.0.1:3000/mcp
# HTTP/1.1 405 Method Not Allowed
# {"jsonrpc":"2.0","error":{"code":-32000,"message":"Method not allowed."},"id":null}
curl -i -X POST http://127.0.0.1:3000/mcp -H 'Origin: https://evil.example' \
-H 'Content-Type: application/json' -H 'MCP-Protocol-Version: 2026-07-28' -H 'Mcp-Method: server/discover' \
-d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'
# HTTP/1.1 403 Forbidden
# {"jsonrpc":"2.0","error":{"code":-32000,"message":"Invalid Origin: evil.example"},"id":null}Suggestion
For responses not tied to a handshake revision (the modern-only rejections and the host / origin middleware), use a standard code such as -32600 (Invalid Request), or send no JSON-RPC body. Keep -32000 where a handshake-era client may depend on it.
This is a SHOULD NOT, and nothing breaks today, so it is low priority. Filing it so the modern path does not carry the legacy code forward.
Activity
Shanmukh-l33t commentedon Nov 15, 2026
Where the legacy code comes from
Three transport-level rejection sites answer with
-32000on the2026-07-28path (line numbers frommainat 919bb8e):packages/core-internal/src/shared/inboundClassification.ts:984:modernOnlyStrictRejectionreturnsnew ProtocolError(-32_000, 'Method not allowed.')for a non-POST request on an endpoint with no legacy serving. Thehttp-methodrung descriptor inINBOUND_VALIDATION_LADDERpins the same code at line 266.packages/server/src/server/middleware/hostHeaderValidation.ts:59andpackages/server/src/server/middleware/originValidation.ts:97: the web-standard403bodies.403body copied per adapter:packages/middleware/express/src/middleware/hostHeaderValidation.ts:30andoriginValidation.ts:30,fastify29 and 30,hono16 and 20,node37 and 38.Spec basis
Overview, Error Codes,
2026-07-28:and, for codes with no defined meaning:
Streamable HTTP, Security and Endpoint, makes the
403body optional ("MAY comprise a JSON-RPC error response that has noid"), and Backward Compatibility asks only for405 Method Not Allowedon GET or DELETE, so the status codes stay as they are and only the body code moves.Change
Each site now answers
-32600(Invalid Request), the standard code the reporter suggested, instead of-32000. Status codes,Allow: POSTon the405, messages and the nullidare unchanged, so a client reading the error keeps working and only the number moves out of the legacy sub-range.Evidence
RED first, on unmodified
main: the new filepackages/server/test/server/modernTransportErrorCodes.test.tsreportedTests 3 failed | 1 passed (4). The three failures were the modern-only405, the Host403and the Origin403, eachexpected -32600 but received -32000. The fourth test, which asserts the handshake-era stateless leg still answers-32000, passed.GREEN after the change:
Tests 4 passed (4)in that file. Full suites, one run per touched package: core-internal 1853 passed (78 files), server 679 passed (56 files), express 45 passed (3), fastify 23 passed (2), hono 18 passed (2), node 105 passed (5). Thetypecheckandlintscripts are clean in each of the six packages.Tests that pinned the old number were updated with it:
inboundClassification.test.ts,inboundLadderCellSheet.test.ts,createMcpHandler.test.ts(thelegacy: 'reject'cell only),originValidation.test.tsin server and in the express, fastify and hono adapters,express.test.ts,fastify.test.ts,hono.test.ts,node/test/validation.test.ts.Not changed, deliberately
packages/server/src/server/streamableHttp.ts: the handshake-era transport keeps-32000for 400, 403, 406, 409, 413, 415 and 500.packages/server/src/server/createMcpHandler.ts:339: the stateless legacy leg keeps-32000for GET and DELETE. This is the leg the first repro actually reaches, because acreateMcpHandlerdefault posture serves GET and DELETE there. A modern-only endpoint (legacy: 'reject') answers-32600. Hand-written modern-only legacy serving is what moves.createMcpHandler.ts:957and966,packages/middleware/node/src/toNodeHandler.ts:162,packages/middleware/hono/src/hono.ts:142: the 413 and 415 answers on the era-shared request read path. They mirror the legacy transport codes and are outside what this issue describes; say so if you want them moved in a follow-up.Judgement call for review
-32600rather than a fresh application-defined code. The spec's allocation rule covers codes for purposes it does not define, and-32600is already defined, is what the reporter proposed, and needs no new constant for a rejection that means exactly "this request is not valid here". If you would rather keep transport rejections out of the JSON-RPC semantic codes entirely, a code in the application range outside-32768to-32000(for example4000) is a one-line change per site.Branch
https://github.com/modelcontextprotocol/typescript-sdk/compare/main...Shanmukh-l33t:typescript-sdk:fix/modern-transport-error-codes?expand=1
Commit: 7a7e502 (
fix(server,middleware,core-internal): drop the legacy -32000 from modern transport rejections), with a changeset covering the six packages.The branch is ready and the PR can be opened the moment a maintainer assigns or invites it.
AI assistance disclosure: this branch and this comment were prepared with AI assistance (Hermes Agent) and reviewed by a human before posting.
media-ctrl commentedon Nov 15, 2026