Skip to content

[v2] Every inbound message is re-classified with up to four full zod parses after the transport already parsed it #3189

Open

Description

@nolnoch

What happened?

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.

  1. 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.
  2. 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.
  3. 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)

Area

Server

Activity

  1. A7mdMe commented on Nov 16, 2026

    @A7mdMe

    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:

    export type JsonRpcVariant = 'request' | 'notification' | 'response' | 'invalid';
    
    /**
     * Fast O(1) envelope discriminator by structural key presence.
     * Directs inbound payloads to the exact matching schema without union backtracking.
     */
    export function discriminateJsonRpc(raw: unknown): JsonRpcVariant {
      if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
        return 'invalid';
      }
    
      const obj = raw as Record<string, unknown>;
    
      // Strict JSON-RPC 2.0 version assertion
      if (obj.jsonrpc !== '2.0') {
        return 'invalid';
      }
    
      // Response: must have 'result' or 'error' and an id
      if ('result' in obj || 'error' in obj) {
        if ('id' in obj && (typeof obj.id === 'string' || typeof obj.id === 'number' || obj.id === null)) {
          return 'response';
        }
        return 'invalid';
      }
    
      // Request or Notification: must have string 'method'
      if ('method' in obj && typeof obj.method === 'string' && obj.method.length > 0) {
        // Request has an id (string | number)
        if ('id' in obj) {
          if (typeof obj.id === 'string' || typeof obj.id === 'number') {
            return 'request';
          }
          return 'invalid';
        }
        // Notification has NO id property
        return 'notification';
      }
    
      return 'invalid';
    }

    Integrating into Protocol.onmessage

    Instead of sequential guards:

    // Inside Protocol.onmessage:
    const variant = discriminateJsonRpc(rawMessage);
    
    switch (variant) {
      case 'request':
        // Run ONLY JSONRPCRequestSchema (1 parse instead of 4)
        return handleRequest(JSONRPCRequestSchema.parse(rawMessage));
      case 'notification':
        // Run ONLY JSONRPCNotificationSchema (1 parse instead of 5)
        return handleNotification(JSONRPCNotificationSchema.parse(rawMessage));
      case 'response':
        if ('result' in (rawMessage as any)) {
          return handleResponse(JSONRPCResultResponseSchema.parse(rawMessage));
        } else {
          return handleError(JSONRPCErrorResponseSchema.parse(rawMessage));
        }
      case 'invalid':
        throw new JsonRpcError(-32600, 'Invalid JSON-RPC 2.0 envelope');
    }

    Key Observations

    1. Zero Backtracking: Completely eliminates the 3-4 failed parse attempts per message.
    2. RFC 2.0 Invariants Maintained: Safely rejects invalid id types (e.g., boolean or object IDs) and invalid protocols before invoking schema engines.
    3. 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).

  2. added
    v2Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes
    v1Issues / PRs related to v1.x
    on Nov 16, 2026
  3. robertwmccarty-caelum commented on Nov 17, 2026

    @robertwmccarty-caelum

    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.

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

    v1Issues / PRs related to v1.xv2Ideas, 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