[nissa-seru]

Fixes #475.

The host now answers an MCPL server's request that has "id": null, and its answer carries id: null. Until now the host took such a request for a notification and never answered it. A request whose id isn't a string, a number or null, or whose method isn't a string, now gets one -32600 "Invalid Request", and the host doesn't dispatch it. A message with an id and no method is a response whatever the id's value, and so is a JSON-RPC 2.0 error with no id, as MCP allows, so the host never answers either. During the initialize handshake, a JSON-RPC 2.0 error that names no request is initialize's answer, and the connect fails at once with it. The framework's MCP server is the other endpoint that answers JSON-RPC requests. It now reads a message's envelope by the same rule, through one shared check. This head merges main at 921390ce, so a request with id: null is answered only on the transport it came on, as every request is since #544. tools/hints, which main has added since e66bdae1, answers one with id: null too, while a read tap listens. main has since moved to 62a126c7, its 0.29.0 release, which changes no file under src/ or test/.

Problem

McplServerConnection tells a server's request from a notification by id != null. At 921390ce, the main this head merges, that's the response check at src/mcpl/server-connection.ts:2392, the dispatch at lines 2390 to 2485, the handshake's ping at line 1343, and tools/hints at line 2429. That gives two wrong answers:

• A request with "id": null is dispatched as a notification, with no responder, so it's never answered. JSON-RPC 2.0 (§4.1) and MCPL §4.1 define a notification as a request without an id member.
• A request whose id is an object, an array or a boolean is dispatched, and the answer to an object id carries that object back. JSON-RPC 2.0 (§4) allows a string, a number or null, and an invalid request gets -32600 with id: null (§5).

MCP's own spec is stricter than JSON-RPC here: a request's ID "MUST NOT be null" (2025-11-25, Basic). The host answers one anyway, as JSON-RPC allows and as the framework's MCP server already did, since a peer that sends one is waiting for its answer.

I probed this through the real connection routing, under Bun 1.4.3, on main (e5f50bf). A stdio server sends the host three scope/elevate requests, which the host answers -32601 whatever its grants. The one with id 7 is answered. The one with id null gets nothing. The one with id {"nested":[1]} is answered with that object as its id.

src/api/mcp-server-core.ts, the MCP server, already answered "id": null. But it also echoed an invalid id back. It answered a non-string method with -32601 "Method not found", and it answered a response that carried an id with -32601, as if it were a request. A request named initialized got no answer at all.

Changes

• src/jsonrpc-envelope.ts reads a parsed message's envelope once, for both endpoints:

  • A message with an id member and no method is a response, whatever the id's value. So is an error with no id, which MCP lets a peer send for a request it couldn't read, but only in a message whose jsonrpc member is "2.0", since a server's own JSON log lines can carry an error key. Any other object with neither a method nor an id isn't JSON-RPC.
  • A message with a method is a request when it has an id member, so "id": null is a request. Without an id member, it's a notification.
  • A message whose method isn't a string, or whose id isn't a string, a number or null, isn't a valid request. It's answered once with -32600 and isn't dispatched. The answer's message says what was wrong, such as Invalid Request: the id must be a string, a number or null, not an object. It carries the request's id where that's a string or a number, and null otherwise.
  • Such a message is answered even when it has no id. A notification is a valid request without an id (§4.1), so the rule against answering notifications doesn't cover it, and JSON-RPC 2.0's own example of an invalid request, {"jsonrpc": "2.0", "method": 1, "params": "bar"}, is answered -32600 with id: null.
  • The texts name an invalid value's kind ("an object", "null") rather than repeat the value.

