MCP Error -32601: Method Not Found — Causes and Fixes

Quick Answer

MCP Error -32601 is the JSON-RPC 2.0 "Method not found" error. It fires when the receiving endpoint — your MCP server or, less commonly, your client — receives a request for a method it has no handler for. This is a dispatch failure, not a network failure. The connection is alive; the JSON-RPC message was parsed; but the method name in the method field mapped to nothing.

The fastest diagnostic path:

1. Find the exact method name from the error response or your logs.
2. Check it against the MCP specification methods.
3. Confirm the server declared the relevant capability during initialization.
4. Verify client and server are running compatible MCP versions.

MCP Error -32601: 60-Second Fix Checklist

• Capture the exact method name from the failing JSON-RPC request
• Identify which side returned the error (server is most common)
• Check for typos — method names are case-sensitive and slash-delimited
• Confirm MCP initialization (initialize / initialized) completed before calling the method
• Inspect the capabilities object in the server's initialize response
• Verify the server explicitly declares the capability for the requested feature (tools, resources, prompts)
• Check that client and server MCP protocol versions match
• Review server code to confirm the method handler is registered
• Check reverse proxy or gateway routing — the request must reach the correct backend
• Reproduce with MCP Inspector and confirm the method succeeds after your fix

What Does MCP Error -32601 Mean?

The JSON-RPC 2.0 specification reserves error code -32601 for the condition "Method not found". In JSON-RPC, every request carries a method field — a string like tools/list or resources/read. When the receiving endpoint processes the message, it looks up that string in its dispatch table. If nothing is registered for it, it returns:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

The Model Context Protocol is built on JSON-RPC 2.0, so it inherits this error directly. MCP does not define its own replacement for -32601.

Key distinction: -32601 is a method dispatch failure, not a network error, not an authentication failure, and not a tool-execution failure. The TCP connection is established, the JSON was valid, and the server understood the envelope — it simply has no registered handler for the method string it received.

A common misconception: calling tools/call with a tool name that does not exist is not the same as -32601. The MCP method tools/call exists; the server may return a different application-level error if the named tool is absent. If you see -32601 on tools/call, the entire method handler is missing from the server, not just the specific tool.

Common Causes of MCP Error -32601

MCP Methods to Check First

The following table covers the core MCP methods defined in the specification. Not every server supports every method — support depends on what the server declares in its capabilities during initialization.

Important: Capabilities are opt-in. A server that only implements tools does not need to support resources, prompts, or logging. Calling an unsupported capability may produce -32601, but behavior varies by implementation — some servers return -32601, others return a different error, and some ignore the request.

MCP Error -32601 During tools/list or tools/call

These two methods generate the most -32601 reports because tools are the most commonly used MCP feature.

Step 1: Check the initialize response

After initialization, the server returns a capabilities object. A server that supports tools will include:

{
  "capabilities": {
    "tools": {}
  }
}

If tools is absent from capabilities, the server is telling you it does not support tool operations. Calling tools/list against it will produce -32601 (or similar) because no handler was registered.

Step 2: Verify initialization sequencing

MCP requires the client to send initialize, receive the server's response, then send the initialized notification before making other requests. If your client calls tools/list before this handshake completes, the server may not have finished registering handlers and can return -32601.

Client → Server: initialize
Server → Client: initialize result (capabilities)
Client → Server: initialized (notification)
--- handshake complete ---
Client → Server: tools/list  ← safe to call here

Step 3: Verify server-side handler registration

If you control the server code, confirm the handler is actually registered. In the TypeScript MCP SDK:

// Correct — handler registered
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return { tools: [...] };
});

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  // handle tool call
});

If these lines are missing or the schema import is wrong, the method dispatcher has nothing to call and returns -32601.

Step 4: Check routing in proxied environments

If your MCP server sits behind a reverse proxy, API gateway, or load balancer, verify that:

• The MCP-specific path is correctly forwarded to the MCP server process
• Multiple backend instances are all running the same server version
• No path rewriting strips or alters the request before it reaches the server

MCP Error -32601 After a Client or Server Update

An update is one of the most common triggers for sudden -32601 errors on a previously working setup.

What changes between versions:

• Method names that were renamed or removed in a newer spec revision
• Capability flags that changed semantics or became required
• SDK handler registration APIs that changed signatures
• Custom methods that one side updated but the other did not

Diagnosis steps after an update:

