Tool … not found (-32602) / Unknown tool
- Spec
2026-07-28- Evidence
- E2Reproducedarm64
- TypeScript SDK (server)
@modelcontextprotocol/server@2.4.0- Python SDK
mcp@2.3.0- Verified
What it means
Section titled “What it means”We called a tool named nope that the server does not define. The two SDKs report it differently:
| Server | Response |
|---|---|
| TypeScript SDK v2 | JSON-RPC error {"code":-32602,"message":"Tool nope not found"}; clients show MCP error -32602: Tool nope not found (v1) or a ProtocolError (v2) |
| Python SDK 2.3.0 | A normal result with isError: true and the text Unknown tool: nope |
The client uses an old tool list
Section titled “The client uses an old tool list”Clients cache the tool list. If you renamed or removed a tool and restarted only the server, the client may still offer the old name to the model. Restart the client or reload its MCP servers. A server whose tools change at runtime should announce it: in 2026-07-28 clients listen with subscriptions/listen and the server sends notifications/tools/list_changed.
The name is case-sensitive and must match exactly. Some clients add a prefix such as the server name when they show tools to the model; the prefix is not part of the name the server receives.
The tool is registered only sometimes
Section titled “The tool is registered only sometimes”If registration depends on an environment variable, a feature flag or the authenticated user, two server instances may disagree. On a stateless HTTP deployment, tools/list and tools/call can land on different instances, or on instances built for different users. Register the same tools for the same caller every time.
Related
Section titled “Related”MCPDev is community documentation. It is not affiliated with the Model Context Protocol project or with the vendors of the clients it covers.