Skip to content

Server answers transport errors with legacy code -32000 on the 2026-07-28 path #3185

Open

Description

@elgorro

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:

-32000 to -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 (-32768 to -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, and jsonRpcErrorResponse(405, -32e3, "Method not allowed.") on the dual-era handler.
  • express and node: the host and origin validation middleware answer 403 with code: -32e3.
  • server: the handshake-era streamable transport uses -32e3 for 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

  1. added
    v2Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes
    on Nov 15, 2026
  2. Shanmukh-l33t commented on Nov 15, 2026

    @Shanmukh-l33t

    Where the legacy code comes from

    Three transport-level rejection sites answer with -32000 on the 2026-07-28 path (line numbers from main at 919bb8e):

    1. packages/core-internal/src/shared/inboundClassification.ts:984: modernOnlyStrictRejection returns new ProtocolError(-32_000, 'Method not allowed.') for a non-POST request on an endpoint with no legacy serving. The http-method rung descriptor in INBOUND_VALIDATION_LADDER pins the same code at line 266.
    2. packages/server/src/server/middleware/hostHeaderValidation.ts:59 and packages/server/src/server/middleware/originValidation.ts:97: the web-standard 403 bodies.
    3. The same 403 body copied per adapter: packages/middleware/express/src/middleware/hostHeaderValidation.ts:30 and originValidation.ts:30, fastify 29 and 30, hono 16 and 20, node 37 and 38.

    Spec basis

    Overview, Error Codes, 2026-07-28:

    -32000 to -32019 are 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.

    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 (-32768 to -32000).

    Streamable HTTP, Security and Endpoint, makes the 403 body optional ("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, 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: POST on the 405, messages and the null id are 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 file packages/server/test/server/modernTransportErrorCodes.test.ts reported Tests 3 failed | 1 passed (4). The three failures were the modern-only 405, the Host 403 and the Origin 403, each expected -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). The typecheck and lint scripts 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 (the legacy: 'reject' cell only), originValidation.test.ts in 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 -32000 for 400, 403, 406, 409, 413, 415 and 500.
    • packages/server/src/server/createMcpHandler.ts:339: the stateless legacy leg keeps -32000 for GET and DELETE. This is the leg the first repro actually reaches, because a createMcpHandler default 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:957 and 966, 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

    -32600 rather than a fresh application-defined code. The spec's allocation rule covers codes for purposes it does not define, and -32600 is 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 -32768 to -32000 (for example 4000) 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.

  3. media-ctrl commented on Nov 15, 2026

    @media-ctrl
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    v2Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions