Servidor MCP configurado pero no aparece en el cliente: cómo diagnosticarlo paso a paso

Imagen ilustrativa: Unsplash

Añadiste el servidor MCP al archivo de configuración, reiniciaste el cliente y no aparece. O peor: aparece conectado pero con cero herramientas. Antes de tocar una línea más, contesta una pregunta: ¿el cliente ni siquiera intenta arrancarlo, lo arranca y se cae, o lo arranca bien y no devuelve herramientas? Son tres fallos distintos con tres causas distintas, y el 90 por ciento del tiempo que se pierde con MCP se pierde por confundirlos. En Claude Code lo distingues con un comando, claude mcp list, y en Claude Desktop mirando un archivo de log concreto que casi nadie abre.

Los tres estados de un servidor que no funciona

No aparece en absoluto. El cliente no leyó tu configuración. El archivo está en la ruta equivocada, el JSON está roto, o la clave raíz no es la que ese cliente espera. Es el caso más común y el más rápido de descartar.

Aparece pero falla al conectar. El cliente encontró la entrada e intentó lanzar el proceso. El fallo está en el comando: ruta relativa, ejecutable que no está en el PATH que hereda el cliente, o permisos.

Conecta pero lista cero herramientas. El proceso arrancó y respondió, pero no registró nada. La documentación de Claude Code es explícita sobre la causa habitual: al servidor le falta una variable de entorno obligatoria, típicamente una clave de API, y arranca en modo degradado sin quejarse.

Dónde vive la configuración y dónde están los logs

La mitad de los problemas se resuelven abriendo el archivo correcto. Esta es la tabla que conviene tener a mano, porque cada cliente usa una ruta, una clave raíz y un sistema de logs diferente:

Cliente	Archivo de configuración	Clave raíz	Dónde mirar el error
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json en macOS, %APPDATA%\Claude\claude_desktop_config.json en Windows	mcpServers	~/Library/Logs/Claude/mcp-server-NOMBRE.log, que recoge el stderr del servidor
Claude Code	.mcp.json en la raíz del proyecto, o ~/.claude.json según el ámbito	mcpServers	claude mcp list, el comando /mcp, y claude --debug=mcp con el log en ~/.claude/debug/
VS Code	.vscode/mcp.json en el proyecto, o el de usuario vía el comando MCP: Open User Configuration	servers	Paleta de comandos, MCP: List Servers, seleccionar el servidor y Show Output
Cursor	~/.cursor/mcp.json global, o .cursor/mcp.json por proyecto	mcpServers	Panel Output, desplegable MCP Logs

Fíjate en la tercera columna. VS Code usa servers y el resto usa mcpServers. Copiar una configuración de un tutorial de VS Code a Claude Code, o al revés, produce exactamente el síntoma de no aparece nada, sin ningún mensaje de error. La documentación de Claude Code lo lista como causa conocida, junto con otro caso que veo mucho: poner el archivo dentro de .claude/ en lugar de en la raíz del proyecto. Ahí no lo lee.

Las cinco causas que explican casi todos los casos

1. Ruta relativa en el comando. La documentación oficial es tajante: el directorio de trabajo de un servidor lanzado por el cliente puede estar sin definir, y en macOS puede ser la raíz del sistema. Usa rutas absolutas siempre. Los ejecutables que ya están en el PATH, como npx o uvx, funcionan tal cual.
2. El PATH que no se hereda. Un servidor lanzado por stdio hereda solo un subconjunto limitado de variables de entorno, y ese subconjunto depende de la plataforma. Si tu cliente se abrió desde el Dock o el menú de inicio, no tiene el PATH de tu terminal. En Windows esto se manifiesta con un ENOENT que menciona ${APPDATA}, y la solución documentada es declarar APPDATA dentro del bloque env de ese servidor.
3. El servidor escribe en stdout. Esto es normativo en la especificación: el servidor no debe escribir en stdout nada que no sea un mensaje MCP válido, y los mensajes van delimitados por saltos de línea sin saltos internos. Un solo console.log de depuración, o un JSON impreso con formato bonito, rompe el protocolo. El síntoma típico en el SDK de TypeScript es un SyntaxError: Unexpected token ... is not valid JSON. Para registrar, usa stderr: la especificación lo permite explícitamente y el cliente puede capturarlo.
4. Falta una variable de entorno y el servidor arranca vacío. Si el servidor aparece conectado con cero herramientas, casi siempre le falta una clave de API. Declárala en el bloque env de la entrada, que no depende del entorno desde el que se lanzó el cliente.
5. El cliente no se reinició de verdad. En Claude Desktop hay que salir por completo de la aplicación: cerrar la ventana no basta. Claude Code lee .mcp.json al inicio de la sesión, así que hay que salir y volver a entrar.

La causa nueva de 2026: ya no hay handshake

Esta es la parte que no vas a encontrar en los tutoriales escritos hace un año, y que explica una oleada de fallos recientes. La revisión 2026-07-28 de la especificación eliminó el handshake de inicialización. Desaparecen initialize y notifications/initialized, y desaparecen también las sesiones a nivel de protocolo. MCP pasa a ser sin estado: cada petición lleva su versión de protocolo y sus capacidades en el campo _meta, y el servidor acepta o rechaza cada petición por separado.

La consecuencia práctica es que ya no hay negociación. Un cliente actualizado contra un servidor antiguo falla, y un cliente antiguo contra un servidor nuevo también, porque el cliente antiguo no tiene mecanismo de avance. Cuando el servidor no soporta la versión pedida, debe devolver el error -32022 con la lista de versiones que sí acepta:

