Fix MCP Error -32601: Method Not Found - Debugging Guide

Fixing "Method not found (-32601)" JSON-RPC errors

Kashish Hora

Co-founder of MCPcat

The Quick Answer

The JSON-RPC error -32601 "Method not found" occurs when calling an unimplemented MCP method. Debug by checking server capabilities and method names:

# List available methods using MCP inspector
$npx @modelcontextprotocol/inspector "node /path/to/your/server.js"

// Verify method exists in server capabilities
{
  "capabilities": {
    "tools": true,
    "resources": false,  // If false, resource methods will return -32601
    "prompts": false     // If false, prompt methods will return -32601
  }
}

This error means your server received the request but doesn't implement that specific method. Check which capabilities your server advertises during initialization.

Prerequisites

MCP server running (any language/framework)
Client configured to connect (Claude Desktop, custom client, etc.)
Basic understanding of JSON-RPC protocol
Access to server logs for debugging

Understanding the Error

The -32601 error is a standard JSON-RPC error code indicating the requested method doesn't exist on the server. In MCP context, this typically happens when clients call methods the server hasn't implemented.

MCP servers don't need to implement every possible method. During the initialization handshake, servers declare their capabilities, telling clients which features they support. When a client calls an unsupported method, the server responds with this error.

// Standard JSON-RPC error response
{
  "jsonrpc": "2.0",
  "id": 123,
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": {
      "method": "resources/list"  // The method that wasn't found
    }
  }
}

The error structure follows JSON-RPC 2.0 specification exactly. The code field always contains -32601 for method not found errors, while message provides human-readable context.

Debugging Steps

Start debugging by identifying exactly which method is failing and why your server doesn't support it.

1. Enable Verbose Logging

// Add detailed logging to your MCP server
server.on('request', (method, params) => {
  console.log(`Received request: ${method}`, params);
});

server.on('error', (error) => {
  console.error('Server error:', error);
});

2. Check Server Capabilities

// Ensure your server advertises correct capabilities
const server = new Server({
  name: 'my-mcp-server',
  version: '1.0.0',
  capabilities: {
    tools: true,      // Enable tool methods
    resources: true,  // Enable resource methods
    prompts: true     // Enable prompt methods
  }
});

Capabilities control which method groups your server supports. If a capability is false or missing, all methods in that group will return -32601.

3. Verify Method Implementation

// Common MCP methods that must be implemented
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return { tools: [...] };
});

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

// If you advertise resources capability, implement these:
server.setRequestHandler(ListResourcesRequestSchema, async () => {
  return { resources: [...] };
});

4. Use MCP Inspector

# Interactive debugging tool for MCP servers
$npx @modelcontextprotocol/inspector "node server.js"
 
# For Python servers
$npx @modelcontextprotocol/inspector "python server.py"

The inspector shows all available methods and lets you test them interactively. If a method returns -32601 here, it's definitely not implemented.

Common Causes and Solutions

Missing Handler Registration

The most common cause is forgetting to register a handler for a specific method. Each MCP method needs explicit handler registration.

// Wrong: Capability enabled but handler missing
const server = new Server({
  capabilities: { tools: true }
});
// No tool handlers registered = -32601 errors

// Correct: Register all required handlers
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return { 
    tools: [
      {
        name: "get_data",
        description: "Retrieves data",
        inputSchema: { type: "object", properties: {} }
      }
    ] 
  };
});

Incorrect Method Names

MCP method names follow specific patterns. Using wrong names causes -32601 errors.

// Wrong method names
"method": "list_tools"      // Should be "tools/list"
"method": "callTool"        // Should be "tools/call"
"method": "getResources"    // Should be "resources/list"

// Correct MCP method names
"method": "tools/list"
"method": "tools/call"
"method": "resources/list"
"method": "resources/read"
"method": "prompts/list"
"method": "prompts/get"

Client-Server Version Mismatch

Different MCP versions may support different methods. Ensure compatible versions between client and server.

// Check versions in package.json
{
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0"  // Use consistent versions
  }
}

Capability Mismatch

Servers must explicitly enable capabilities for method groups to work.

