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. Cuando falla la conexión, el registro puede mostrar una línea como MCP error -32000: Connection closed. La causa se acota combinando tres cosas: el estado, el método de conexión y los detalles del error. Este artículo recorre, por este orden, el inicio local, la comunicación y autenticación remotas, y 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. Corrige solo lo que corresponda al error real y vuelve a conectar para comprobar el resultado.

1. Qué te está diciendo este error

Cuando se cierra la conexión, el registro muestra esta línea.

MCP error -32000: Connection closed

MCP error -32000: Connection closed indica que se cerró la conexión MCP. El SDK de TypeScript de MCP asigna -32000 a ConnectionClosed y muestra este mensaje cuando la conexión se cierra (véase la gestión del cierre de conexiones en el SDK). Esta línea solo comunica el resultado, que la conexión se cerró; el motivo está en las entradas anteriores del registro. Ahí es donde se distingue si el proceso del servidor terminó antes de inicializarse o si la comunicación se cortó después de conectar.

La conexión también puede cerrarse aunque la configuración sea correcta. La incidencia #20713 es el informe de un usuario al que se le cerró la conexión durante la inicialización con Claude Code 2.1.19 en macOS. La causa que apunta («condición de carrera») es una hipótesis del autor, y la incidencia se cerró como not planned en abril de 2026. Si informas tú 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. Los errores de ubicación, sintaxis y ámbito del archivo de configuración pueden darse en ambos tipos.

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 aparece tanto si falla el inicio local como si falla la comunicación remota. La pista está en los detalles: claude mcp list los añade al final de la línea ✘ Failed to connect, y claude mcp get <name> y la vista de detalle de /mcp los muestran en la línea Issue:, con el estado HTTP o el código de error y el texto de error que devolvió el servidor. Una cabecera fija Authorization rechazada con 401/403 durante la conexión también produce failed.

Si un servidor remoto se desconecta a mitad de sesión, Claude Code intenta reconectarlo automáticamente y, mientras tanto, /mcp lo muestra como pending (con un significado distinto al de pendiente de aprobación). Si fallan los cinco intentos y pasa a failed, aparece el aviso MCP server "<name>" disconnected · open /mcp to reconnect (si hace falta volver a autenticarse, pasa a needs authentication). Los servidores stdio no se reconectan automáticamente: vuelve a conectarlos a mano desde /mcp. Además, /mcp marca los servidores que declaran la capacidad de herramientas pero no exponen ninguna. Un servidor que solo ofrece recursos o prompts funciona correctamente aunque tenga cero herramientas. Consulta los detalles oficiales de los estados del servidor.

3. Causas principales del fallo y soluciones

Estos son los puntos que revisar ante fallos de conexión y discrepancias de configuración. Empieza por los que correspondan a tu método de conexión y revísalos por orden.

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 (reglas oficiales de expansión). Las sesiones interactivas solicitan aprobación para los servidores del proyecto, pero claude -p y el SDK los cargan sin esa pregunta. Si aun así no quieres que se cargue un servidor, añádelo a disabledMcpjsonServers (documentación oficial del ámbito de proyecto). Relacionado: 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. Después, prueba si Node/npm funciona y si el paquete indicado arranca por sí solo. Según la documentación oficial de Node, en Windows los archivos .cmd no pueden ejecutarse por sí solos y deben iniciarse a través de un shell o de cmd.exe.

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

5. El flujo de diagnóstico

Cuando la causa no esté clara, avanza de arriba abajo. El truco está en comprobar que el servidor funciona por sí solo antes de sospechar de Claude Code.

Nota: de forma predeterminada, Claude Code carga las definiciones cuando se necesitan mediante la búsqueda de herramientas, así que añadir servidores apenas afecta al contexto. Sin embargo, en los servidores con alwaysLoad o en configuraciones con la búsqueda de herramientas desactivada, las definiciones se cargan desde el principio, así que lo más seguro es desactivar con /mcp disable <name> los servidores que no uses. Sobrecargar el contexto puede provocar Prompt is too long.

6. Lista de prevención

Hábitos para no atascarte con las conexiones MCP.

(1) Escribe las rutas reales de los 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 revisión de 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 prueba 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.

Si en la aplicación Codex ves el historial pero falla el envío, no es un problema de MCP, sino del estado de la conversación. Lo tratamos en Codex «thread not found»: pasos de diagnóstico y un caso de recuperación.

FAQ

P. /mcp muestra failed. ¿Por dónde empiezo?
R. Mira el método de conexión e Issue:. En stdio, los candidatos son 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, y el estado HTTP aparece en Issue:.

P. Dice «needs authentication» y las herramientas no funcionan.
R. La solución depende del método de autenticación. Si el servidor usa OAuth, autentícate en /mcp. Con un headersHelper propio, este estado aparece cuando una llamada a una herramienta devuelve 401/403 y el reintento con credenciales renovadas también falla. Si el helper proporciona una cabecera Authorization, Claude Code no cambia a OAuth: corrige el origen y el valor de las credenciales y vuelve a conectar. Los conectores proporcionados por Anthropic, como Microsoft 365, Gmail y Google Calendar, no admiten OAuth local desde Claude Code. Si los añades con claude mcp add o en .mcp.json e inicias sesión desde /mcp, aparece is Anthropic-hosted and doesn't support local OAuth: quita ese registro y conéctalos en la configuración de conectores de claude.ai. Consulta la documentación oficial sobre autenticación propia.

P. Mi servidor npx no conecta en Windows.
R. Mira 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 iniciarlo con cmd.exe /c npx .... Si lo ejecutas en WSL, prepara Node y los paquetes en el lado Linux.

P. Está connected, pero muestra 0 herramientas.
R. Mira primero si ese servidor está diseñado para ofrecer herramientas. Si solo ofrece recursos o prompts, cero herramientas es lo normal. Si declara la capacidad de herramientas pero muestra 0, /mcp marca ese servidor: revisa las capacidades expuestas, los permisos, los ajustes del servidor y los registros, y 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 se carga como texto literal, lo que provoca fallos de inicio o autenticación. Indica también type en las configuraciones HTTP. Si claude mcp get <name> devuelve ✘ Rejected, el servidor está en disabledMcpjsonServers de algún archivo de configuración: además de repetir la aprobación, quita esa entrada.

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