Depurar MCP cuando nada funciona, los 10 checks que resuelven el 90 por ciento de los casos

Tienes un servidor MCP en la config. Arrancas Claude Code. Tecleas /mcp. Pone "no servers" o el servidor está pero faltan los tools. O mejor todavía: el servidor aparece como "connected" pero en cada tool call sale "tool not found". Esa es la hora en la que la mayoría se rinde o empieza a reescribir rutas al azar.

Te doy aquí el orden que yo mismo recorro. Diez checks, cada uno dura uno o dos minutos, en el orden de manera que de media después de tres pasos sabes cuál es la causa.

Paso 1, leer claude --debug entero una vez

Cierra Claude Code, arranca de nuevo con claude --debug. En la consola corre ahora el logging verbose. Fíjate en tres tipos de línea: "MCP server connecting", "tool discovery", "MCP error". Las dos últimas líneas antes del primer error casi siempre te dicen qué está roto.

La documentación oficial sobre debug logging está en la MCP Integration skill: "running claude --debug ... will reveal details about MCP server connection attempts, the process of tool discovery, authentication flows, and any errors". Este es el único paso que de verdad no debes saltarte.

Paso 2, llamar /mcp en el chat

En la sesión en marcha: teclea /mcp. Obtienes una lista de tus servidores con estado. "connected" significa que la conexión está en pie. "failed" significa que la conexión nunca llegó a establecerse. "no tools" significa conectado pero sin tools descubiertos. Cada uno de estos tres estados tiene un diagnóstico distinto.

Apunta el estado antes de cambiar nada. Si reescribes la config a ciegas una vez, ya no sabes si el estado anterior era "failed" o "no tools".

Paso 3, el comando tiene que existir y ser ejecutable

Con servidores stdio (o sea npx, node, python) Claude Code hace en segundo plano un spawn sobre el comando que indicaste en la config. Si el comando no está en el PATH, o los node_modules no están instalados, o el script no tiene los execute bits, no vuelve nada.

Test: copia el comando exacto de tu config mcp a tu terminal y ejecútalo a mano. Si el servidor no arranca en tu terminal, tampoco arranca en Claude Code. Revisa la ruta, revisa los permisos (chmod +x), revisa si los node_modules están instalados.

Paso 4, stdout tiene que estar limpio

Los servidores MCP stdio se comunican por stdin/stdout en el formato JSON-RPC. Si tu servidor escribe un console.log o print('starting...') en stdout al arrancar, eso se mezcla en el stream JSON y Claude Code no puede parsear nada.

Cita de los docs de MCP integration sobre stdio troubleshooting: "ensure that your server correctly uses stdin/stdout for MCP messages and check for any unintended print or console.log statements that might interfere with the JSON-RPC stream".

Fix: redirige todos los statements de logging de tu código MCP a stderr. console.error en lugar de console.log en Node, sys.stderr en Python. Más un ajuste "no banner on startup" por si tu framework imprime uno.

Paso 5, la ruta en la config es absoluta

Las rutas relativas en las configs mcp son una de las fuentes de error más frecuentes. "./meine-skripte/server.js" no funciona porque Claude Code arranca desde un working directory distinto del que piensas. Escribe la ruta completa, /home/user/projekt/meine-skripte/server.js.

Lo mismo con las variables ENV: $HOME no se expande en la config si lo escribes como string. O bien la ruta completa o usa la sección env de la config si tu framework MCP lo soporta.

Paso 6, reinicio después de cada cambio de config

Los cambios en la config mcp NO se recargan en vivo. De los docs de troubleshooting: "If issues persist after making configuration changes, restart Claude Code to apply the updates". Cerrar del todo, arrancar de nuevo. Un reload no basta.

Suena trivial. Pero es la razón por la que la gente cree durante una hora "la ruta tiene que seguir mal" aunque la ruta lleva diez minutos correcta y simplemente no se dieron cuenta porque no corría ninguna sesión nueva.

Paso 7, MCP HTTP, el puerto está abierto y la auth es correcta

Con servidores MCP HTTP (remoto, Cloud Run, endpoint propio) los failure modes típicos son: puerto no alcanzable, URL incorrecta, header de auth ausente, token expirado. curl sobre el endpoint de health es tu primer test, luego mira los logs del servidor.

Importante: 401 o 403 NO son "broken". Esos son endpoints auth-required, tu token estaba mal o faltaba. "connection refused" o "timeout" son los problemas de conexión de verdad.

Paso 8, el nombre del tool hace match exacto

De los docs de tool usage: "Verify that tool names match exactly, as they are case-sensitive". Si tu servidor exporta nex_entity_create y tienes mcp__nex__nexEntityCreate en la lista allow, eso no hace match. Tool no disponible.

Checklist: mayúsculas-minúsculas, underscores vs camelcase, prefijo del servidor. Con plugins y bundles también el prefijo namespace. Si no está claro: llama /mcp una vez y copia los nombres de los tools exactamente como aparecen.

Paso 9, los permisos en settings.json bloquean el tool

Quizá tengas una lista permissions.deny o permissions.allow que bloquea el tool implícitamente. "mcp__*" como deny bloquea todos los tools MCP. Una lista allow demasiado estrecha deja pasar solo unos pocos.

Test: comprueba en .claude/settings.json (proyecto) y ~/.claude/settings.json (global) si hay una sección permissions que excluya tu tool. El Plan Mode también te dice en el transcurso "tool not allowed" si es el caso.

Paso 10, el malentendido del permission mode

Si estás en Plan Mode, no corre ningún tool, aunque todo esté configurado correctamente. Tecleas una tarea, Claude responde con un plan, no ves ningún tool call y piensas "el servidor está roto". En realidad todo funciona, solo estás en el permiso equivocado.

Cicla con Shift+Tab hasta que aparezca "default" o "acceptEdits". Luego inténtalo de nuevo. Quien se pasa un día entero buscando desesperado un bug de MCP y al final era el Plan Mode, no se le olvida nunca más. Pregúntame cómo lo sé.

Qué sigue

Cuando tu servidor vuelva a funcionar, lee el recipe phase-7-mcp-patterns/7.5-error-handling para un patrón de errores sensato en tu código MCP. Para servidores propios vale la pena el playbook erster-mcp-server-in-90-minuten más mcp-server-publishen si quieres distribuir. Y si haces malabares a menudo entre varios servidores: tool-sprawl-vermeiden ayuda a mantener baja la carga.

Source

• Debug logging y MCP Integration: https://code.claude.com/docs/en/mcp y https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/mcp-integration/SKILL.md
• stdio troubleshooting: https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/mcp-integration/references/server-types.md
• Tool usage y nota de restart: https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md
• Plan Mode y permission modes: https://code.claude.com/docs/en/interactive-mode