• The MCPL connection dispatches on the envelope:

  • An id-null request is dispatched with responders that answer id: null.
  • An invalid request gets its -32600 answer and a stderr line, which names the method when that's a string. On main at e66bdae1, a request whose method isn't a string got -32601 "Method not found" (fix(mcpl): contain inbound request handler failures #208), and one without an id was ignored.
  • Any other object with neither a method nor an id is ignored, as before, like a server's other unrelated output on stdout.
  • Answers go out only on the transport the request came on, as main sends every answer since fix(mcpl): a reconnect holds control traffic as well as data until its new grant, whatever gate completes meanwhile #544. A request with id: null gets the same transport-bound responder as any request, including one read after its transport closed and kept for the next grant. An invalid request read after its transport closed isn't answered: main's not answering request … line says so, in place of the answered -32600 line.
  • A response whose id is neither a string nor a number, or that has none, can't be matched to a request of the host's, whose ids are numbers. It's logged with its error member, if it has one, and ignored, and it's no longer surfaced as an orphaned response. A server sends an error with id: null, or under MCP with no id, for a request it couldn't read. Once connected, such an error may be meant for one of the host's requests, which gets nothing from it and ends as any unanswered request does, by its timeout where it has one.
  • During the initialize handshake, initialize is the only request the host has out, and a peer never answers a response. So a JSON-RPC 2.0 error with id: null or no id then is initialize's answer, and the connect fails at once with the server's error. Of the handshake's other responses, one whose id is neither a string nor a number, or that has none, is logged, as on a connected transport, a server's own log line with "id": null and an error key included. One with another string or number id is ignored, as on main.
  • MCP's ping (The host doesn't answer MCP ping from an MCPL server #392) follows the same rule. A ping with id: null gets its empty result with id: null, on a connected transport and during the initialize handshake. During the handshake, every other request and notification is still ignored, an invalid request included, as The host doesn't answer MCP ping from an MCPL server #392 has it.
  • So does tools/hints, which main has added since e66bdae1. Read while a read tap listens, a tools/hints request with id: null gets its empty result with id: null, as a ping does.

• The MCP server answers an invalid request with -32600 by the same rule.

  • It logs a response, with its error member if it has one, and doesn't answer it, since it sends its client no requests.
  • It answers a JSON value that isn't an object with -32600 and id: null. For an array, JSON-RPC's batch, the answer says this server doesn't accept batches. Until now, a number, a string or null got -32700 "Parse error", though it parsed, and an array got no answer.
  • A request named initialized now gets -32601 "Method not found", as any unknown method does. MCP's acknowledgment is the notifications/initialized notification, which never reached the request handler, so the handler's initialized case only ever met a request, and answered nothing.
  • The MCPL connection still ignores a value that isn't an object, apart from the stderr lines main writes for lines it drops (messageFromLine, src/mcpl/server-connection.ts:2894–2897).

• The id types now include null wherever a request's id travels. These are:

  • JsonRpcRequest and JsonRpcResponse, neither of which is exported from the package root;
  • the connection's reply helpers;
  • the framework's InboundResponder and its inference/request responder;
  • InferenceRouter's Responder.

  The router already streams only for a request id that isn't null. So a streaming inference/request with id: null gets its whole result in one answer.

Why each part

• One shared check. The endpoints that answer requests read an envelope by one rule, kept in one place, so they can't drift apart. The host doesn't answer MCP ping from an MCPL server #392's handshake ping had already drifted, answering only a ping whose id wasn't null, and main's tools/hints has the same test, request.id != null (921390ce:src/mcpl/server-connection.ts:2429). Two copies of the rule were the alternative.
• A response before a request. A peer answers a request it couldn't read with id: null (§5). Telling requests by the id member alone would take that answer for a request and answer it. Two peers that both answer what they can't read would then trade errors.
• The response-id guard in handleResponse. The host's own request ids are numbers. Without the guard, a response whose id is an object and which carries state is surfaced as an orphaned response, as it is on main. An orphan means a late answer to a request the host can name, and such a response can't be one.
• The handshake's failure. A server that can't read the host's initialize answers it with id: null, or under MCP with no id, and then the connection can't work. Until now the handshake dropped that answer, and the connect failed only at its 30 s timeout, without the server's error. Now it fails at once, with the error's message. It takes an error that names no request that way only when its jsonrpc is "2.0", so a server's own JSON log line on stdout, with an error key and "id": null or no id, can't fail the connect. A line that carries initialize's own id, 0, is still taken for its answer whatever its jsonrpc, as on main.
• An error with no id. MCP 2025-11-25 lets a peer answer a request it couldn't read with no id at all (Basic, Error Responses), where JSON-RPC 2.0 has id: null. Without this, a server that follows MCP's newest form and can't read initialize would still leave the connect to its timeout. Requiring "jsonrpc": "2.0" keeps such log lines out of the envelope's responses.
• The MCP server's non-object answer. Its stdin carries only its client's messages, so a value that isn't an object is an invalid request. A server's stdout can carry unrelated output, which is why the MCPL connection keeps ignoring such values.
• The stderr lines. They're the host's only trace of a request answered -32600, and of a response that's dropped. Each prints a response's error member as logValue prints a peer's text, escaped and cut at 256 UTF-16 units, so one that isn't the usual {code, message} still shows what was sent, up to that cut, and none can pose as a log field. The MCPL connection's line also redacts any credential the server's configuration holds, as main's line for an error answer does (logValueRedacted). The MCP server's line, about its own client rather than a configured server, isn't redacted.
• The id types. What the code sends, id: null, type-checks without casts.
• initializeAnswers, a test helper. Four handshake tests each need a stdio server that answers initialize with lines they choose, some carrying initialize's own id. The helper writes that server once, where each test would otherwise carry its own copy of the same script.
• Cut. The change removes describeMethod, whose non-string case now belongs to the envelope, and the MCP server's initialized case. main's other caller of describeMethod, the line for a request read after its transport closed, now prints method <name> as the -32601 line does, since such a request's method is always a string.

What callers and servers will notice

• An MCPL server that sends "id": null now gets an answer, with id: null. One that sends an invalid id or method gets -32600 saying what was wrong, with or without an id. The host never answers a response.
• An MCP client of McpServer, which the agent-framework-mcp command runs, gets -32600 for an invalid request or for a value that isn't an object, and -32601 for a request named initialized. It gets no answer to a response.
• A host connecting to an MCPL server that can't read its initialize, and answers it with a JSON-RPC 2.0 error with id: null or no id, gets the connect's rejection at once, MCPL server "<id>" initialize error: <the server's message>, where it got a timeout 30 s later.
• Hosts see a stderr line for each invalid request ([mcpl] <server>: answered -32600 to an invalid request …) and for each response whose id is neither a string nor a number, or that has none (… which can't be matched to a request of ours …). An invalid request read after its transport closed gets main's not answering request … line instead of an answer. The MCP server logs each response it gets, prefixed [agent-framework-mcp].
• Code that listens to McplServerConnection's request events can now be handed a responder whose id is null. An inference/request handler can be handed a requestId of null.
• Unchanged. The host handles requests with a string or number id and a string method, notifications with a string method, and responses to its own requests as before.

Merging with main

This branch was opened on main at e5f50bf, and 6ce9796 merges main at e66bdae1 into it, with no force-push. Four files conflicted, where #544 binds a request's answers to the transport it came on and main's log lines print a server's error text redacted. The merge keeps both for what this change adds:

• responderFor, sendResponse, sendErrorResponse and sameTransport take a null id, and a request with id: null gets responderFor's transport-bound responder, read live or kept across a transport boundary (afterBoundary takes the id the envelope read).
• An invalid request's -32600 is sent only on the transport it came on, so one read after that transport closed isn't answered.
• A response read after its transport closed goes to handleResponse as late, as on main, and the guard for an id that is neither a string nor a number comes first.
• The log line for a response that can't be matched redacts its error member with the server's configuration (redactServerText during the handshake, the connection's kept redactor once connected).
• framework.ts, inference-router.ts and the router's test take main's sendChunk and noChunkSender beside this change's null id.

c51253fe then merges main at 921390ce. Two files conflicted, src/mcpl/server-connection.ts and test/mcp-server-bin.test.ts. On main, the connection reads each stdio line through messageFromLine, which logs the lines it drops, and applies RFC-014 hints from responses, push/event and tools/hints as it reads them. The merge keeps both beside this change's envelope:

• tapResponse returns at once for a response with id: null (src/mcpl/server-connection.ts:2639), since on this branch a response's id can be null (src/mcpl/types.ts:36).
• tools/hints answers a request whose id is null, with id: null, as a ping is answered. f9337c47 adds its test.
• test/mcp-server-bin.test.ts keeps this branch's bundle copy, as deep in dist/src/ as the module. The module now also imports ../jsonrpc-envelope.js and ../mcpl/log-value.js (src/api/mcp-server-core.ts:15–18), where main's form of the test copied only line-reader.js beside its copy.
• test/mcpl-request-envelope.test.ts's test of a JSON value that isn't an object allows main's lines for lines it drops, and nothing else, on stderr.

I merged this head with each of the 53 other open pull requests, as of 20:58 UTC on October 28, by git merge-tree, with 921390ce, the main this head merges, merged with each as the control. With every one, it conflicts in the same files, with as many conflicting hunks, as 921390ce's merge does, or merges cleanly as it does. Of them, #378 changes src/mcpl/inference-router.ts, whose answer to an inference/request with id: null this change's router test pins.

Tests

• test/mcpl-request-envelope.test.ts (new, 19 tests) drives the real connection routing and response encoding with a stand-in transport, and stdio servers for the handshake. It checks:

  • a request with "id": null is dispatched with a responder and answered with id: null, and so is a request for each removed method;
  • a tools/hints request with "id": null, read while a read tap listens, is answered with id: null;
  • a request with "id": null held while the planes are paused is answered with id: null when they open, and one for an event the grant refuses gets the refusal with id: null;
  • a request with "id": null whose handler answers after its transport closed, and one read after its transport closed and kept for the next grant, are answered on neither transport, and neither is an invalid request read after its transport closed; each answer not sent gets main's not answering request line, and nothing says answered -32600;
  • a message with no id member is still a notification, dispatched with no responder (a control);
  • an object, array or boolean id gets one -32600 with id: null, and nothing is dispatched;
  • a non-string method gets -32600, with the request's id where that's a string or a number and null otherwise. When both are wrong, the message names both faults;
  • JSON-RPC 2.0's own example of an invalid request, with a non-string method and no id, is answered -32600 with id: null;
  • a server's error with id: null or with no id, and a response with an object id and state, are each logged, never answered and not surfaced as orphans. A number id still is surfaced (a control);
  • an error with id: null or no id while a request of the host's is pending leaves that request pending, and its own answer still settles it;
  • an error that can't be matched is logged with a credential its server's configuration holds redacted, once connected and during the handshake, and once connected, three such errors read a configuration whose env is a getter once, for the redaction the connection keeps;
  • during the handshake, a JSON-RPC 2.0 error with id: null, and one with no id, answers initialize, so the connect fails at once with the server's error. A numbered response that isn't initialize's is ignored, and so is a log line with an error key and neither an id nor jsonrpc. A null-id result, two log lines with id: null and an error key but no jsonrpc, and an object-id response with a bare-string error are logged, and the initialize answer that follows is taken;
  • an object with neither a method nor an id, a log line with an error key and no jsonrpc among them, is ignored, with no log, and a JSON value that isn't an object, a batch included, is ignored, with nothing on stderr but main's lines for lines it drops (two controls).

• test/mcp-server-envelope.test.ts (new, 8 tests) feeds the MCP server's input handler lines, as its stdin reader does. It checks:

  • a ping with id: null is answered with id: null (a control: it already was);
  • invalid ids and methods are answered -32600 and not handled;
  • JSON-RPC 2.0's own example of an invalid request, with no id, is answered -32600 with id: null;
  • an error with id: null or no id, a numbered response, an object-id response whose error is a bare string, and a response whose string id and error could pose as log fields are each logged, escaped, and not answered;
  • values that aren't objects are answered -32600 with id: null, and a batch's answer says batches aren't accepted;
  • a request named initialized gets -32601, and the notifications/initialized notification nothing;
  • controls for a line that isn't JSON, a notification, an object with neither member, an error without jsonrpc, and an unknown method.

• test/mcpl-request-handler-errors.test.ts.

  • Its -32601 test now takes a request with id: null for an unhandled method, in place of its two non-string methods. The new file pins those as -32600.
  • Its failure-trace test's id that is neither a string nor a number is now null, the one such id a request can now carry.

• test/mcpl-ping.test.ts. While the planes are paused, a ping with id: null is answered with id: null at once, and one with an object id gets -32600. During the handshake, a ping with id: null is answered with id: null, and one with an object id is ignored, not echoed.

• test/mcpl-inference-router.test.ts. A streamed inference/request with id: null is answered whole, with no stream opened and no chunks.

• test/mcp-server-bin.test.ts puts its bundle copy of the server's module at the module's own depth in dist/src/. The copy then resolves the module's new relative imports the way the module does.

• Red-first. With 921390ce's source and the six new and changed test files at this head, 26 of those files' 185 tests fail. They are the new files' tests of an id-null request (answered, held and flushed, refused, and answered only on its own transport), an error that names no request beside a pending request, the redacted log of an error that can't be matched (connected and during the handshake) and the one read of its configuration for that redaction, an invalid id or method (with and without an id), a response, a value that isn't an object, the handshake's failure on an error that names no request (in both forms) and its log, the request named initialized, and the tools/hints request with id: null; the two turned-round tests in mcpl-request-handler-errors; and the two new ping tests. The other 159 pass, the controls among them. They include the router's tests, since main's router already answers a null id whole, which one of them pins. Against main's Responder type, which doesn't allow null, that test has one type error, and tsc still emits it.

• Removals. At 72dc84a, before the merge, I removed or inverted each piece on its own, 39 in all, and ran these six files on what tsc emits. Every one fails a test aimed at it. The pieces are:

  • in the envelope: the response-first rule, the treatment of an object with neither member, telling a request by its id member, the method check, the id check, carrying a valid id in the -32600, answering an invalid message that has no id, passing the method on for the log, jsonKind's article, taking an error with no id as a response, and taking it only with "jsonrpc": "2.0";
  • in the MCPL connection: the response branch, the -32600 answer, its log line and that line's method, the response-id guard, the responder's id: null, the handshake's ping for id: null, its not echoing an invalid id, the connected ping for id: null, the handshake's log of a response that can't be matched, the error member in that log and its escaping, the handshake's taking an error that names no request as initialize's answer, its taking one with no id so, its taking only an error so, its taking only a JSON-RPC 2.0 one, and the log's words for a response with no id;
  • in the MCP server: the refusal of non-objects, the refusal of batches and its text, the -32600 answer, the response branch, the error member in its log, the escaping of that member and of a response's string id, the log's words for a response with no id, and the dropped initialized case;
  • in the router, which this change doesn't touch: answering a null id whole, which the new router test pins.

  At the merge (6ce9796), each of its own 8 pieces, removed on its own, fails a test aimed at it, in these six files with mcpl-reconnect-events and mcpl-agent-words: the transport's epoch on an invalid request's -32600, leaving out answered -32600 for one read after its transport closed, binding a live request's responder to its transport, afterBoundary's responder for id: null, the redaction of the unmatched-response line once connected and during the handshake, marking a response read after its transport closed as late, and sending a request read after its transport closed to afterBoundary.

  At this head's tree, with main's request.id != null put back in tools/hints' answer, the new tools/hints test fails at its reply, and the file's other 18 tests pass.

  At 1dd81e4, building the redactor afresh for each response that can't be matched, in place of the connection's kept one, fails the new test of that redaction, and only that test, in mcpl-request-envelope and mcpl-agent-words: three such responses read the configuration 3 times, not once.

• Full suite. We ran npm install, typecheck, build and npm test, as CI runs them, on Linux with Node 24.22.1. At this head (f9337c47), 8,773 of 8,835 tests pass, none fail, and 62 are skipped. At 921390ce, run the same way, 8,743 of 8,805 pass, none fail, and 62 are skipped. By name, the difference is exactly the 30 new tests: 19 and 8 in the new files, 2 in mcpl-ping and 1 in mcpl-inference-router.

• Under Bun. Under Bun 1.4.3, the stdio probe above, at 72dc84a, before the merge, gets three answers: id 7 -32601, id null -32601 with id: null, and the object id -32600 with id: null. The same probe of the MCP server's input handler gets a result with id: null for initialize with id: null, -32600 with id: null for an object id, and -32600 with id: 9 for "method": 7.

Checks

The two workflow runs at this head, f9337c47, CI and Changelog, are pull_request runs, and each of their jobs checked out a2f70a3, GitHub's merge of f9337c47 into main at 62a126c7. All passed: Build & Test on Ubuntu with Node 22.12.0, 24 and latest and on macOS with Node 22.12.0, code_execution under Bun 1.4.0 and 1.4.3 on Ubuntu and macOS, the packed release's install on Node 22.12.0 and 24, What the change touches, and the changelog check (runs 40762754329 and 40762754525).

Not verified

• No published MCPL server or MCP client was run against this. The tests use a stand-in transport, the server's input handler or a stdio server script, and the probes a stdio server script.
• No real reconnect carried a request with id: null. The tests that answer one only on its own transport reach the transport's boundary by calling the connection's own resetPolicyForTransportBoundary and replacing its transport.
• No run checked whether the MCP TypeScript SDK 1.30.0 or mcpl-core-ts ever sends a request with id: null, an invalid id or a non-string method.

Out of scope

• params isn't checked. §4.2 asks for an object or an array, and each method's handler reads its own params, as before.
• The jsonrpc member isn't checked, as before, except to tell a JSON-RPC error that names no request from a server's own log line.
• Batches aren't served. The MCPL connection ignores a JSON array, as main does. The MCP server answers one with a single -32600 saying it doesn't accept batches.
• A response whose numeric id matches no pending request of the host's is handled as before.
• Failure reports keep a request's id only when it's a string or a number, as the mcpl:request-handler-error trace's contract says. So a failed request with id: null is traced and logged without its id.
• An error member that's a bare string, answering one of the host's own requests or its initialize, is read as before. Those paths read code and message from it, so a request's log line reads with error undefined: undefined, its rejection says the server answered "without saying what went wrong", and an initialize answered that way fails with initialize error: undefined. A probe under Bun showed the same at main (e5f50bf) and at 72dc84a. Only the log of a response that can't be matched prints the member itself, as logValue prints it.
• An id JSON.parse can't hold exactly is answered as JSON.parse read it, as every value the connection reads is. An integer past 2^53 comes back rounded, and 1e400, read as Infinity, comes back as null, since JSON writes Infinity that way.

---

• Changelog fragment added: changelog.d/475-mcpl-request-ids.fixed.md

Byron-2452 made this change and wrote this description, and settled its design with Ada-1017. Our internal review read it, and this head takes its fixes. Desmond-2579 and Ogden-2688 reviewed it, the later handshake changes included: Ogden-2688 proposed failing the handshake at once, Desmond-2579 found MCP's error with no id, and both found that the handshake had to require "jsonrpc": "2.0" too. Desmond-2579 also reviewed the first merge with main, 6ce9796, and read the second, c51253fe, with the test commit f9337c47. Lottie-2661 checked and posted earlier versions of this description and wrote this update for the second merge.

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; no actionable issues were found.

Summary

Shares JSON-RPC message checks between the MCPL connection and MCP server. Requests with id: null now receive replies, while invalid ids and methods receive -32600 without reaching handlers.

• The MCPL connection reads requests and responses by their message fields.
• The MCP server separates client requests from responses and invalid messages.
• Null-ID inference requests return their result without streaming chunks.

No actionable issues found. This review checked source and tests; it did not run tests.

_{Reviews (1) · Last reviewed commit: "fix(mcpl,api): read a JSON-RPC envelope ..." · Reviewed by Greptile}