Skip to content

fix(server): a tool's MissingRequiredClientCapabilityError is a JSON-RPC error - #3202

Open
mattzcarey wants to merge 5 commits into
mainfrom
fix/tool-missing-capability-error
Open

mattzcarey wants to merge 5 commits into
mainfrom
fix/tool-missing-capability-error

Conversation

@mattzcarey

@mattzcarey mattzcarey commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

On a 2026-07-28 request, a tool that throws MissingRequiredClientCapabilityError now answers tools/call with JSON-RPC error -32021 and its requiredCapabilities, instead of an isError tool 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 -32021 and, on HTTP, status 400:

  • McpServer wrapped the error like any other throw; it now passes it through, as it already does UrlElicitationRequiredError.
  • The HTTP transport already maps a handler's -32021 to 400. A response whose stream is already open (the tool sent a notification first, or responseMode: 'sse') keeps its 200 and carries the error in the stream, as the migration guide describes.
  • This changes what such a tool returns for every McpServer on 2026-07-28, so it has its own server patch changeset. A tool that relays a downstream server's -32021 should catch and translate it.
  • Split out of feat: server and client extensions ({ id, setup(ctx) }), request middleware (use), acceptResultType #2820 at review. feat: Tasks extension for server and client (ext/tasks subpaths) #2782 (Tasks) needs it: tasks.create throws this error inside a tool handler.
  • docs/servers/errors.md now 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 the createMcpHandler entry, and the unchanged tool error on 2025-11-25; the status was also checked by hand through toNodeHandler on a Node server and on Express.

@mattzcarey
mattzcarey requested a review from a team as a code owner November 18, 2026 15:16
@changeset-bot

changeset-bot Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 081824c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages
Name Type
@modelcontextprotocol/server Patch
@modelcontextprotocol/client Patch
@modelcontextprotocol/codemod Patch
@modelcontextprotocol/core Patch
@modelcontextprotocol/server-legacy Patch
@modelcontextprotocol/core-internal Patch

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

@pkg-pr-new

pkg-pr-new Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/@modelcontextprotocol/client@3202

@modelcontextprotocol/codemod

npm i https://pkg.pr.new/@modelcontextprotocol/codemod@3202

@modelcontextprotocol/core

npm i https://pkg.pr.new/@modelcontextprotocol/core@3202

@modelcontextprotocol/server

npm i https://pkg.pr.new/@modelcontextprotocol/server@3202

@modelcontextprotocol/server-legacy

npm i https://pkg.pr.new/@modelcontextprotocol/server-legacy@3202

@modelcontextprotocol/express

npm i https://pkg.pr.new/@modelcontextprotocol/express@3202

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/@modelcontextprotocol/fastify@3202

@modelcontextprotocol/hono

npm i https://pkg.pr.new/@modelcontextprotocol/hono@3202

@modelcontextprotocol/node

npm i https://pkg.pr.new/@modelcontextprotocol/node@3202

commit: 081824c

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

Comment thread test/e2e/requirements.ts Resolved
Comment thread packages/server/src/server/mcp.ts Resolved
Comment thread packages/server/src/server/mcp.ts Resolved
…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.
@mattzcarey
mattzcarey force-pushed the fix/tool-missing-capability-error branch from 9f7ab2b to 91b84d5 Compare November 19, 2026 00:10

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code review found no issues

No high-confidence issues detected in this change.

Still open from earlier reviews (2):

  • Unresolved: 2 minor or pre-existing.

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

Still open from earlier reviews (1):

  • Unresolved: 1 minor or pre-existing.

Comment thread docs/servers/errors.md Resolved
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.

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

Comment thread test/e2e/requirements.ts Resolved

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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() in server.ts, so an undefined or 2025-era version keeps the isError result.
  • The changeset and docs/servers/errors.md wording against perRequestTransport.ts: a handler's -32021 gets 400 only while no response is committed, and an open stream keeps its 200.
  • The three manifest entries: the supersedes/supersededBy pair 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.

@claude claude Bot added the v2 Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes label Nov 19, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

v2 Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant