Error MCP -32601: Método No Encontrado – Guía Completa de Corrección y Solución de Problemas 2026

Conclusiones clave

• Error MCP -32601 "Método no encontrado" es un error estándar JSON-RPC 2.0 que ocurre cuando un cliente solicita un método que el servidor MCP no implementa o no ha anunciado en sus capacidades.
• Las causas principales incluyen probes de métodos opcionales (resources/list, prompts/list, elicit), desajustes de versiones entre SDKs de cliente y servidor, y declaraciones incompletas de capacidades.
• La mayoría de los casos son benignos y esperados; los errores persistentes se resuelven usando el Inspector MCP oficial y alineando las implementaciones.
• Común en Claude Desktop, Cursor, Continue.dev y servidores custom construidos con FastMCP, Spring AI o McpSharp.

Comprendiendo el error "Método no encontrado" de MCP

El Protocolo de Contexto del Modelo (MCP) estandariza la comunicación entre clientes AI (Claude, Cursor, etc.) y servidores externos para herramientas, recursos y prompts usando JSON-RPC 2.0 sobre varios transportes.

La respuesta de error típicamente se ve así:

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

Este indica que el método solicitado (e.g., tools/call, resources/list, prompts/list, o métodos relacionados con elicitación) es desconocido para el servidor. A diferencia de errores de conexión o parseo, la capa de transporte usualmente tiene éxito — el problema está al nivel del protocolo.

Reportes de la comunidad e issues en GitHub muestran que este error frecuentemente aparece durante la discovery de capacidades o cuando los clientes asumen un soporte más amplio que el que el servidor provee.

Causas comunes

Análisis de issues recientes (2025–2026) resalta estos triggers:

• Métodos Opcionales No Implementados: Los servidores MCP no están obligados a soportar todas las funcionalidades. Los clientes como Claude Desktop frecuentemente prueban los métodos resources/list, prompts/list, o elicitation, provocando -32601 si están ausentes.
• Gaps en la Publicación de Capacidades: La respuesta initialize del servidor no declara correctamente las capacidades soportadas, llevando a los clientes a llamar métodos no soportados.
• Desajustes de SDK y Versiones: Versiones diferentes de @modelcontextprotocol/sdk, FastMCP, Spring AI MCP, o McpSharp causan incompatibilidad. Usuarios de Java frecuentemente resuelven esto cambiando a JDK 21.
• Comportamiento Específico del IDE/Cliente: El chat del agente Cursor puede reportar "No MCP resources available" junto con errores de método. Los logs de Claude muestran repetidas veces "Method not found: resources/list".
• Solicitudes de Elicitación: FastMCP y frameworks similares arrojan McpError durante la elicitación de entrada del usuario si no están completamente soportados por el cliente.
• Implementaciones Custom o Minimales: Servidores hechos "hand-rolled" sin manejo de errores apropiado o soporte completo de primitivas (initialize, tools/list, tools/call) fallan bajo clientes reales.
• Issues de Transporte/Proxy: En configuraciones con Docker, ngrok, o proxy inspector, problemas de routing pueden manifestarse como errores de método.

Troubleshooting paso a paso y fixes

1. Usar el Inspector MCP para diagnóstico

La herramienta oficial es la forma más rápida para validar tu servidor:

# Node.js / TypeScript
npx @modelcontextprotocol/inspector "node your-server.js"

# Python
uvx mcp-inspector "python your_server.py"

El inspector muestra las capacidades, permite probar métodos interactivamente y revela exactamente qué métodos devuelven -32601. Si un método falla aquí, no está implementado en el servidor.

2. Inspecciona y Declara las Capacidades Correctamente

Durante el intercambio initialize, el servidor debe devolver capacidades exactas. Ejemplo de estructura:

{
  "capabilities": {
    "tools": {
      "listChanged": true
    },
    "resources": false,
    "prompts": false
  }
}

Establece explícitamente las características no soportadas como false o omítelas para evitar sondas innecesarias.

3. Alinea Versiones y Dependencias

• Actualiza el cliente y el servidor a versiones del SDK de MCP coincidentes.
• Para Java/Spring AI: Configura JAVA_HOME a JDK 21+ y limpia las cachés.
• Para Cursor/Claude: Reinicia la aplicación y refresca las configuraciones de MCP después de actualizaciones.
• Retrocede a versiones anteriores estables (e.g., Cursor 0.45 en reportes antiguos) si una versión reciente introdujo incompatibilidad.

4. Revisa los Registros Detalladamente

• En el lado del servidor: Confirma el nombre exacto del método que llega y cómo se redirige.
• En el lado del cliente: Revisa los registros de Claude (~/Library/Logs/Claude/ en macOS), la salida de la extensión de Cursor, o la consola de Continue.dev.
• Busca secuencias: initialize exitoso seguido por llamadas fallidas de métodos opcionales.

5. Maneja Métodos Opcionales y Casos Extremos

• Trata el -32601 para métodos opcionales como no fatal en el código del cliente donde sea posible.
• Para herramientas con mucha elicitación: Implementa fallos elegantes o desactiva la característica si el cliente objetivo (e.g., CLI de Gemini o ciertos modos de Cursor) no tiene soporte.
• En servidores personalizados: Siempre responde con el formato de error JSON-RPC apropiado, en lugar de bloquearse o exceder el tiempo de espera.

Consejos Avanzados y Errores Comunes

• Sondas de Recursos y Prompt: Muchos servidores registran “Method not found: resources/list” sin impacto — ignora estos si las herramientas principales funcionan.
• Configuraciones Docker y Remotas: Verifica el reenvío de puertos, las verificaciones de salud y que las solicitudes POST llegan al manejador correcto. Los errores 405 a veces acompañan -32601.
• Estrategia de Pruebas: Siempre prueba primero con el Inspector MCP, luego con múltiples clientes (Claude Desktop, Cursor, Continue.dev). Usa llamadas JSON-RPC directas mediante curl para validación de bajo nivel.
• Imitadores Relacionados con Rendimiento: Llamadas de herramientas de larga ejecución con tiempos de espera (común en Spring AI) pueden manifestarse downstream como errores de método.
• Servidor Mínimo Viable: Implementa al menos initialize, tools/list, tools/call, y ping. Agrega registros robustos para cada solicitud entrante.

Mejores Prácticas de Prevención

• Adherirse estrictamente a la última especificación del MCP para códigos de error y respuestas de capacidades.
• Usar SDKs oficiales siempre que sea posible, en lugar de implementaciones desde cero.
• Incluir registro integral y negociación de versiones en servidores de producción.
• Monitorizar regularmente la organización GitHub de modelcontextprotocol para actualizaciones y cambios disruptivos.
• Testear exhaustivamente la detección de capacidades — esto previene la mayoría de los problemas -32601 en uso real.

Los desarrolladores que anuncian claramente las capacidades y manejan métodos opcionales de manera elegante reportan significativamente menos tickets de soporte.

Conclusión

El error del MCP -32601 “Método no encontrado” usualmente es un comportamiento esperado para características opcionales del protocolo, más que un fallo crítico. Diagnóstico sistemático con el Inspector MCP, declaración apropiada de capacidades, y alineación de versiones resuelven casi todos los casos.

Mantén tus servidores y clientes MCP actualizados mientras el ecosistema continúa madurando en 2026. Para problemas persistentes, comparte el JSON de capacidades de tu servidor, los registros exactos del método, y la versión del cliente en repositorios GitHub relevantes o foros de la comunidad para asistencia comunitaria más rápida.

Implementa estas prácticas para construir integraciones MCP más robustas y compatibles.