MCP Error -32601 Method Not Found: How to Fix It (Claude Code, Inspector, Python and TypeScript SDKs)

MCP error -32601 means "Method not found": one side sent a JSON-RPC method the other side has no handler for. In MCP the usual cause is an era mismatch, where a method from the 2025 spec revisions reaches a 2026-07-28 peer (or the reverse). The other common cause is a server that never registered an optional feature, such as completions or resources. The fastest fix is to let both sides negotiate the protocol version automatically and to check the server's declared capabilities before calling optional methods.

Checked against: the JSON-RPC 2.0 specification, the 2026-07-28 changelog and Streamable HTTP page, and the Python SDK troubleshooting page on 2 November 2026 (Python mcp 2.3.0, TypeScript @modelcontextprotocol/server 2.4.0). eSEOspace did not run these steps.

What this error means

The JSON-RPC 2.0 spec reserves -32601 for a method that "does not exist / is not available." In MCP, a method is something like tools/list, resources/read or subscriptions/listen. Tools themselves are not methods: calling a tool sends the tools/call method with a tool name, and an unknown tool name returns -32602. See -32602 invalid params.

The 2026-07-28 revision changed which methods exist. Its changelog lists:

So a 2025-era message sent to a modern-only peer, or a modern-only method sent to a legacy peer, can come back as -32601. The Python SDK troubleshooting page gives two examples: "a 2025-era resources/subscribe arriving at a 2026-07-28 connection, or a 2026-only subscriptions/listen sent by a client pinned to mode="legacy"." It adds that e.error.data names the method.

On HTTP, the Streamable HTTP page says a server that does not implement the requested method "MUST respond with 404 Not Found and a JSON-RPC error with code -32601." The JSON body is what separates it from a plain 404 from a legacy server that has no modern endpoint.

Quick fix

1. Find the method name. Check error.data, the client log, or the server log.
2. Check which era each side speaks. If the method is in the table above, you have an era mismatch.
3. Switch the client to automatic negotiation. Do not pin a single version or force legacy mode unless you need it.
4. Check server capabilities. Before calling completion/complete, resources/* or prompts/*, confirm the server declared that capability.
5. Update the older side. Current official SDKs handle both eras as clients.

Fix by client / OS

Claude Code

Claude Code's MCP docs say its v2 runtime asks HTTP and stdio servers whether they support 2026-07-28 and uses it with those that do. If a server answers the probe badly, set MCP_PROTOCOL_NEGOTIATION=legacy so every server connects with the older handshake. The environment variables page says this needs Claude Code v2.1.221 or later.

TypeScript client

The TypeScript SDK troubleshooting guide has a close cousin: SdkError: METHOD_NOT_SUPPORTED_BY_PROTOCOL_VERSION. The SDK raises it locally, before anything is sent, and the message names the replacement. Its example: subscriptions/listen requires a 2026-07-28-era connection (negotiated: 2025-11-25). Either negotiate the modern era with versionNegotiation: { mode: 'auto' }, or call the method the negotiated era defines.

Python client and server

On the client, keep the default mode="auto". On the server, register a handler for each optional feature you advertise. The Python SDK's completions page says that without a completion handler, the request is Method not found, and the completions capability "appears the moment you register the handler."

MCP Inspector

Set the server's Protocol Era to auto, or pass --protocol-era auto to the CLI, per the Inspector protocol eras page. The default is legacy, which sends a plain initialize. Against a modern-only server, that alone can fail. See Inspector connection errors.

Where to find the logs

• Claude Code: claude --debug-file /tmp/claude-debug.log.
• VS Code: MCP: List Servers > Show Output, per the manage and troubleshoot page.
• Claude Desktop: ~/Library/Logs/Claude/mcp*.log (macOS) or %APPDATA%\Claude\logs (Windows), per the MCP debugging guide.
• Your server: log the incoming method for every error response.

If it still fails

• Method is initialize. A legacy client reached a modern-only server. The spec's compatibility matrix says that combination fails; the server needs dual-era support, or the client needs an update. See protocol version mismatch.
• Method is ping. It was removed in 2026-07-28. Use an ordinary request or HTTP health check instead.
• HTTP 404 with no JSON body. That is a wrong URL or a legacy HTTP+SSE server, not -32601. See SSE transport deprecated.
• Custom method names. Methods outside the spec only work if both sides implement them.
• Look up the code in our MCP error code lookup or browse revisions in the spec version explorer.

Next step

If you are upgrading a server to 2026-07-28 and need it to keep serving older clients, eSEOspace's MCP development team can help plan the migration. Our JSON-RPC messages reference covers the message shapes.

Frequently asked questions