MCPServer answers an unknown tool with an isError result; the spec (and the TS SDK) use JSON-RPC -32602

Summary

The spec's error-handling section for tools lists "Unknown tool" under protocol errors, returned as a standard JSON-RPC error with code: -32602. This is in both 2025-11-25 and 2026-07-28: server/tools.mdx in 2026-07-28, around line 742.

MCPServer (mcp 2.3.0) instead returns a successful CallToolResult with is_error=True and the text Unknown tool: <name>. It comes from ToolError in src/mcp/server/mcpserver/tools/tool_manager.py, at lines 72 and 85. The behaviour is described in docs/troubleshooting.md. Meanwhile docs/whats-new.md (the low-level example, note 5) says -32602 "is the spec's own answer for an unknown tool". The TypeScript SDK returns -32602 ("Tool nope not found").

Reproduction

import anyio
from mcp import Client, MCPError
from mcp.server import MCPServer

mcp = MCPServer("demo")

@mcp.tool()
def echo(text: str) -> str:
    """Echo the text."""
    return text

async def main() -> None:
    for mode in ("2026-07-28", "legacy"):
        async with Client(mcp, mode=mode) as client:
            try:
                result = await client.call_tool("does_not_exist", {})
                print(f"{mode}: CallToolResult is_error={result.is_error} text={result.content[0].text!r}")
            except MCPError as e:
                print(f"{mode}: JSON-RPC error code={e.code} message={e.message!r}")

anyio.run(main)

Output with mcp 2.3.0:

2026-07-28: CallToolResult is_error=True text='Unknown tool: does_not_exist'
legacy: CallToolResult is_error=True text='Unknown tool: does_not_exist'

Expected, per the spec:

2026-07-28: JSON-RPC error code=-32602 message='Unknown tool: does_not_exist'

Notes

The conformance probe in server-stateless (sep-2575-server-rejects-undeclared-capability) calls a tool name the server does not list. With this behaviour the probe reports "Server executed 'test_missing_capability'…", where for the TS SDK it reports "not testable". So the deviation also produces a confusing conformance finding for ordinary servers.
If the current behaviour is deliberate (the model can read an isError result), the 2026-07-28 spec text would need to change, or the docs could say the high-level server deviates here.

Reproduced on current main (91941ed) and read the full path through the code:

ToolManager.call_tool raises ToolError("Unknown tool: nope") for an unknown name (src/mcp/server/mcpserver/tools/tool_manager.py:85).
_handle_call_tool catches it and returns CallToolResult(content=[...], is_error=True) (src/mcp/server/mcpserver/server.py:456), so the client sees a successful result with is_error, never a JSON-RPC error.
The resource side already does the right thing: _handle_read_resource maps an unknown resource to MCPError(code=INVALID_PARAMS) (server.py:474-475), i.e. -32602.

So the fix can mirror the resource path: distinguish "tool not found" from other ToolErrors (for example a ToolNotFoundError subclass, raised in tool_manager.py at both sites), and in _handle_call_tool re-raise it as MCPError(code=INVALID_PARAMS, message=...) instead of returning is_error=True. Argument-validation failures keep returning isError results as they do today, since the spec treats invalid arguments as a tool error, not a protocol error.

Happy to prepare the patch if it's wanted.

@maxisbey

I re-checked this on main@91941ed with the SDK's own Client, pinned once to each era (mode="legacy", which negotiates 2025-11-25, and mode="2026-07-28"). In both, an unknown tool name still returns CallToolResult(is_error=True, "Unknown tool: ..."). Invalid arguments and a tool that raises both stay is_error=True, which is correct.

#1872 (approved in March) fixes this, but 11 files now conflict, and its resource half uses -32002, where MCPServer on main now returns -32602 for an unknown resource.

I have a narrow port ready locally. It adds a ToolNotFoundError(ToolError) subclass that carries the requested name, and the tools/call handler turns it into -32602 only when that name is the one in the request. call_tool() still raises ToolError, and subclass call_tool() overrides keep working.

On @maxisbey's question in #2422 (what a separate exception type gets you): here it's needed for subclasses that override call_tool(). Without overrides, the handler could just check the registry for the requested name. But an override can serve names that aren't registered, so only the exception raised by the failed lookup says the requested tool wasn't found. The name check keeps an override that looks up a different missing name at is_error=True. (A registered tool that calls a missing one already stays is_error=True, because Tool.run re-wraps the error.)

Would you rather have #1872 refreshed, or this port? I reported this and would like to fix it myself if you take an outside PR for it.

Disclosure: an AI assistant helped with the investigation and the draft patch.

Navigation Menu

Repository navigation

`MCPServer` answers an unknown tool with an `isError` result; the spec (and the TS SDK) use JSON-RPC `-32602` #3659

Summary

Reproduction

Notes

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

MCPServer answers an unknown tool with an isError result; the spec (and the TS SDK) use JSON-RPC -32602 #3659

Description

Summary

Reproduction

Notes

Activity

TINGyu123644 commented on Oct 9, 2026

ANcpLua commented on Oct 10, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

`MCPServer` answers an unknown tool with an `isError` result; the spec (and the TS SDK) use JSON-RPC `-32602` #3659