La causa más frecuente del «el asistente no ve mis datos» no es un servidor roto.
Es un cliente que nunca se reinició después de cambiar la configuración. La
mayoría de los clientes MCP leen su configuración al arrancar y nunca más, así
que un archivo editado con la aplicación abierta es un archivo que la aplicación
no ha leído. Ciérrela del todo — en macOS, cerrar la ventana deja el proceso
vivo — y vuelva a abrirla. En Claude Code, ejecute /mcp en lugar de reiniciar
el terminal.
Si eso no lo arregla, la pregunta útil no es «qué cliente uso» sino «qué está pasando exactamente». Un servidor que no aparece, un servidor que conecta pero no expone ninguna herramienta, herramientas que no devuelven nada y herramientas que solo fallan cuando intentan cambiar algo son cuatro averías distintas con cuatro soluciones distintas, y la solución apenas depende de la aplicación que use. Cada detalle de esta página se contrastó con la documentación de los proveedores a 14 de agosto de 2026.
Antes de tocar nada, mire lo que el cliente ya sabe. Cada cliente tiene exactamente un sitio que responde a «¿conectó este servidor?», y adivinarlo desde la ventana de conversación es la forma habitual de pasar una hora con un problema que esa pantalla nombra en un segundo.
| Cliente | Dónde mirar | Qué aspecto tiene un servidor sano |
|---|---|---|
| Claude Code | claude mcp list o el panel /mcp |
✔ Connected |
| Claude Desktop | icono más del campo de chat → Connectors | el servidor aparece con sus herramientas |
| Cursor | panel Output (Cmd+Shift+U) → MCP Logs |
inicialización, sin errores de conexión |
| VS Code | MCP: List Servers en la Command Palette | el servidor arranca y el registro de Show Output está limpio |
| Zed | Settings → AI → MCP Servers | punto verde, mensaje emergente Server is active |
Claude Code es el más informativo de todos. claude mcp list imprime un estado
de salud junto a cada servidor — ✔ Connected, ! Needs authentication,
✘ Failed to connect, ⏸ Pending approval — y añade el detalle del fallo en esa
misma línea; claude mcp get <name> muestra lo mismo en una fila Issue:,
incluido el texto de error que devolvió el propio servidor.
Si la pantalla de estado no muestra su servidor, el cliente no está leyendo la entrada que usted escribió. Tres causas explican casi todos los casos.
El archivo no es JSON válido. Una coma de más o una llave que falta y el cliente ignora el archivo entero — no solo la entrada rota — normalmente sin decirlo. Pegue el archivo en cualquier validador de JSON antes de sospechar de otra cosa.
Editó un archivo distinto del que lee el cliente. Casi todos los clientes
tienen una configuración personal y otra de ámbito de proyecto, y editar la
equivocada produce exactamente este síntoma. Cursor lee ~/.cursor/mcp.json de
forma global y .cursor/mcp.json dentro de un proyecto; VS Code lee
.vscode/mcp.json en un espacio de trabajo y un mcp.json del perfil de
usuario, que se abre con MCP: Open User Configuration. Claude Code tiene tres
ámbitos — local y usuario en ~/.claude.json, proyecto en un .mcp.json en la
raíz del repositorio — y cuando un nombre está definido en más de uno, local gana
a proyecto y proyecto gana a usuario. La entrada entera viene del ámbito ganador;
los campos no se fusionan.
El nombre de la clave no es el de ese cliente. La clave de primer nivel de
VS Code es servers, la de Zed es context_servers, y el resto usa
mcpServers. Un bloque mcpServers pegado en VS Code no es un error que el
editor señale: es sencillamente una clave que no lee. Esto se detalla cliente por
cliente en
dónde está la configuración de MCP.
Hay un caso que parece un servidor ausente y no lo es: en Claude Code, un
servidor de ámbito de proyecto se queda en ⏸ Pending approval hasta que se
ejecuta claude de forma interactiva en esa carpeta y se aprueba, y las
aprobaciones subidas al repositorio se ignoran mientras no se marque el espacio
de trabajo como de confianza.
Cuando nada cambió en la configuración y el servidor dejó de conectar, lo
habitual es que la configuración siga guardando una ruta absoluta a un programa
que ya no está ahí. Actualizar una aplicación a otra carpeta, renombrarla o
sacarla de Aplicaciones rompen la ruta mientras el JSON sigue pareciendo
correcto, y nada en el error del cliente apunta al traslado. Compruebe el valor
de command contra la realidad antes que nada:
ls -l "/absolute/path/from/your/config"
El mismo tipo de fallo afecta a los servidores que se lanzan a través de un
gestor de versiones. Si command es node, npx, python o uv y el runtime
viene de nvm, pyenv o asdf, la ruta existe en su terminal y no existe para el
cliente, porque el cliente no arranca un shell de inicio de sesión. Sustituya el
nombre suelto por la ruta absoluta — which node la da — o apunte command
directamente al binario.
Un estado verde con la lista de herramientas vacía significa que el saludo
inicial funcionó y que tools/list no devolvió nada útil. Esto lo producen dos
cosas.
La primera es un servidor que de verdad declara un conjunto de herramientas vacío, algo que se puede confirmar fuera del cliente con el MCP Inspector, la interfaz de pruebas de referencia que se conecta directamente a un servidor stdio o Streamable HTTP y lista lo que publica. Si el Inspector ve herramientas y su cliente no, el fallo está en la configuración del cliente.
La segunda es un tope de herramientas. VS Code limita cada petición de chat a 128 herramientas activas y rechaza la petición cuando el total lo supera, un límite que una máquina cargada alcanza antes de lo que parece; el botón Configure Tools de la vista Chat es donde se apagan servidores para volver por debajo. Cursor deja desactivar servidores uno a uno desde el panel Customize de la barra lateral, y un servidor desactivado no se carga ni aparece en la conversación: conviene mirarlo primero, porque un interruptor que alguien cambió el mes pasado se ve igual que un servidor que falló.
Las herramientas aparecen listadas, el asistente las llama y los resultados vienen vacíos. El transporte está bien; aquí la pregunta es de datos, no de configuración. Compruebe que la biblioteca que lee el servidor es la que usted tiene en mente: la cuenta correcta, el dispositivo correcto y contenido que de verdad se ha sincronizado a esta máquina en lugar de vivir solo en otra. Después mire los argumentos de la herramienta en el registro del cliente: un asistente que adivinó un rango de fechas o un filtro puede producir un resultado vacío a partir de una biblioteca perfectamente sana.
Si las búsquedas salen bien pero cada intento de renombrar, etiquetar o actualizar algo falla, esto no es un problema de transporte. Los servidores suelen dividirse en herramientas que leen y herramientas que cambian datos, y la mitad que cambia lleva a menudo un requisito extra: una aplicación en ejecución, una sesión autenticada, un permiso que el cliente no ha recibido. Hay dos causas del lado del cliente que conviene descartar primero. Las herramientas que cambian datos se declaran como tales, así que el cliente pregunta antes de ejecutarlas, y una pregunta que se descartó se lee como un fallo en la transcripción. Y un servidor arrancado con una opción de solo lectura no publica esas herramientas en absoluto, lo cual es una decisión de configuración y no una avería.
Esta es un error del servidor y no suyo, pero conviene reconocerla porque el
mensaje confunde. Sobre stdio el protocolo exige que la salida estándar no lleve
nada más que mensajes JSON-RPC, así que un servidor que imprime un banner de
versión, una línea de «arrancando» o un registro con colores en stdout corrompe
el flujo, y el cliente falla con un error de análisis que cita los primeros
caracteres de lo que se imprimió:
Unexpected token 'S', "Starting s"... is not valid JSON. El arreglo le
corresponde al autor del servidor: las líneas de registro van a stderr, que el
anfitrión captura de todos modos.
El entorno es la otra trampa del arranque. Un servidor stdio hereda solo un
subconjunto limitado de variables de entorno, que además depende de la plataforma
— no el perfil de shell — y su directorio de trabajo puede quedar indefinido, en
la práctica / en macOS. Pase lo que el servidor necesite mediante la clave
env de su entrada de configuración, y mantenga todas las rutas absolutas.
command existe, como ruta absoluta.Empezar por arriba cuesta un minuto. Empezar por el paso siete es lo que convierte un problema de cinco segundos en una tarde entera.
Speak-Y incluye su servidor MCP dentro de la aplicación de macOS, así que varias
de las averías de arriba no pueden ocurrirle: no hay paquete de npm que instalar,
ni runtime que resolver a través de nvm, ni token que caduque. La que sí puede
ocurrir es la ruta obsoleta, y la aplicación la repara por su cuenta. Al arrancar
revisa las configuraciones de Claude Code, Claude Desktop y Cursor y reescribe el
valor de command allí donde apunta a una ubicación antigua de la aplicación,
solo en las entradas que son realmente suyas, identificadas por el binario de la
aplicación y el argumento --mcp, de modo que otro servidor que casualmente
comparta nombre se queda intacto. Si hay que hacerlo a mano,
Configuración → Integraciones muestra Reinstalar junto a cada cliente
detectado; después, reinicie el cliente o ejecute /mcp en Claude Code.
La separación entre leer y cambiar es el otro síntoma que conviene reconocer.
Buscar en las grabaciones y leer transcripciones, resúmenes y action items
funciona directamente contra la biblioteca de esta máquina y no necesita nada más
en ejecución. Las herramientas que organizan — etiquetas, títulos, nombres de los
participantes, retranscripción, publicación en un canal de equipo —
pasan por la aplicación en ejecución, así que con Speak-Y cerrado fallan mientras
la búsqueda sigue funcionando. Esa asimetría es un diagnóstico en sí misma: si
leer funciona y cambiar no, abra la aplicación en lugar de editar ninguna
configuración. Añadir --read-only a los argumentos del servidor retira por
completo de la vista del cliente las herramientas que cambian datos: es el
comportamiento previsto, no una avería. Los resultados vacíos de un servidor sano
suelen significar que la grabación sigue en otro dispositivo: el servidor lee
este disco y no va a buscar el resto.
Si lo que toca es instalar y no reparar, las guías por cliente sirven más que esta página: Claude Desktop y Claude Code paso a paso, y VS Code, Zed y Devin Desktop para los editores cuya forma de configuración se aparta de la del resto.
La mayoría de los clientes leen la configuración de MCP solo al arrancar, así que una configuración escrita mientras el cliente estaba abierto todavía no se ha cargado. Cierre la aplicación por completo y vuelva a abrirla — en macOS no basta con cerrar la ventana — y en Claude Code ejecute /mcp en lugar de reiniciar el terminal.
Cada cliente tiene un único sitio que responde a esto. Claude Code: claude mcp list, que imprime ✔ Connected, ! Needs authentication o ✘ Failed to connect junto a cada servidor. Claude Desktop: el icono más del campo de chat y luego Connectors. VS Code: MCP: List Servers desde la Command Palette. Cursor: el panel Output con MCP Logs seleccionado. Zed: Settings → AI → MCP Servers, donde un punto verde indica Server is active.
En ~/Library/Logs/Claude en macOS y en %APPDATA%\Claude\logs en Windows. Se siguen en directo con tail -n 20 -F ~/Library/Logs/Claude/mcp*.log. El archivo mcp.log guarda los eventos generales de conexión, y mcp-server-NAME.log lo que ese servidor concreto escribió en stderr.
El cliente lanza el proceso por su cuenta, no a través del shell de inicio de sesión. No hereda todo el PATH, sino un subconjunto limitado de variables de entorno que depende de la plataforma, y su directorio de trabajo puede quedar indefinido. Use una ruta absoluta en command, rutas absolutas en los argumentos y pase las variables necesarias de forma explícita mediante la clave env.
Casi siempre la ruta absoluta de la configuración de MCP, que apunta a donde estaba la aplicación antes. Reinstalarla en otra carpeta, renombrarla o sacarla de Aplicaciones rompen la ruta mientras la configuración sigue pareciendo correcta. Vuelva a lanzar la instalación de un clic del cliente para que la ruta se reescriba.