Skip to content

fix(server): validate low-level tool inputs - #2634

Open
uuzzrm wants to merge 2 commits into
modelcontextprotocol:mainfrom
uuzzrm:codex/validate-low-level-tool-inputs
Open

uuzzrm wants to merge 2 commits into
modelcontextprotocol:mainfrom
uuzzrm:codex/validate-low-level-tool-inputs

Conversation

@uuzzrm

@uuzzrm uuzzrm commented Aug 10, 2026

Copy link
Copy Markdown

Fixes #2628

Summary

  • Remember each tool inputSchema advertised by a low-level tools/list response for the active connection.
  • Validate tools/call arguments before dispatch and return an isError tool result when the arguments do not match the advertised schema.
  • Keep the high-level McpServer Standard Schema parsing path unchanged, including schemas that intentionally coerce or transform values.
  • Add regression coverage for invalid and valid calls, connection-scoped schema state, custom JSON Schema validators, and high-level coercion.
  • Update the low-level server and schema validator documentation and example.

Verification

Passed:

  • pnpm lint:all
  • pnpm typecheck:all
  • pnpm build:all
  • pnpm --filter @modelcontextprotocol/server test (42 files, 473 tests)
  • pnpm --filter @modelcontextprotocol/examples typecheck
  • pnpm --filter @modelcontextprotocol/examples exec tsx guides/advanced/low-level-server.examples.ts

The repository-wide pnpm test:all run was blocked by two existing examples/shared tests because the local environment could not load the better-sqlite3 native binding. The server, client, core, and middleware test suites completed successfully.

@uuzzrm
uuzzrm requested a review from a team as a code owner August 10, 2026 07:11
@pkg-pr-new

pkg-pr-new Bot commented Aug 10, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

@modelcontextprotocol/client

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

@modelcontextprotocol/codemod

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

@modelcontextprotocol/core

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

@modelcontextprotocol/server

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

@modelcontextprotocol/server-legacy

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

@modelcontextprotocol/express

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

@modelcontextprotocol/fastify

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

@modelcontextprotocol/hono

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

@modelcontextprotocol/node

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

commit: e5571a6

@pacocartones pacocartones left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Verify pass on the current head — no blocking findings.

I reproduced the issue independently against the published @modelcontextprotocol/sdk@1.30.0: the low-level Server runs a tools/call handler with arguments that violate the tool's declared inputSchema (e.g. code: 12345 against {code: string, required}) with no protocol error, while McpServer rejects the identical call with -32602: Input validation error: Invalid arguments for tool …. This PR closes exactly that gap.

Checked against the code rather than the description:

  • Schemas are captured from the validated tools/list result (validateResult before _rememberToolInputSchemas), so an invalid tools/list still fails wire validation — the seam does not trust an unvalidated handler response.
  • The rejection surface mirrors the high-level path (isError: true + Input validation error: Invalid arguments for tool ${toolName}: …), so clients see one consistent error shape.
  • Servers without a declared schema are untouched (_toolInputValidators only populated from declared schemas; the catch around a malformed schema preserves prior behavior).
  • The highLevelServers guard against double validation is the right call: McpServer validates via Standard Schema, which may intentionally differ from the advertised JSON Schema (coercion).

Non-blocking notes:

  1. The validator runs against the schema recorded at the last tools/list; if a server changes schemas between requests the map is refreshed on each list, so this is fine — worth a line in the docs for readers, though.
  2. The ServerOptions.jsonSchemaValidator docstring was updated to mention tool inputs, but docs/advanced/ may still describe it as elicitation-only; a one-line docs sync would avoid confusion.

The CI surface (build, client/server conformance, tests) is green on the current head.

@uuzzrm

uuzzrm commented Aug 11, 2026

Copy link
Copy Markdown
Author

Thanks for the careful verification. I checked the current head dc24b03e against the docs note: docs/advanced/schema-libraries.md already describes low-level Server tool-call validation, elicitation validation, the separate fromJsonSchema validator, and the fact that high-level McpServer uses its registered Standard Schemas. No additional docs change is needed on this head.

The schema map is refreshed from each validated tools/list response as noted. The current CI remains green; this is ready for maintainer review.

@changeset-bot

changeset-bot Bot commented Aug 15, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: e5571a6

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/core Patch
@modelcontextprotocol/client Patch
@modelcontextprotocol/server-legacy Patch
@modelcontextprotocol/codemod 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

@claude claude Bot added the v2 Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes label Aug 18, 2026
@Ahmad-Faraj

Copy link
Copy Markdown

Thanks for picking this up. I filed #2628, and reviewed this at e5571a6.

This PR checks a call only against schemas the server remembered from a tools/list earlier on the same Server instance. Without that earlier listing, the call reaches the handler unchecked, as it does today. That leaves gaps:

  1. createMcpHandler: on the modern path, and on the default legacy: 'stateless' path, every HTTP request gets a fresh Server from the factory (see the header of createMcpHandler.ts and invoke.ts). The tools/list and the tools/call therefore run on different instances. The validator map is always empty when the call arrives, so nothing is checked on the HTTP path most deployments use. Could you add a test that goes through createMcpHandler?
  2. Clients that don't list first: a client that cached the tool list, or that reconnected, is not checked. The test does not reuse tool schemas after the connection closes makes this the expected behaviour. The docs example also needed a new await client.listTools() before the call, which shows the same dependency.
  3. Stale schemas: @pacocartones raised this as a docs note. If the server changes a tool's inputSchema and the client hasn't listed again, calls are checked against the old schema, so a valid call can be rejected.

A design that avoids all three: when a tools/call arrives, have the server call its own registered tools/list handler (following pagination), so the check doesn't depend on what the client happened to request. I assume that question is what the needs design label is about, so a maintainer probably needs to choose the approach before this lands. Smaller notes:

  • The new text in low-level-server.md ("returns an isError: true tool result before your handler runs") is only true after a listing on the same instance. It should say that, or the behaviour should change.
  • mcp.compat.test.ts changes an existing test's input from 7 to '7'. Adding a new coercion test would keep the original case covered.
  • The branch currently conflicts with main.

The isError shape and the McpServer opt-out look right to me. Happy to test a revision against the census cases (the 3.5% of servers that executed on an argument their own schema rejects).

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.

Low-level Server API publishes inputSchema in tools/list but does not enforce it on tools/call

3 participants