Repository navigation
fix(server): a tool's MissingRequiredClientCapabilityError is a JSON-RPC error - #3202
mattzcarey wants to merge 5 commits into
Conversation
🦋 Changeset detectedLatest commit: 081824c The changes in this PR will be included in the next version bump. This PR includes changesets to release 6 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
@modelcontextprotocol/client
@modelcontextprotocol/codemod
@modelcontextprotocol/core
@modelcontextprotocol/server
@modelcontextprotocol/server-legacy
@modelcontextprotocol/express
@modelcontextprotocol/fastify
@modelcontextprotocol/hono
@modelcontextprotocol/node
commit: |
ac7515b to
9f7ab2b
Compare
…RPC error The spec says a server MUST answer a request that needs an undeclared client capability with MissingRequiredClientCapabilityError (-32021) carrying requiredCapabilities. McpServer wrapped it as an isError tool result, like any other throw; it now passes it through, as it does UrlElicitationRequiredError.
…docs say what a tool can propagate docs/servers/errors.md said the SDK converts anything a tool throws and that UrlElicitationRequiredError is the only error a tool can propagate.
9f7ab2b to
91b84d5
Compare
2025-11-25 does not define the code, so there the tool error stays as it was, the way the -32042 passthrough is gated to its own era. errors.md says which era each exception applies to.
There was a problem hiding this comment.
I reviewed the latest push and found no bugs. Because this changes what tools/call puts on the wire for every McpServer on 2026-07-28 (JSON-RPC -32021 and HTTP 400 instead of an isError result on 200), a maintainer look is still worthwhile.
What was reviewed:
- The new rethrow in
packages/server/src/server/mcp.ts: it uses the same condition as_servedModernEra()inserver.ts, so an undefined or 2025-era version keeps theisErrorresult. - The changeset and
docs/servers/errors.mdwording againstperRequestTransport.ts: a handler's-32021gets 400 only while no response is committed, and an open stream keeps its 200. - The three manifest entries: the
supersedes/supersededBypair is now linked both ways with matching version bounds, and the legacy entry's cells fall only on 2025-11-25. - I read the new e2e bodies but did not run them.
Extended reasoning...
The diff is 6 files and about 120 lines; the only production change is an 11-line era-gated rethrow in the McpServer tools/call catch block, with a changeset, doc rewording and three e2e requirements around it. It touches no auth, crypto or input-handling surface. Two facts ruled out approval: .github/CODEOWNERS assigns every path to the SDK maintainers team, and the change is a deliberate wire-visible behaviour change (result on 200 becomes error on 400) that a maintainer should sign off on. This run reported no findings, and the latest commit adds the manifest link raised in the previous review.
On a 2026-07-28 request, a tool that throws
MissingRequiredClientCapabilityErrornow answerstools/callwith JSON-RPC error-32021and itsrequiredCapabilities, instead of anisErrortool result. Over HTTP the response status is 400. On 2025-11-25, which does not define that code, nothing changes.The draft spec says a server MUST answer a request that needs an undeclared client capability with
-32021and, on HTTP, status 400:McpServerwrapped the error like any other throw; it now passes it through, as it already doesUrlElicitationRequiredError.-32021to 400. A response whose stream is already open (the tool sent a notification first, orresponseMode: 'sse') keeps its 200 and carries the error in the stream, as the migration guide describes.McpServeron 2026-07-28, so it has its ownserverpatch changeset. A tool that relays a downstream server's-32021should catch and translate it.tasks.createthrows this error inside a tool handler.docs/servers/errors.mdnow says which errors a tool handler can propagate, and on which revision.pnpm check:all, the build and the unit, integration, e2e and conformance suites ran on Node 24. Three new e2e requirements cover the JSON-RPC error and the HTTP 400 on thecreateMcpHandlerentry, and the unchanged tool error on 2025-11-25; the status was also checked by hand throughtoNodeHandleron a Node server and on Express.