You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[v2] Every inbound message is re-classified with up to four full zod parses after the transport already parsed it #3189
On a Streamable HTTP server, each inbound JSON-RPC request goes through five zod schema walks before its handler runs, though its kind is settled by the first one. Line references are at 919bb8e (main); 2.4.0 behaves the same.
The transport parses the message with JSONRPCMessageSchema.parse (packages/server/src/server/streamableHttp.ts:838-839). That union's first member is JSONRPCRequestSchema, so this parse has already established that the message is a request.
Protocol's onmessage (packages/core-internal/src/shared/protocol.ts:838-845) discards that result and classifies the message again with the guards in types/guards.ts. Each guard is a full safeParse. For a request this runs isJSONRPCResultResponse (fails), then isJSONRPCErrorResponse (fails), then isJSONRPCRequest (succeeds): three more walks. A notification gets four.
Dispatch validates the request again through the era codec (protocol.ts:1887, validateRequest).
The three parses in step 2 do no work that step 1 hasn't already done. On our server (@modelcontextprotocol/server 2.4.0, about 1000 concurrent sessions), zod accounts for 6.8% of server CPU in a profile, and this classification chain is a large share of it.
What did you expect?
Each message is classified once. Two options:
Have the transport pass on the kind it already parsed, so onmessage doesn't classify again.
Or classify by key presence (method with id, method without id, result, error) and run only the one schema those keys select.
Either option keeps validation strict and drops two or three full parses from every inbound message.
Related: #3178 asks for pluggable protocol validation, mainly to reduce bundle size, and lists skipping inbound validation as one option. This issue is narrower. It asks for no new API, only for each message to be parsed once rather than three to five times.
Code to reproduce
Every inbound message takes this path, with no conditions. POST any request (for example tools/call) to a McpServer on StreamableHTTPServerTransport and step through streamableHttp.ts:838 → protocol.ts:838-845 → protocol.ts:1887. The guard chain in onmessage runs on every message the transport delivers, after the transport has already parsed it with JSONRPCMessageSchema.
SDK version
@modelcontextprotocol/server 2.4.0 (also present on main at 919bb8e)
We encountered this exact bottleneck when profiling high-throughput MCP server transports under sustained JSON-RPC traffic. The sequential fallback across types/guards.ts (isJSONRPCResultResponse -> isJSONRPCErrorResponse -> isJSONRPCRequest -> isJSONRPCNotification) forces multiple backtracking safeParse passes on every single incoming frame.
Classifying by envelope key presence prior to schema validation drops those redundant walks entirely while maintaining strict runtime validation.
Here is a minimal, zero-dependency discriminator that resolves the variant in $O(1)$ and invokes only the selected schema:
exporttypeJsonRpcVariant='request'|'notification'|'response'|'invalid';/** * Fast O(1) envelope discriminator by structural key presence. * Directs inbound payloads to the exact matching schema without union backtracking. */exportfunctiondiscriminateJsonRpc(raw: unknown): JsonRpcVariant{if(typeofraw!=='object'||raw===null||Array.isArray(raw)){return'invalid';}constobj=rawasRecord<string,unknown>;// Strict JSON-RPC 2.0 version assertionif(obj.jsonrpc!=='2.0'){return'invalid';}// Response: must have 'result' or 'error' and an idif('result'inobj||'error'inobj){if('id'inobj&&(typeofobj.id==='string'||typeofobj.id==='number'||obj.id===null)){return'response';}return'invalid';}// Request or Notification: must have string 'method'if('method'inobj&&typeofobj.method==='string'&&obj.method.length>0){// Request has an id (string | number)if('id'inobj){if(typeofobj.id==='string'||typeofobj.id==='number'){return'request';}return'invalid';}// Notification has NO id propertyreturn'notification';}return'invalid';}
Integrating into Protocol.onmessage
Instead of sequential guards:
// Inside Protocol.onmessage:constvariant=discriminateJsonRpc(rawMessage);switch(variant){case'request':
// Run ONLY JSONRPCRequestSchema (1 parse instead of 4)returnhandleRequest(JSONRPCRequestSchema.parse(rawMessage));case'notification':
// Run ONLY JSONRPCNotificationSchema (1 parse instead of 5)returnhandleNotification(JSONRPCNotificationSchema.parse(rawMessage));case'response':
if('result'in(rawMessageasany)){returnhandleResponse(JSONRPCResultResponseSchema.parse(rawMessage));}else{returnhandleError(JSONRPCErrorResponseSchema.parse(rawMessage));}case'invalid':
thrownewJsonRpcError(-32600,'Invalid JSON-RPC 2.0 envelope');}
Key Observations
Zero Backtracking: Completely eliminates the 3-4 failed parse attempts per message.
RFC 2.0 Invariants Maintained: Safely rejects invalid id types (e.g., boolean or object IDs) and invalid protocols before invoking schema engines.
Batch Handling: Works cleanly in batch arrays by classifying each element before selecting its validation branch.
(Full maintainer disclosure: I am the author of mcp-production-kit, where we implemented and test-covered this fast-path pattern across our production server test suite).
I tested a smaller, backwards-compatible alternative to replacing validation with a raw key discriminator. Treat envelope keys only as a hint; still run the selected Zod schema guard. For the common cases, one safeParse replaces multiple unsuccessful union-arm parses; if the hint is ambiguous or the schema rejects the payload, fall back to the original ordered guard chain (result → error → request → notification). This preserves the current invalid-message behavior and avoids adding a public API.
A pinned-source candidate against 919bb8ea88b6e10e72c2f8b6218fad4cfdc40b2c passed the complete @modelcontextprotocol/core-internal Vitest suite, typecheck, lint and the full workspace build. A standalone differential classifier run compared original vs candidate on 2,812 messages, including seeded randomized malformed/ambiguous envelopes, with zero classification disagreements.
A same-process Node/Zod microbenchmark (paired alternating runs, median of 7 repetitions; not end-to-end HTTP throughput) measured:
requests: 753.14 ms → 38.44 ms, ~19.6×
notifications: 1380.40 ms → 16.37 ms, ~84×
errors: 341.91 ms → 37.03 ms, ~9.2×
normal result responses: 16.07 ms → 17.09 ms, ~6.4% slower
mixed sample: 918.96 ms → 36.04 ms, ~25.5×
These numbers characterize this isolated classification path only; they do not establish a production CPU improvement or a particular traffic mix. A PR should still pin the exact conformance semantics for multiple protocol revisions and test transport-level throughput. The result-response regression also argues against claiming every message is faster. The important property is the absence of a validation bypass.
Activity
A7mdMe commentedon Nov 16, 2026
We encountered this exact bottleneck when profiling high-throughput MCP server transports under sustained JSON-RPC traffic. The sequential fallback across
types/guards.ts(isJSONRPCResultResponse->isJSONRPCErrorResponse->isJSONRPCRequest->isJSONRPCNotification) forces multiple backtrackingsafeParsepasses on every single incoming frame.Classifying by envelope key presence prior to schema validation drops those redundant walks entirely while maintaining strict runtime validation.
Here is a minimal, zero-dependency discriminator that resolves the variant in$O(1)$ and invokes only the selected schema:
Integrating into
Protocol.onmessageInstead of sequential guards:
Key Observations
idtypes (e.g., boolean or object IDs) and invalid protocols before invoking schema engines.(Full maintainer disclosure: I am the author of mcp-production-kit, where we implemented and test-covered this fast-path pattern across our production server test suite).
robertwmccarty-caelum commentedon Nov 17, 2026
I tested a smaller, backwards-compatible alternative to replacing validation with a raw key discriminator. Treat envelope keys only as a hint; still run the selected Zod schema guard. For the common cases, one
safeParsereplaces multiple unsuccessful union-arm parses; if the hint is ambiguous or the schema rejects the payload, fall back to the original ordered guard chain (result → error → request → notification). This preserves the current invalid-message behavior and avoids adding a public API.A pinned-source candidate against
919bb8ea88b6e10e72c2f8b6218fad4cfdc40b2cpassed the complete@modelcontextprotocol/core-internalVitest suite, typecheck, lint and the full workspace build. A standalone differential classifier run compared original vs candidate on 2,812 messages, including seeded randomized malformed/ambiguous envelopes, with zero classification disagreements.A same-process Node/Zod microbenchmark (paired alternating runs, median of 7 repetitions; not end-to-end HTTP throughput) measured:
These numbers characterize this isolated classification path only; they do not establish a production CPU improvement or a particular traffic mix. A PR should still pin the exact conformance semantics for multiple protocol revisions and test transport-level throughput. The result-response regression also argues against claiming every message is faster. The important property is the absence of a validation bypass.