1. Check the changelog of the updated component for method renames or removals.
2. Compare the protocolVersion strings exchanged during initialization — a mismatch signals incompatibility.
3. Test client and server independently using MCP Inspector before reconnecting them.
4. If one side uses a custom method, confirm both sides were updated together.
5. Roll back one component at a time to isolate which update introduced the error.

SDK version drift is a specific trap: if your server uses an older SDK that registers handlers under old method names while your client sends the new method names (or vice versa), every request for affected methods will return -32601.

MCP Error -32601 in Claude, Cursor, and Other MCP Clients

The underlying error is always JSON-RPC -32601. What differs across clients is how they trigger it.

• Claude Desktop configures MCP servers via a local config file. If the config points to a server binary that doesn't exist, loads the wrong version, or fails to start, the "server" that responds may not be a valid MCP implementation at all — leading to -32601 on any method.
• Cursor manages its own MCP server connections. A -32601 in Cursor most often means the server it connected to doesn't support the method Cursor is requesting, or the server process crashed and a fallback is responding.
• Any OAuth-protected MCP client: If the bearer token is invalid and an error-returning proxy intercepts the call before it reaches your server, the response may look like -32601 because the proxy has no MCP method handlers.

In all cases, the diagnostic path is the same: capture the raw JSON-RPC request and response, identify the failing method name, and verify server capabilities and routing.

If you're debugging Claude-specific MCP connection issues, the MCP failed to connect troubleshooting guide covers environment and process startup problems that can indirectly produce method dispatch errors.

How to Debug MCP Error -32601 with MCP Inspector

MCP Inspector is the official interactive testing tool for MCP servers. It connects to your server, completes the handshake, and lets you call methods manually — making it ideal for isolating -32601 causes.

Connect to your server

For a stdio server:

npx @modelcontextprotocol/inspector node ./build/index.js

For an HTTP/SSE server:

npx @modelcontextprotocol/inspector --url http://localhost:3000/sse

What to inspect

1. Initialization result — MCP Inspector displays the server's full initialize response. Check the capabilities object. If tools, resources, or prompts are absent, the server won't respond to those method families.

2. Available methods — After connecting, attempt to call the specific method that returned -32601. Inspector shows the raw request sent and the raw response received.

3. Capability vs. method mismatch — If the capability is declared but the method still returns -32601, the handler registration in the server code is the problem. If the capability is absent, the server intentionally doesn't support it.

4. Isolating client vs. server — MCP Inspector is your reference client. If Inspector can call a method successfully but your application client returns -32601, the problem is in your client: wrong method name, wrong initialization sequence, or incompatible version. If Inspector also gets -32601, the problem is the server.

You can also test your live MCP server directly at MCPForge's MCP Server Test tool to quickly verify initialization and method availability without setting up a local Inspector session.

MCP Error -32601 Troubleshooting Table

Notifications vs. Requests — A Subtle Source of -32601

MCP, like JSON-RPC, distinguishes requests (which expect a response) from notifications (which do not). A notification has no id field.

If you accidentally send a notification where a request is expected, or vice versa, you may get unexpected -32601 responses. For example, initialized is a notification — sending it with an id as if it were a request can confuse some server implementations.

Conversely, some MCP events like notifications/tools/list_changed are server-to-client notifications. If your client tries to call this as a request method on the server, you'll get -32601 because the server has no handler for it as an inbound request.

SDK Implementation Mistakes That Produce -32601

If you're building an MCP server with an SDK, these are the most common code-level causes:

TypeScript SDK — handler not registered:

// Missing handler — tools/list will return -32601
const server = new Server({ name: 'my-server', version: '1.0.0' }, {
  capabilities: { tools: {} }  // capability declared...
});
// ...but no setRequestHandler for ListToolsRequestSchema
// This is inconsistent and will cause -32601

Correct pattern:

const server = new Server({ name: 'my-server', version: '1.0.0' }, {
  capabilities: { tools: {} }
});

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      { name: 'search', description: 'Search the web', inputSchema: { type: 'object', properties: {} } }
    ]
  };
});

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === 'search') {
    // handle search tool
  }
  throw new Error(`Unknown tool: ${request.params.name}`);
});

Python SDK — missing handler:

# Capability declared but handler missing will cause -32601
@server.list_tools()
async def list_tools() -> list[Tool]:
    return [Tool(name="search", description="Search", inputSchema={})]

# Without a corresponding @server.call_tool() handler,
# tools/call will return -32601
@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
    if name == "search":
        return [TextContent(type="text", text="results")]
    raise ValueError(f"Unknown tool: {name}")

Declaring a capability in the server options without registering the corresponding request handler is the single most common SDK mistake. The SDK declares the capability but has nothing to dispatch the method to.

