Error de conexión del servidor MCP en Claude Code: causas y soluciones

Has configurado un servidor MCP (Model Context Protocol), pero al abrir /mcp aparece atascado en un estado como este: ¿te suena?

/mcp

  filesystem      ✓ connected      (12 tools)
  github          ✗ failed
  notion          △ needs authentication
  my-server       ⏸ pending approval

MCP permite a Claude Code trabajar con herramientas y datos externos. Si falla la conexión, no diagnostiques solo por el estado: comprueba también el método de conexión y los detalles del error. Este artículo recorre el inicio local, la comunicación y autenticación remotas, la configuración y la aprobación.

Lo esencial: (1) Lee el estado y los detalles con /mcp y claude mcp get <name>. (2) failed puede aparecer tanto en servidores locales como remotos. En stdio, revisa el comando y las variables de entorno; en HTTP, la URL, la red, la respuesta del servidor y la autenticación. (3) Si la causa no está clara, consulta los registros de conexión con claude --debug=mcp. Cambia solo lo que indique el error real y vuelve a conectar para comprobar el resultado.

1. Qué te está diciendo este error

Por ejemplo, puedes encontrar este error en un registro. El mensaje por sí solo no demuestra que el servidor no haya arrancado; revisa también las entradas anteriores.

MCP error -32000: Connection closed

MCP error -32000: Connection closed indica que la conexión se cerró. El SDK de TypeScript de MCP asigna -32000 a ConnectionClosed. Consulta los registros anteriores para averiguar qué la cerró, como la salida del servidor o una conexión interrumpida. El mensaje no permite saber si el proceso terminó antes de inicializarse o si la conexión cayó después. Consulta la gestión del cierre de conexiones en el SDK.

También puede haber fallos ajenos a tu configuración. Por ejemplo, la incidencia #20713 recoge el informe de un usuario sobre una desconexión durante la inicialización con Claude Code 2.1.19 en macOS. No confundas el diagnóstico de un usuario con una causa confirmada por Anthropic ni con un fallo actual que afecte a todos los entornos. Al informar de un problema, incluye sistema operativo, versión, método de conexión y registros sin secretos.

Los servidores MCP suelen utilizar dos tipos de conexión. (1) stdio (local): Claude Code inicia el comando del servidor como subproceso en tu equipo y se comunica por la entrada y salida estándar. (2) HTTP (remoto): se conecta a un servidor en la nube mediante una URL (el antiguo SSE está obsoleto). El significado de «no conecta» depende mucho del tipo.

En servidores locales (stdio), comprueba si falta un comando o una variable, si el servidor termina o si mezcla registros con stdout. En servidores remotos (HTTP), revisa la URL, los problemas de red, las respuestas 5xx, los tiempos de espera y la autenticación. La ubicación, sintaxis y ámbito de la configuración importan en ambos casos. No afirmes que los fallos son «casi siempre de autenticación» o «casi siempre de rutas» sin datos sobre su frecuencia.

Primero, anota el estado y los detalles del error e identifica si la conexión usa stdio o HTTP. Cambiar varios ajustes a la vez dificulta saber cuál ayudó. Usa la siguiente tabla como punto de partida e investiga una causa pertinente cada vez.

2. Lee primero el estado con /mcp

Ejecuta /mcp dentro de la sesión (o claude mcp list / claude mcp get <name> desde el shell) para ver el estado de cada servidor. Los estados principales y sus significados:

failed por sí solo no distingue un fallo de inicio local de un problema de comunicación remota. Lee el código HTTP o el cuerpo del error que aparezca en Issue: al ejecutar claude mcp get <name>, o en los detalles de /mcp. Una cabecera fija Authorization rechazada con 401/403 durante la conexión también produce failed. Además, cero herramientas no implica necesariamente un error si el servidor solo ofrece recursos o prompts. Comprueba primero si está diseñado para ofrecer herramientas. Consulta los detalles oficiales de los estados del servidor.

3. Causas principales del fallo y soluciones

Estas comprobaciones ayudan a investigar fallos de conexión y discrepancias de configuración. Empieza por las que correspondan a tu método de conexión.

Puedes compartir el .mcp.json del proyecto, pero no incluyas valores secretos directamente en los commits. Por ejemplo, referencia ${API_KEY} y define el valor necesario en cada entorno. Algunos nombres de variables protegidos, incluidas las credenciales del propio Claude Code, se resuelven como cadenas vacías en URL y cabeceras remotas; consulta las reglas oficiales de expansión. Las sesiones interactivas solicitan aprobación para los servidores del proyecto. En cambio, claude -p y el SDK normalmente los cargan sin esa pregunta. Consulta la documentación oficial del ámbito de proyecto para los ajustes de rechazo y otras condiciones. También están relacionados los fundamentos de MCP y A2A.

4. Comprobar el inicio de npx en Windows