# Python MCP server example
async def handle_initialize(params):
    return {
        "capabilities": {
            "tools": True,      # Must be True for tool methods
            "resources": False, # Resource methods will fail with -32601
            "prompts": False    # Prompt methods will fail with -32601
        }
    }

Examples

Example 1: Minimal Server with Proper Error Handling

Here's a minimal MCP server that correctly handles method requests and avoids -32601 errors:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
  ListToolsRequestSchema,
  CallToolRequestSchema,
} from '@modelcontextprotocol/sdk/types.js';

const server = new Server({
  name: 'debug-server',
  version: '1.0.0',
  capabilities: {
    tools: true  // Only enable what we implement
  }
});

// Implement all methods for enabled capabilities
server.setRequestHandler(ListToolsRequestSchema, async () => {
  console.log('Handling tools/list request');
  return {
    tools: [{
      name: 'echo',
      description: 'Echoes input back',
      inputSchema: {
        type: 'object',
        properties: {
          message: { type: 'string' }
        }
      }
    }]
  };
});

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  console.log('Handling tools/call request:', request.params.name);
  
  if (request.params.name === 'echo') {
    return {
      content: [
        {
          type: 'text',
          text: `Echo: ${request.params.arguments?.message || 'No message'}`
        }
      ]
    };
  }
  
  throw new Error(`Unknown tool: ${request.params.name}`);
});

// ... error handling and transport setup

This server only enables the tools capability and implements both required tool methods. Resource and prompt methods will correctly return -32601 since those capabilities are disabled.

Example 2: Debugging Client Requests

When debugging -32601 errors from a client, add comprehensive logging:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const client = new Client({
  name: 'debug-client',
  version: '1.0.0'
});

// Wrap requests with error handling
async function safeRequest(method: string, params?: any) {
  try {
    console.log(`Calling ${method} with params:`, params);
    const result = await client.request({ method, params });
    console.log(`Success:`, result);
    return result;
  } catch (error: any) {
    if (error.code === -32601) {
      console.error(`Method '${method}' not found on server`);
      console.error('Available capabilities:', client.serverCapabilities);
    } else {
      console.error(`Request failed:`, error);
    }
    throw error;
  }
}

// Test various methods
await safeRequest('tools/list');
await safeRequest('resources/list');  // May fail with -32601
await safeRequest('prompts/list');    // May fail with -32601

Production implementations would include retry logic, fallback behavior, and user-friendly error messages. The logging shown here helps identify exactly which methods are failing during development.

Example 3: Custom Error Handling

Implement custom error responses with additional debugging information:

from mcp.server import Server
from mcp.server.models import InitializationOptions
import json

class DebugServer(Server):
    async def handle_request(self, request):
        try:
            # Log all incoming requests
            print(f"Received: {request.method}")
            
            # Check if method is implemented
            if not hasattr(self, f"handle_{request.method.replace('/', '_')}"):
                return {
                    "jsonrpc": "2.0",
                    "id": request.id,
                    "error": {
                        "code": -32601,
                        "message": "Method not found",
                        "data": {
                            "method": request.method,
                            "available_methods": self.get_available_methods(),
                            "hint": "Check server capabilities"
                        }
                    }
                }
            
            # Process normally
            return await super().handle_request(request)
            
        except Exception as e:
            print(f"Error handling {request.method}: {e}")
            raise
    
    def get_available_methods(self):
        """List all implemented methods based on capabilities"""
        methods = ["initialize", "ping"]
        if self.capabilities.get("tools"):
            methods.extend(["tools/list", "tools/call"])
        if self.capabilities.get("resources"):
            methods.extend(["resources/list", "resources/read"])
        return methods

This enhanced error handling provides clients with helpful debugging information when methods fail. The response includes available methods and hints about checking capabilities.

Related Guides

Understanding the JSON-RPC protocol and how it's used in MCP

Understand how JSON-RPC 2.0 protocol powers MCP client-server communication and message structure.

Debugging message serialization errors in MCP protocol

Debug and fix MCP message serialization errors with proven troubleshooting techniques.

Building an MCP server in TypeScript

Build type-safe MCP servers using TypeScript with full SDK support and production best practices.

Keep an eye on AI.

Get rich user analytics and tracing on every user interacting with your MCP server.

Get started