MCP tool call failing with -32601, -32602, or -32700? What each JSON-RPC error means

You're connecting an MCP server — your own, or a client to someone else's — and the tool calls come back with a bare JSON-RPC error code: -32601, -32602, or -32700. They're terse, but each points at a specific, common mistake. Here's how to read them.

-32601: Method not found (the #1 MCP mistake)

This is the one nearly everyone hits first. In MCP, the only top-level JSON-RPC methods are initialize, tools/list, and tools/call. Tools are not top-level methods — you call a tool through tools/call, passing its name in the params:

// WRONG — returns -32601 method not found:
{"jsonrpc":"2.0","id":1,"method":"my_tool","params":{...}}

// RIGHT — call the tool through tools/call:
{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"my_tool","arguments":{...}}}

If you're getting -32601 on a tool that clearly exists, this is why. The tool result comes back in result.content[0].text as a JSON string — parse it.

-32602: Invalid params

The method exists and you called it right, but the arguments don't match the tool's inputSchema — a missing required field, a wrong type, an extra property a strict schema rejects. Two things to check:

• Your arguments against the schema. Fetch the tool's inputSchema from tools/list and validate before calling.
• A silently-empty inputSchema. If you authored the server and your schema serialized to empty (a common Zod-vs-JSON-Schema conversion gotcha), the client can't send valid params. Confirm tools/list returns the real schema, not {}.

-32700: Parse error (usually stdout corruption)

On a stdio transport, the server speaks JSON-RPC over stdout — and so does every stray print(), log line, or debug banner your process emits. When those interleave with the protocol messages, the client gets malformed JSON and returns -32700.

Quick reference

For agents (and agent builders)

These are the errors an agent hits when connecting to any MCP server — including debugging your own. diagnose_infra_error returns the mcp / mcp-tools family with the specific fix, so an agent (or you) resolves the connection instead of guessing at a terse code:

diagnose_infra_error({error: "-32601 method not found"})
// → { family: "mcp", fix: "call the tool via tools/call with the name in params, not as a top-level method" }

Snapback is itself an MCP server — see the docs for the connect flow and the skill guide for a worked example.