How to Confirm the Fix

After applying a fix, verify all of the following before closing the issue:

• The initialize exchange completes without errors
• The server's capabilities object includes the feature you're using
• The protocolVersion is the same on both sides
• The specific method that failed now returns a valid result
• No -32601 appears in server or client logs
• MCP Inspector can successfully call the method
• Your application-level operation (tool call, resource read, etc.) completes successfully end-to-end

If MCP Inspector succeeds but your application still fails, the remaining issue is in how your client constructs or sequences its requests — not in the server.

How to Prevent MCP Method Not Found Errors

Use official MCP SDKs. They handle the initialization lifecycle, capability negotiation, and method registration correctly by default. Hand-rolled JSON-RPC implementations frequently miss edge cases.

Always respect the initialization handshake. Never send method requests until the initialize → initialized cycle completes. Build explicit sequencing into your client startup code.

Check capabilities before calling optional methods. Read the server's capabilities object from the init response before calling tools/list, resources/list, prompts/list, or any logging or completion methods. Calling unsupported capabilities is a preventable error.

Validate method names at the source. If you're generating method names dynamically (e.g., from config), add a validation step that checks the generated string against the spec's defined methods before sending.

Keep client and server versions aligned. Pin your MCP SDK versions in both components. When upgrading, update both sides together and run your integration test suite immediately after.

Test with MCP Inspector after every change. Make Inspector part of your development workflow — run it against your server whenever you modify handler registration, add capabilities, or change protocol handling.

Document and coordinate custom methods. If you implement non-standard MCP extensions, treat them like an API contract: version them, document them, and ensure every consumer is updated before deployment.

Maintain integration tests. Write tests that cover the initialize handshake, each supported method, and capability negotiation. These catch -32601 regressions before they reach production. The MCP Inspector complete guide explains how to automate server validation in CI.

For related transport-level errors that can accompany -32601 in degraded environments, see the MCP error codes reference and MCP Error -32603 (Internal Error) guide.

FAQ

What does MCP Error -32601 mean? It is the standard JSON-RPC 2.0 "Method not found" error. The server received a valid JSON-RPC request but has no registered handler for the method name in the method field. It is a dispatch failure, not a connectivity failure.

How do I fix MCP Method Not Found? Capture the exact method name, verify it exists in the MCP spec, confirm initialization completed, check the server's declared capabilities, and ensure the method handler is registered in the server. Use MCP Inspector to reproduce the call and isolate whether the problem is client-side or server-side.

Is -32601 an MCP-specific error code? No. It is defined in the JSON-RPC 2.0 specification. MCP uses JSON-RPC 2.0 as its messaging layer and inherits all standard JSON-RPC error codes including -32601.

Why does tools/list return -32601? Most commonly because the server did not declare the tools capability in its initialize response, or because the server's ListToolsRequestSchema handler was never registered. Check both.

Why does tools/call return Method Not Found? tools/call returning -32601 means the server has no handler for the tools/call method at all — not that a specific tool name is missing. A missing tool name inside a valid tools/call handler produces a different, application-level error. Verify the server declares tools capability and registers the CallTool handler.

Can an MCP version mismatch cause -32601? Yes. Methods introduced in newer MCP versions won't have handlers in an older server. Methods renamed between versions will also produce -32601. Always ensure the protocolVersion strings in the initialize exchange match.

Can a reverse proxy cause Method Not Found? Indirectly. If a reverse proxy routes MCP traffic to the wrong backend — one that doesn't implement the requested method — that backend returns -32601. Always trace request routing in proxied deployments.

Why does one MCP client work while another returns -32601? Clients may request different methods, use different protocol versions, or trigger different capability negotiation paths. A working client may only use methods the server supports; a failing client may request additional methods outside the server's declared capabilities.

How do I find which MCP method caused the error? Enable debug logging on both sides. The JSON-RPC request that preceded the error contains the method field — that string is what failed to dispatch. MCP Inspector also shows raw requests and responses for every call.

Can MCP Inspector help diagnose -32601? Yes — it's the best tool for this. Inspector connects to your server, shows the full capabilities from initialization, and lets you call methods interactively. If Inspector gets -32601, the server is the problem. If Inspector succeeds but your app fails, your client code is the problem.

Official Sources

• JSON-RPC 2.0 specification - authoritative reference for -32601 Method not found.
• MCP base protocol overview - official MCP request, response, and notification structure.
• MCP tools specification - official tools/list and tools/call method behavior.