{"jsonrpc":"2.0","id":1,"error":{
  "code":-32022,
  "message":"Unsupported protocol version",
  "data":{"supported":["2026-07-28","2025-11-25"],"requested":"1900-01-01"}}}

Otros dos códigos nuevos que conviene reconocer: -32021 significa que el servidor necesita una capacidad de cliente que no declaraste, y -32020 es un desajuste de cabecera. Y un aviso: -32602 es ambiguo, porque es el mismo código que devuelven muchas entradas malformadas.

Si mantienes servidores propios, el cambio también deprecó Roots, Sampling y Logging. La migración sugerida para el logging es directa: escribe a stderr en stdio, o usa OpenTelemetry.

Aislar el problema con MCP Inspector

La regla es no depurar dentro del cliente. Saca el servidor del cliente y pruébalo solo. La herramienta oficial es MCP Inspector, requiere Node 22.19.0 o superior, y trae tres interfaces en el mismo binario.

1. Lanza el servidor contra el Inspector en modo CLI y pide la lista de herramientas: npx @modelcontextprotocol/inspector --cli node ruta/al/server.js --method tools/list.
2. Si devuelve herramientas, el servidor está bien y el problema es de configuración del cliente. Vuelve a la tabla de arriba.
3. Si no devuelve nada, mira el código de salida. Es el diagnóstico más rápido que existe: 3 significa que el servidor pide autenticación, 4 que es inalcanzable por DNS, conexión rechazada o timeout, y 5 que la herramienta devolvió error o no existe.
4. Si sospechas de incompatibilidad de versión, fuerza el modo moderno con el ajuste protocolEra en modern. Por defecto el Inspector usa legacy, a propósito, para no contaminar la transcripción que fuiste a leer.
5. Para un servidor remoto: npx @modelcontextprotocol/inspector --server-url https://tu.servidor/mcp --transport http, y revisa la pestaña Network, donde resalta las cabeceras del protocolo.

Timeouts que te hacen creer que el servidor está roto

Un servidor que tarda en arrancar parece un servidor caído. En Claude Code, la variable MCP_TIMEOUT controla el tiempo de arranque en milisegundos, y la documentación menciona un valor por defecto de 30 segundos para servidores locales. Si tu servidor descarga dependencias en el primer arranque, súbelo: MCP_TIMEOUT=60000 claude. En PowerShell, $env:MCP_TIMEOUT = "60000" antes de lanzar.

Hay un detalle que despista mucho: un servidor HTTP remoto puede mostrarse como cached, con la lista de herramientas cargada de una sesión anterior en lugar de una conexión real. Eso puede enmascarar que el servidor ya no responde. Se desactiva con MCP_DISCOVERY_CACHE=0.

Y si trabajas en VS Code con muchos servidores a la vez, hay un límite duro documentado: un máximo de 128 herramientas por petición de chat. El mensaje es literal, Cannot have more than 128 tools per request, y se resuelve desactivando servidores enteros en el selector de herramientas.

Veredicto crítico

MCP resolvió un problema real: antes de él, cada integración entre un modelo y una herramienta era código a medida. Hoy escribes un servidor y lo usan cuatro clientes distintos. Eso vale mucho y explica la adopción.

Dicho eso, el ecosistema tiene un problema de superficie de configuración que no se está tomando en serio. Cuatro clientes, cuatro rutas, dos claves raíz distintas para el mismo objeto JSON y cuatro sistemas de logs sin nada en común. Que servers y mcpServers signifiquen lo mismo en herramientas que compiten por los mismos usuarios es una decisión que solo produce horas perdidas. Y que un archivo mal formado se salte en silencio, cargando el resto, es amable con el usuario pero pésimo para depurar.

El cambio a un protocolo sin estado me parece correcto de fondo, porque simplifica los servidores y elimina una máquina de estados entera. Pero rompe la compatibilidad en ambas direcciones sin un puente, y eso durante los próximos meses va a generar muchos informes de fallo que en realidad son desajustes de versión. Si mantienes un servidor público, lo más útil que puedes hacer ahora mismo es declarar en el README qué revisión de la especificación implementas.

Cuándo conviene un servidor MCP propio: cuando la integración la van a usar varios clientes o varias personas del equipo. Cuándo no: para una automatización puntual de un solo uso, donde un script normal te cuesta diez minutos y no te obliga a mantener compatibilidad de protocolo.

Sigue leyendo

• Error 429 en la API de Gemini, si el servidor arranca pero la API que hay detrás te está limitando.
• Firebase App Check bloquea tus peticiones, otro caso donde el error que llega al cliente no dice la verdad.
• Google Play rechaza tu app Flutter por seguridad de los datos, para cuando el bloqueo no es técnico sino de política.
• El resto está en el índice de guías prácticas.

Fuentes

Especificación MCP, revisión 2026-07-28, transportes y stdio: modelcontextprotocol.io. Registro de cambios de la revisión, con la eliminación del handshake: changelog. Versionado y códigos de error de protocolo: versioning. Guía oficial de depuración y rutas de logs: docs/tools/debugging. MCP Inspector y sus códigos de salida: docs/tools/inspector. Configuración y diagnóstico de MCP en Claude Code: code.claude.com. Servidores MCP en VS Code y el límite de herramientas: code.visualstudio.com. Configuración de MCP en Cursor: cursor.com/docs/mcp.