Modern Streamable HTTP: handler-produced -32602 answers HTTP 400 instead of 200 #3855

Initial Checks

• I confirm that I'm using the newest release of my line (the latest 2.x, or the latest 1.x if I'm still on v1)
• I confirm that I searched for my issue in https://github.com/modelcontextprotocol/python-sdk/issues before opening this issue

Release line

2.x (current stable)

Description

On the 2026-07-28 (modern) Streamable HTTP path, _write picks the HTTP status from ERROR_CODE_HTTP_STATUS for every JSON-RPC error, ignoring whether it came from the request-validation ladder or from a handler. Since that table maps -32602 INVALID_PARAMS -> 400, a handler-produced "resource not found" is returned as HTTP 400, but the spec requires it in-band on HTTP 200.

-32602 legitimately needs 400 for one origin (malformed request envelope) and 200 for the other (handler error), so one code→status table cannot express the rule.

Actual: 400 {"jsonrpc":"2.0","id":7800,"error":{"code":-32602,"message":"Resource not found: 'demo://does-not-exist'",...}}

Expected: same body, HTTP 200.

Why:

• Streamable HTTP 2026-07-28 (Sending Messages item 6): a JSON-RPC request MUST return application/json or text/event-stream. Non-200 is assigned only to -32020 HeaderMismatch (400), -32021 MissingRequiredClientCapability (400), -32022 UnsupportedProtocolVersion (400), -32601 MethodNotFound (404).
• A non-existent resource is -32602 (SEP-2164, resources error handling); no HTTP status is assigned → in-band on 200.
• -32602 + 400 is required only for a malformed request envelope missing required _meta fields (basic/index, Per-request protocol fields).

Root cause — src/mcp/server/_streamable_http_modern.py, _write:

status = ERROR_CODE_HTTP_STATUS.get(msg.error.code, _OK_STATUS) if isinstance(msg, JSONRPCError) else _OK_STATUS

Handler errors reach _write via _to_jsonrpc_response; ladder rejections via _write_rejection. Both go through the same table (src/mcp/shared/inbound.py), which includes INVALID_PARAMS: 400 and whose docstring says it is consulted for "classifier-origin and handler-origin errors". That origin conflation is the bug.

Suggested fix: carry the origin into _write (flag set by _to_jsonrpc_response) and apply the spec's status table only to ladder rejections. For handler-origin errors, default to 200, applying a status only for codes the spec defines:

_HANDLER_ERROR_HTTP_STATUS = {
    HEADER_MISMATCH: 400,                    # -32020
    MISSING_REQUIRED_CLIENT_CAPABILITY: 400, # -32021
    UNSUPPORTED_PROTOCOL_VERSION: 400,       # -32022
    METHOD_NOT_FOUND: 404,                   # -32601
}

Verified locally: handler -32602 → 200, envelope -32602 → 400, Mcp-Method mismatch → 400.

Impact: any modern client reading a missing resource gets an HTTP transport error instead of the spec's in-band error. Fails MCPJam conformance check modern-resource-not-found-invalid-params.

Example Code

Minimal FastMCP app with one resource, then POST a modern resources/read for a missing URI:

import asyncio, httpx
from fastmcp import FastMCP
from fastmcp.server.auth.providers.jwt import StaticTokenVerifier

mcp = FastMCP("repro", auth=StaticTokenVerifier(
    tokens={"tok": {"client_id": "x", "scopes": ["s"]}}))

@mcp.resource(uri="demo://widget", name="w", description="d")
async def widget() -> str:
    return "<html></html>"

BODY = {"jsonrpc": "2.0", "id": 7800, "method": "resources/read",
    "params": {"uri": "demo://does-not-exist", "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {},
        "io.modelcontextprotocol/clientInfo": {"name": "t", "version": "1"}}}}
HEADERS = {"Authorization": "Bearer tok",
    "Accept": "application/json, text/event-stream",
    "Content-Type": "application/json",
    "MCP-Protocol-Version": "2026-07-28",
    "Mcp-Method": "resources/read", "Mcp-Name": "demo://does-not-exist"}

async def main():
    app = mcp.http_app(path="/mcp", stateless_http=True, json_response=True)
    async with app.lifespan(app):
        async with httpx.AsyncClient(
            transport=httpx.ASGITransport(app=app), base_url="http://test") as c:
            r = await c.post("/mcp", json=BODY, headers=HEADERS)
            print(r.status_code, r.text)

asyncio.run(main())

Python & MCP Python SDK

mcp==2.3.0, Python 3.13, modern Streamable HTTP (MCP-Protocol-Version: 2026-07-28). Reproduced via fastmcp 4.1.6, but the defect is in the SDK transport.

AI disclosure: this issue was drafted with AI assistance from a reproduction I ran locally; I have reviewed and can explain its contents.