Configuración MCP de Claude Code: .mcp.json, ámbitos y solución de problemas

2026-09-09 Actualizado: 2026-09-14

Claude Code lee los servidores MCP de dos archivos: .mcp.json en la raíz del proyecto para los servidores compartidos con el equipo, y ~/.claude.json para tus propios servidores de ámbito local y de usuario. Los dos usan el mismo objeto mcpServers, donde cada entrada nombra un type de http, sse, ws o stdio, y un servidor que no aparece casi siempre se debe a un type equivocado, una variable de entorno sin expandir, o un inicio de sesión que nunca se completó.

El formato de .mcp.json

Un archivo de proyecto con un servidor remoto y uno local se ve así:

{
  "mcpServers": {
    "hosttracker": {
      "type": "http",
      "url": "https://mcp.host-tracker.com/mcp"
    },
    "local-tool": {
      "type": "stdio",
      "command": "/path/to/executable",
      "args": ["--flag", "value"],
      "env": { "KEY": "value" },
      "timeout": 600000
    }
  }
}

El campo type es obligatorio siempre que esté presente url. Una url sin type se reporta como un error de configuración (el mensaje te dice que añadas "type": "http", o sse o ws), lo que sustituyó a una queja más antigua y mucho menos útil sobre un command que faltaba. El valor streamable-http se acepta como alias de http. Un servidor remoto que necesita una credencial fija lleva un objeto headers; uno local lleva command, args y env. El timeout opcional es un límite por llamada a herramienta en milisegundos. Los servidores WebSocket solo se pueden declarar en un archivo o mediante claude mcp add-json; el indicador --transport no acepta ws.

El comando claude mcp add con --scope project escribe este archivo por ti, así que editarlo a mano solo hace falta para campos que el comando no expone o cuando prefieres revisar el cambio en una pull request.

Mantener los secretos fuera del archivo

Como .mcp.json está pensado para subirse al control de versiones, los tokens no deberían escribirse directamente en él. Claude Code expande variables de entorno en command, args, env, url y headers: ${VAR} toma el valor de la variable, y ${VAR:-default} recurre al valor por defecto cuando no está definida.

{
  "mcpServers": {
    "secure-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

Una variable referenciada que no está definida y no tiene un valor por defecto no impide que el servidor cargue; el texto literal ${API_KEY} se envía tal cual, y claude mcp list imprime un aviso. Ese aviso es lo primero que hay que buscar cuando un servidor conecta pero cada llamada se rechaza como no autorizada.

Para un servidor que admite OAuth no hay nada que ocultar en absoluto: deja la entrada solo con type y url, y cada usuario inicia sesión una vez desde /mcp. El token se guarda por usuario, fuera del repositorio, y se elimina de nuevo con claude mcp remove.

Aprobación, precedencia y servidores gestionados

La primera vez que Claude Code ve un servidor en el .mcp.json de un proyecto, una sesión interactiva pregunta si usarlo; las ejecuciones no interactivas (claude -p, el Agent SDK, las sesiones en la nube) lo cargan sin preguntar. La decisión se recuerda por proyecto; claude mcp reset-project-choices la olvida para que puedas volver a aprobar tras un cambio.

Cuando un mismo nombre se define en varios sitios, el orden es ámbito local, luego ámbito de proyecto, luego ámbito de usuario, luego los servidores que aportan los plugins, y por último los conectores de claude.ai. Se usa toda la entrada ganadora. Las organizaciones pueden imponer una lista fija de servidores mediante un archivo de configuración gestionado o el ajuste managedMcpServers (Claude Code 2.1.259 o posterior); esos van por delante de cualquier ámbito a nivel de usuario, y un archivo gestionado que reclama control exclusivo hace que claude mcp add se rechace con un mensaje que dice que hay una configuración empresarial activa. Las listas de permitidos y denegados (allowedMcpServers, deniedMcpServers) también pueden restringir qué URLs o comandos pueden añadir los usuarios, y un denegado siempre gana.

Leer la salida de estado

claude mcp list reporta cada servidor como conectado, necesita autenticación, no se pudo conectar, pendiente de aprobación, rechazado mediante disabledMcpjsonServers, o desactivado para este proyecto. Vale la pena conocer algunos avisos menos obvios que imprime: espacios en blanco ocultos al principio o al final de un valor (un token pegado que terminó con un salto de línea), el mismo nombre apuntando a endpoints distintos en dos ámbitos, y un puñado de nombres reservados que no se pueden usar para tus propios servidores. Los servidores WebSocket no aparecen en absoluto en la lista; compruébalos con claude mcp get <name> o /mcp.

Fallos habituales y cómo arreglarlos

Un servidor remoto muestra "needs authentication" o responde 401 o 403. Abre /mcp, selecciona el servidor y completa el inicio de sesión en el navegador, o ejecuta claude mcp login <name>. Si el servidor usa un token estático, revisa el valor de la cabecera y el aviso sobre variables sin expandir.
Un servidor local no consigue conectar al arrancar. Ejecuta su comando a mano en la misma terminal para ver el error real; las causas habituales son un entorno de ejecución que falta, un paquete que hay que instalar, o una variable de entorno necesaria. Los servidores que arrancan despacio chocan con el límite de arranque, que MCP_TIMEOUT sube en milisegundos, por ejemplo MCP_TIMEOUT=10000 claude.
El servidor conecta pero una herramienta devuelve un resultado truncado. La salida de las herramientas tiene un tope de 25.000 tokens por defecto, con un aviso a partir de 10.000; MAX_MCP_OUTPUT_TOKENS sube el tope.
Las herramientas parecen faltar en la conversación. Claude Code retrasa las definiciones de herramientas hasta que hacen falta para mantener el contexto reducido, así que al principio solo cargan los nombres y las instrucciones del servidor; el asistente las sigue encontrando cuando una petición coincide. Fija "alwaysLoad": true en la entrada de un servidor si quieres que sus definiciones completas estén presentes desde el primer turno.
Un servidor remoto se cae a mitad de sesión. Claude Code reintenta una conexión caída hasta cinco veces con retrasos crecientes y una primera conexión HTTP fallida hasta tres veces, pero no para errores de autenticación ni para servidores locales, así que un fallo de autenticación no se va a arreglar solo.

Probar la configuración contra un servicio en vivo

La forma más rápida de validar el .mcp.json de un proyecto es un servidor cuyas respuestas puedas comprobar de forma independiente. Con { "type": "http", "url": "https://mcp.host-tracker.com/mcp" } subido al repositorio y cada desarrollador con la sesión iniciada una vez desde /mcp, una petición como "ejecuta una comprobación HTTP sobre nuestra URL de staging desde Europa y Asia" tiene que volver con códigos de estado y tiempos de respuesta reales desde los puntos de control de HostTracker, lo que demuestra que el archivo se lee correctamente o acota el fallo al inicio de sesión. La guía complementaria, cómo añadir un servidor MCP a Claude Code, cubre la vía de línea de comandos y los ámbitos con más detalle.