Tabla de contenidos
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 approvalMCP le da a Claude Code "manos": herramientas externas (operaciones de archivos, GitHub, bases de datos, varias APIs), pero sus conexiones se atascan más a menudo de lo que cabría esperar. Las causas se dividen en tres familias: "fallo al lanzar el subproceso local", "autenticación remota" y "errores en el archivo de configuración", y el estado de /mcp te dice cuál es. Este artículo expone cómo leer el estado, las soluciones causa por causa, la principal trampa de Windows y el flujo de diagnóstico, todo basado en información oficial.
Puntos clave de entrada. (1) Mira primero el estado con /mcp (y claude mcp list): failed (fallo al lanzar), needs authentication (autenticación) y pending approval (en espera de aprobación) requieren soluciones completamente distintas. (2) Para local (stdio) los culpables habituales son las rutas y las variables de entorno, además del problema de npx en Windows. (3) Para remoto (HTTP) el culpable habitual es OAuth. (4) Cuando te atasques, ejecuta claude --debug mcp para ver la salida de error del servidor (stderr). Los comportamientos y valores por defecto cambian según la versión, así que confírmalos con la documentación oficial más reciente.
El estado te indica la solución
— failed / needs auth / pending tienen cada uno una cura distinta
✗ failed = un problema de lanzamiento local, △ needs auth = autenticación remota, ⏸ pending = en espera de aprobación.
No metas en el mismo saco todos los "no se conecta": clasifica primero por el estado; es la ruta más corta.
1. Qué te está diciendo este error
Los servidores MCP vienen en dos grandes tipos de conexión. (1) stdio (local): Claude Code lanza el comando del servidor como un subproceso en tu máquina y se comunica por la E/S estándar. (2) HTTP (remoto): se conecta a un servidor en la nube mediante una URL (el antiguo SSE está obsoleto). Lo que significa "no se conecta" depende en gran medida del tipo.
Un fallo local (stdio) es casi siempre "el propio comando no se pudo lanzar": ruta incorrecta, npx que no se resuelve (especialmente en Windows) o el servidor que se cae al instante porque falta una variable de entorno necesaria. Un fallo remoto (HTTP) suele ser "OAuth no se ha completado": el servidor devuelve 401/403 y muestra needs authentication. Y cuando no es ninguno de los dos, pero la configuración no surte efecto, sospecha de la ubicación del archivo de configuración, un error tipográfico en el JSON o la aprobación del proyecto.
Así que el primer movimiento es "abrir /mcp, leer el estado e identificar cuál de las tres familias es." Tratar cada error como un genérico "no se conecta" y andar a tientas es el camino largo. La siguiente sección cubre cómo leer el estado.
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:
| Estado | Significado | Dónde mirar primero |
|---|---|---|
| ✓ connected | Conectado. El número de herramientas aparece al lado | Si el número de herramientas es 0: "conectado pero sin herramientas" → reconectar / depurar |
| ✗ failed | Falló al lanzarse, o agotó los reintentos | Lanzamiento local = comando, ruta, npx, variables de entorno (§3, §4) |
| △ needs authentication | El remoto devolvió 401/403. OAuth sin completar | Ejecuta la autenticación desde /mcp (aprueba en el navegador) |
| ⏸ pending approval | En espera de aprobación de un servidor de proyecto en .mcp.json | Apruébalo en /mcp. Si lo rechazaste por error: claude mcp reset-project-choices |
| ✗ rejected | Un servidor de proyecto que rechazaste anteriormente | Lo mismo (reset-project-choices para volver a aprobar) |
La idea: "failed = un problema de lanzamiento, needs authentication = autenticación, pending = aprobación": el estado determina de forma única tu siguiente paso. Un caso que se pasa por alto a menudo es "conectado pero 0 herramientas": el servidor arrancó pero no devuelve una lista de herramientas; pasa a reconectar o revisa los registros con claude --debug mcp.
3. Causas principales del fallo y soluciones
Aquí tienes las causas representativas de failed (fallo al lanzar el servidor local) y los problemas de configuración, emparejadas con sus soluciones.
Principales causantes de failed / problemas de configuración
spawn ... ENOENT.env por servidor (en .mcp.json o --env). El env de settings.json NO llega a MCP.MCP_TIMEOUT (ms) al lanzar, p. ej. MCP_TIMEOUT=10000 claude..mcp.json de proyecto va en la raíz del repositorio (no bajo .claude/, ni en settings.json). Un ${VAR} sin definir hace que falle el análisis de la configuración.needs authentication. OAuth desde /mcp. Nota: una cabecera de autenticación estática rechazada se reporta como failed.
Para local, comprueba en orden: 1) ruta → 2) variables de entorno → 4) ubicación de la configuración.
Para remoto, 6) autenticación es prácticamente todo. La trampa de Windows de la siguiente sección también es muy común.
Un .mcp.json de proyecto puede compartirse vía git y pide aprobación la primera vez. Si descartas ese aviso por accidente, el servidor queda deshabilitado (pending/rejected). Ejecuta claude mcp reset-project-choices para rehacer la aprobación. Combina esto con los fundamentos de MCP y la comunicación entre agentes A2A para tener la imagen completa de la conectividad.
4. Cuando falla en Windows (la trampa más frecuente)
En Windows nativo, que los servidores MCP basados en npx no se conecten con spawn npx ENOENT / Failed to connect es extremadamente común. La causa: el npx de Windows es en realidad un shim por lotes (npx.cmd), y el spawn de procesos de Node no puede resolver directamente un .cmd.
Solución: envuélvelo en cmd /c
Haz que command sea cmd en lugar de npx directamente, y pasa /c npx ... como args:
{
"command": "cmd",
"args": ["/c", "npx", "-y", "@scope/your-mcp-server"]
}O ejecútalo bajo WSL, que es fiable. Si where npx muestra una ruta y aún así falla, sospecha primero de este problema del .cmd. Algunas apariciones específicas de cierta versión pueden estar corregidas en versiones posteriores, así que prueba también a actualizar a la última versión.
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.
Aíslalo de arriba abajo
/mcp y claude mcp list / get para comprobar el estado (failed vs auth vs pending).claude --debug mcp para leer el stderr (salida de error) del servidor. La razón del fallo suele estar justo aquí.npx ... en el mismo shell?). Si no, es un problema previo a Claude Code.npx @modelcontextprotocol/inspector): inspecciona su lista de herramientas e invócalas desde una interfaz.mcp*.log. /doctor también realiza comprobaciones.
La regla: confirma primero "¿funciona el servidor por sí solo?".
Una vez resuelto eso, el resto se reduce a configuración (ruta, env, ubicación) o autenticación.
Nota: añadir demasiados servidores MCP hace que las definiciones de herramientas consuman el contexto (sobre todo con configuraciones de carga permanente). Claude Code aplaza las definiciones de herramientas mediante búsqueda de herramientas por defecto, así que el impacto es pequeño, pero aun así es prudente deshabilitar 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) Especifica los scripts locales con rutas absolutas. (2) Pon las claves del servidor en el env por servidor (no en settings.json). (3) En Windows, envuelve con cmd /c npx ... (o usa WSL). (4) Mantén .mcp.json en la raíz del repositorio; vigila la sintaxis del JSON y los ${VAR} sin definir. (5) Los servidores no deben registrar en stdout (usa stderr). (6) Tras cambiar la configuración, recarga (reinicia Desktop por completo; vuelve a aprobar los servidores de proyecto). (7) Cuando te atasques, aísla con claude --debug mcp y un lanzamiento del servidor por sí solo, y actualiza a la última versión si hace falta.
Resumen
Para los errores de conexión del servidor MCP de Claude Code, la ruta más corta es clasificar por el estado de /mcp en tres familias. ✗ failed es un problema de lanzamiento local (ruta, variables de entorno, timeout, ubicación de la configuración; y en Windows, envuelve npx con cmd /c), △ needs authentication es OAuth remoto (autentícate desde /mcp), y ⏸ pending approval es un servidor de proyecto a la espera de aprobación (apruébalo en /mcp; un rechazo equivocado se corrige con claude mcp reset-project-choices).
Diagnostica en orden: (1) estado con /mcp -> (2) stderr con claude --debug mcp -> (3) lanzamiento por sí solo -> (4) MCP Inspector -> (5) reinicio completo de Desktop. Confirma que el servidor funciona por sí solo antes de culpar a Claude Code, y el resto se reduce a configuración o autenticación. Solo tres hábitos -variables de entorno en el env por servidor, .mcp.json en la raíz del repositorio, registros a stderr- reducen drásticamente los incidentes. Relacionados: Qué es MCP, Monetizar servidores MCP, Recopilación de errores de Claude Code.
FAQ
Q. /mcp muestra "failed". ¿Por dónde empiezo?
A. failed es en su mayoría un fallo al lanzar un servidor local (stdio). Comprueba en orden: (1) la ruta del comando/script (usa rutas absolutas), (2) las variables de entorno necesarias (ponlas en el env por servidor), y (3) en Windows, envuelve con cmd /c npx .... Si la causa sigue sin estar clara, lee el stderr del servidor con claude --debug mcp, y primero prueba si el servidor se lanza por sí solo en el mismo shell.
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.
Q. En Windows mi servidor npx simplemente no se conecta.
A. El npx de Windows es en realidad un shim por lotes (npx.cmd), que a menudo falla al lanzarse con spawn npx ENOENT. Cambia command a cmd y args a ["/c","npx","-y","nombre-del-paquete"] para envolverlo. Ejecutarlo bajo WSL también es fiable. Si where npx muestra una ruta y aún así falla, es casi seguro este problema del .cmd. Puede estar corregido en versiones más nuevas, así que prueba también a actualizar.
Q. Está "connected" pero muestra 0 herramientas.
A. El servidor se lanzó correctamente pero no devuelve una lista de herramientas. Una causa común es un servidor stdio que escribe registros en stdout y corrompe el protocolo: envía siempre los registros a stderr. Primero reconecta desde /mcp; si eso no lo soluciona, revisa la salida del servidor con claude --debug mcp.
Q. Configuré un servidor pero no aparece en /mcp.
A. La ubicación del archivo de configuración es el problema probable. Un servidor de proyecto compartido va en .mcp.json en la raíz del repositorio (no se lee bajo .claude/ ni dentro de settings.json). Un ${VAR} sin definir también hace que falle el análisis de la configuración. Los servidores de proyecto necesitan una aprobación inicial; si descartas el aviso, queda en pending: rehazlo con claude mcp reset-project-choices.