Si Windows muestra spawn npx ENOENT, comprueba primero el ejecutable y PATH con where.exe npx. Revisa también si Node/npm funciona y si el paquete indicado puede arrancar. La documentación oficial de Node explica que los archivos .cmd no pueden ejecutarse directamente y muestra cómo iniciarlos mediante un shell o cmd.exe. Sin embargo, eso no significa que indicar npx directamente falle en todos los entornos de Claude Code.

{
  "command": "cmd.exe",
  "args": ["/c", "npx", "-y", "@scope/your-mcp-server"]
}

5. El flujo de diagnóstico

Cuando la causa no esté clara, trabaja de arriba abajo. El truco está en confirmar que el servidor funciona por sí solo antes de culpar a Claude Code.

Nota: añadir demasiados servidores MCP hace que las definiciones de herramientas consuman contexto (sobre todo con carga permanente). Claude Code pospone esas definiciones mediante la búsqueda de herramientas de forma predeterminada, lo que reduce el impacto; aun así, conviene desactivar los servidores que no uses. Sobrecargar el contexto puede incluso provocar Prompt is too long.

6. Lista de prevención

Hábitos para no atascarte con las conexiones MCP.

(1) Comprueba las rutas reales de ejecutables y scripts stdio. (2) Distingue las variables de stdio de las cabeceras de autenticación HTTP y evita guardar secretos en archivos compartidos. (3) En Windows, comprueba where.exe npx y Node/npm; prueba cmd.exe /c solo si el problema es el método de inicio. (4) Coloca .mcp.json en la raíz del proyecto y revisa la sintaxis JSON, las variables y la aprobación. (5) Envía los registros stdio a stderr, no a stdout. (6) Haz un cambio cada vez; después, vuelve a conectar y prueba la operación necesaria.

Resumen

Investiga los errores de conexión MCP de Claude Code combinando el estado, el método de conexión y los detalles del error. failed no se limita a los fallos de inicio local: también puede deberse a problemas de comunicación HTTP o al rechazo de cabeceras fijas de autenticación. needs authentication orienta hacia la autenticación y pending approval, hacia la aprobación de un servidor del proyecto.

Sigue estos pasos: lee el estado y Issue: → consulta los registros adecuados al método de conexión → prueba el funcionamiento independiente o la comunicación → vuelve a conectar y verifica la operación. Selecciona la categoría de depuración con claude --debug=mcp. Añade --debug-file ./claude-mcp-debug.log para guardar los registros. Elimina los secretos antes de compartirlos. Lecturas relacionadas: Qué es MCP, Monetizar servidores MCP, Errores habituales de Claude Code.

FAQ

P. /mcp muestra failed. ¿Por dónde empiezo?
R. Revisa el método de conexión e Issue:. En stdio, examina el comando, la ruta, las variables de entorno y stderr; en HTTP, la URL, la red, la respuesta del servidor y la autenticación. Una cabecera fija Authorization rechazada con 401/403 durante la conexión también produce failed: no asumas que es un problema de inicio local.

Q. Dice "needs authentication" y las herramientas no funcionan.
A. Esto es un servidor remoto (HTTP) que solicita autenticación (401/403). Abre /mcp y ejecuta la autenticación de ese servidor; continúa con la aprobación OAuth en el navegador. Una vez hecho, los tokens se almacenan de forma segura y se renuevan automáticamente. Ten en cuenta que algunos servicios (Microsoft 365, Gmail, Google Calendar) no admiten la autenticación local desde Claude Code y deben conectarse mediante Settings → Connectors en claude.ai en su lugar.

P. Mi servidor npx no conecta en Windows.
R. Comprueba where.exe npx y Node/npm e intenta iniciar el mismo paquete con los mismos argumentos. Si el problema es cómo se ejecuta el archivo .cmd, puedes usar cmd.exe /c npx .... WSL también necesita un entorno Linux funcional. Cambiar de sistema operativo no garantiza una solución.

P. Está connected, pero muestra 0 herramientas.
R. Comprueba si ese servidor está diseñado para ofrecer herramientas. Cero herramientas no implica necesariamente un error si solo ofrece recursos o prompts. Si debería ofrecerlas, revisa las capacidades expuestas, los permisos, los ajustes del servidor y los registros; después, vuelve a conectar. Envía los registros de diagnóstico de stdio a stderr, no al flujo stdout utilizado por el protocolo.

P. Configuré un servidor, pero no puedo utilizarlo.
R. Comprueba que el .mcp.json compartido esté en la raíz del proyecto; después, revisa la sintaxis, el ámbito y la aprobación. Una ${VAR} no definida y sin valor predeterminado genera una advertencia y permanece como texto literal al cargar la configuración, lo que puede provocar fallos de inicio o autenticación. Especifica también type en las configuraciones HTTP. Repetir la aprobación no resuelve por sí solo los ajustes de rechazo ni las políticas administradas.

Referencias de configuración y comandos: ajustes env, referencia de la CLI, referencia de conexiones MCP.