Ubicación del archivo de configuración MCP de Claude Code y sus ajustes explicados

Ejecutas claude mcp add, el servidor se conecta y una semana después un compañero te pregunta dónde acabó ese ajuste. Claude Code no guarda la configuración MCP en un único archivo ordenado. La reparte entre ~/.claude.json, un .mcp.json a nivel de proyecto, varios archivos settings.json y, en entornos de empresa, un archivo de política gestionada. Si editas el equivocado, no pasa nada. Si editas el correcto sin conocer el orden de precedencia, otra definición gana en silencio.

Este artículo recorre cada ubicación en macOS, Windows y Linux, muestra qué definición prevalece cuando dos archivos nombran el mismo servidor y enumera los comandos, las variables de entorno y los ajustes de timeout que más importan en el día a día. Cada ruta y cada flag de abajo se han comprobado con la documentación actual de Claude Code, así que puedes copiarlos tal cual.

Dónde están realmente los archivos

Claude Code tiene tres alcances para los servidores que añades tú mismo, más una capa de organización que se superpone a ellos. El alcance decide dos cosas: qué proyectos cargan el servidor y si la definición viaja con el repositorio.

Tres alcances, tres ubicaciones

El alcance local es el predeterminado. Un servidor añadido sin --scope solo se carga en el proyecto desde el que ejecutaste el comando y sigue siendo privado para ti. Claude Code lo escribe en ~/.claude.json, bajo la ruta de ese proyecto:

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

Copiar prompt

El alcance de proyecto escribe un archivo .mcp.json en la raíz del repositorio. Está pensado para subirse al control de versiones, así que todo el equipo obtiene las mismas herramientas. El alcance de usuario guarda la definición en el mismo archivo ~/.claude.json, fuera de cualquier ruta de proyecto, de modo que la ven todos los proyectos que abras.

💡 Regla rápida: un servidor privado o experimental va en el alcance local. Una herramienta compartida del equipo va en el alcance de proyecto. Una herramienta personal que quieres en todos los repositorios va en el alcance de usuario.

Rutas en Windows, macOS y Linux

En Windows, ~ significa %USERPROFILE%, así que el archivo de nivel de usuario está en %USERPROFILE%\.claude.json. El archivo .mcp.json es relativo a la raíz de tu proyecto en todos los sistemas. Solo el archivo gestionado cambia según el sistema operativo, porque está en un directorio común a todo el sistema que controla un administrador.

Si quieres que los archivos del directorio personal estén en otro lugar, define CLAUDE_CONFIG_DIR. Claude Code guardará entonces tus ajustes, el historial de sesiones y los plugins allí, en lugar de en ~/.claude.

La trampa del nombre "local"

La palabra "local" significa dos cosas distintas en Claude Code. El alcance local de MCP vive en ~/.claude.json dentro de tu directorio personal. Los ajustes locales generales viven en .claude/settings.local.json dentro del proyecto. Buscar settings.local.json para un servidor MCP que añadiste con el alcance predeterminado no encuentra nada, y ese único malentendido explica una gran parte de las preguntas de "¿dónde se fue mi servidor?".

💡 Las definiciones de servidores van en .mcp.json o ~/.claude.json, y los comandos claude mcp las escriben por ti. Los archivos settings.json guardan las aprobaciones, las listas de permitidos y las listas de bloqueados, de las que se habla más abajo.

Dentro del archivo .mcp.json

Cuando añades un servidor con --scope project, Claude Code crea o actualiza este archivo automáticamente. También puedes escribirlo a mano y subirlo al repositorio. Tiene un campo contenedor, mcpServers, y una entrada por servidor.

Un ejemplo funcional

{
  "mcpServers": {
    "docs-search": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SERVICE_TOKEN}"
      }
    },
    "local-files": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@example/files-server"],
      "env": {
        "ROOT_DIR": "${PROJECT_ROOT:-.}"
      },
      "timeout": 600000
    }
  }
}

Copiar prompt

El campo type acepta http, sse, stdio y ws. El nombre streamable-http funciona como alias de http, lo que significa que un fragmento copiado de la documentación de un servidor normalmente se carga sin editarlo. Una entrada stdio necesita command y, opcionalmente, args y env. Una entrada remota necesita url y, opcionalmente, headers.

Un detalle hace tropezar a quien pega configuración de otro cliente, como Claude Desktop. El mismo contenedor mcpServers funciona dentro de .mcp.json, pero claude mcp add-json espera solo el objeto dentro del contenedor, no el contenedor en sí.

Variables de entorno en lugar de secretos

Como .mcp.json se sube al repositorio, los tokens nunca deben ir ahí. Claude Code expande dos formas de referencia a variables:

• ${VAR} se expande al valor de VAR.
• ${VAR:-default} se expande a VAR cuando está definida, y a default en caso contrario.

La expansión funciona en los valores command, args, env, url y headers. Si una variable no está definida y no tiene valor por defecto, el archivo se carga igualmente. Claude Code muestra una advertencia de variable ausente para ese servidor en claude mcp list y usa tal cual el texto literal ${VAR}, por eso un servidor puede fallar con una cadena literal desconcertante en su encabezado.

Además hay una regla de seguridad. En los url y headers de un servidor remoto, las variables que contienen credenciales, como ANTHROPIC_AUTH_TOKEN y NPM_TOKEN, se leen como vacías. Así se evita que un repositorio clonado envíe tus credenciales de Claude Code o de la nube a un servidor que nombre.

💡 Exporta el token real en el perfil de tu shell o en tu gestor de secretos, y sube solo la referencia ${SERVICE_TOKEN}.

Añadir servidores desde la terminal

Rara vez necesitas tocar el JSON tú mismo. La familia claude mcp add escribe en el archivo correcto para el alcance que elijas, y es la forma más segura de evitar una errata que rompa ~/.claude.json.

Comandos HTTP y stdio

# Remote HTTP server with a bearer token
claude mcp add --transport http docs-search https://example.com/mcp \
  --header "Authorization: Bearer your-token"

# Local stdio server. The -- separates Claude's options from the server command
claude mcp add --transport stdio --env SERVICE_TOKEN=abc123 local-files -- npx -y @example/files-server

# Shared with the team and written to .mcp.json
claude mcp add --scope project --transport http docs-search https://example.com/mcp

Copiar prompt

En los servidores stdio, el doble guion no es opcional. Todo lo que va antes pertenece a Claude Code, y todo lo que va después es el comando que lanza el servidor.

Los servidores remotos usan http o sse, mientras que un proceso local usa stdio. Los servidores WebSocket no tienen un flag propio, así que los añades mediante JSON:

claude mcp add-json events-server '{"type":"ws","url":"wss://example.com/events"}'

Copiar prompt

Los servidores que usan OAuth aceptan --client-id, --client-secret y --callback-port, y claude mcp login <name> inicia sesión desde la línea de comandos.

Comprobar qué se ha conectado

Tres comandos responden a la mayoría de preguntas: claude mcp list muestra todos los servidores, claude mcp get <name> muestra uno y claude mcp remove <name> elimina uno. Dentro de una sesión, /mcp abre la misma vista y te permite autenticarte.

Qué definición gana

Cuando el mismo servidor aparece en más de un lugar, Claude Code se conecta a él una sola vez y usa la fuente con mayor precedencia.

Precedencia, de mayor a menor

1. Un servidor del ajuste gestionado managedMcpServers (Claude Code v2.1.259 o posterior)
2. Alcance local
3. Alcance de proyecto
4. Alcance de usuario
5. Servidores proporcionados por plugins
6. Conectores de claude.ai

Claude Code compara los duplicados entre los tres alcances por nombre. Compara los plugins y los conectores por endpoint, así que uno que apunta a la misma URL o al mismo comando que un servidor habilitado de arriba cuenta como duplicado.

El detalle más importante: se usa la entrada completa de la fuente ganadora, y los campos no se combinan. Supón que docs-search existe en el alcance de usuario con un encabezado Authorization y, otra vez, en el alcance de proyecto sin él. La definición del proyecto gana por completo y el encabezado de la entrada de usuario nunca aparece.

Avisos de aprobación para servidores compartidos

Por motivos de seguridad, Claude Code pide aprobación en las sesiones interactivas antes de usar un servidor de alcance de proyecto procedente de .mcp.json. Tres ajustes controlan el resultado:

{
  "enabledMcpjsonServers": ["docs-search"],
  "disabledMcpjsonServers": ["local-files"]
}

Copiar prompt

¿Tomaste una decisión de la que te arrepientes? claude mcp reset-project-choices borra las aprobaciones.

Desde la v2.1.196, un repositorio clonado no puede aprobar sus propios servidores. Las aprobaciones subidas al .claude/settings.json del proyecto se ignoran en una carpeta que no has marcado como de confianza, y el servidor se queda en ⏸ Pending approval. Las aprobaciones de tu archivo de ajustes de usuario, ~/.claude/settings.json, de los ajustes gestionados y de --settings siguen aplicándose. Un .claude/settings.local.json sin seguimiento también funciona, una vez que la carpeta es de confianza.

Las ejecuciones no interactivas, como claude -p, cargan los servidores del proyecto sin preguntar, salvo que las inicies con --strict-mcp-config. Ese flag indica a Claude Code que use solo los servidores pasados con --mcp-config.

💡 Revisa .mcp.json en una pull request como revisarías un script. Una entrada stdio ejecuta un comando en el equipo de cada compañero.

Archivos de ajustes y controles de política

Archivos de ajustes, de mayor a menor prioridad

Un ajuste de nivel superior anula el mismo ajuste de nivel inferior. ~/.claude.json es un archivo aparte que Claude Code escribe para sí mismo. Guarda tu sesión de inicio, la configuración de tus servidores MCP, el estado por proyecto como las decisiones de confianza y las opciones globales que cambia /config. No necesitas editarlo a mano.

Listas de permitidos y servidores gestionados

Los equipos que necesitan control tienen cuatro herramientas, ordenadas aquí de la más ligera a la más estricta:

• disabledMcpServers permite que un usuario se excluya de servidores concretos de usuario, de plugins, gestionados o de claude.ai.
• allowedMcpServers y deniedMcpServers filtran por nombre de servidor o por un patrón de serverUrl.
• managedMcpServers es un ajuste gestionado que ofrece servidores a todos, junto a los que añaden los usuarios.
• managed-mcp.json despliega un conjunto fijo de servidores desde las rutas del sistema mostradas antes.

Desplegar managed-mcp.json tiene un efecto secundario que conviene conocer. Por defecto, suprime los conectores de claude.ai que Claude Code obtiene por su cuenta. Para cargarlos junto a tus servidores gestionados, define "allowAllClaudeAiMcps": true en una fuente de ajustes gestionados. Definir la variable de entorno ENABLE_CLAUDEAI_MCP_SERVERS=false desactiva los conectores en un único equipo.

Timeouts y límites de salida

Timeouts de arranque y de herramientas

Importan dos temporizadores, y es fácil confundirlos.

El timeout por servidor sustituye a la variable de entorno MCP_TOOL_TIMEOUT solo para ese servidor. Los valores inferiores a 1000 se ignoran y se usa MCP_TOOL_TIMEOUT. Cuando esa variable no está definida, el valor predeterminado es de unas 28 horas. Las notificaciones de progreso del servidor no amplían el límite.

Salida grande de herramientas

Claude Code avisa cuando cualquier herramienta MCP devuelve más de 10.000 tokens y limita la salida a 25.000 tokens por defecto. Sube el límite con MAX_MCP_OUTPUT_TOKENS=50000 claude, o hazlo permanente mediante el campo env de un archivo de ajustes:

{
  "env": {
    "MCP_TIMEOUT": "10000",
    "MAX_MCP_OUTPUT_TOKENS": "50000"
  }
}

Copiar prompt

Arreglar rápido una configuración rota

Síntomas y soluciones

Si ~/.claude.json falla al analizarse, Claude Code copia el archivo roto a ~/.claude/backups/.claude.json.corrupted.<timestamp> y te pregunta si quieres salir para arreglarlo a mano o restablecer la configuración predeterminada. Para recuperar tu estado anterior, copia a su lugar uno de los cinco archivos .claude.json.backup.<timestamp> más recientes de ~/.claude/backups/.

💡 Las ediciones manuales de ~/.claude.json rara vez merecen el riesgo. Prefiere claude mcp add, add-json y remove, y guarda una copia del archivo antes de cualquier cambio manual.

Crea tus propias imágenes con Picasso IA

El trabajo de configuración termina en cuanto un servidor muestra ✔ Connected, pero documentarlo lleva más tiempo que hacerlo. Las capturas para el README, los diagramas de incorporación y los clips cortos de una sesión de terminal ralentizan a un equipo. Ahí es donde Picasso IA ayuda, con modelos de texto, imagen y video en un solo lugar.

Usa Claude Sonnet 5 en PicassoIA

Claude Sonnet 5 es un modelo de lenguaje diseñado para tareas de programación y uso de herramientas, lo que lo hace útil para redactar una entrada de configuración o revisarla antes de subirla. La página del modelo expone estas entradas:

1. Abre la página del modelo y pega tu petición en Prompt. Por ejemplo: "Convierte este comando claude mcp add en una entrada .mcp.json cuyo encabezado Authorization lea una variable de entorno."
2. Define Effort. El valor predeterminado es low, que desactiva el razonamiento para obtener la respuesta más rápida y barata. Elige high o max cuando un error abarque varios archivos.
3. Añade un System Prompt, como "Responde solo con JSON válido, sin comentarios", y reutilízalo durante la sesión.
4. No toques Max Tokens salvo que la salida sea larga. El valor predeterminado es 8.192.
5. Adjunta una imagen si tienes una captura de un error. El modelo la lee como contexto.
6. Ejecútalo y verifica. Pega el resultado en .mcp.json y ejecuta claude mcp get <name> para confirmar que el servidor se conectó.

💡 Trata la configuración generada como un borrador. Las rutas, los flags y los ajustes cambian entre versiones, así que compruébalos uno a uno con la documentación oficial.

En el lado visual, modelos de texto a imagen como PicassoIA Image y Seedream 5 Pro pueden crear arte de cabecera para una página de documentación o una entrada de changelog. Para ajustar una imagen que ya tienes, abre PicassoIA Image Editor Pro. Para movimiento, PicassoIA Video y Seedance 2.5 Lite convierten un prompt o una imagen fija en un clip corto.

PicassoIA también ofrece conexiones MCP para sus modelos de imagen y video, que gestionas desde tu cuenta en picassoia.com/en/mcp/accounts. Una vez que tengas los datos de conexión, un servidor HTTP se añade con el mismo patrón claude mcp add --transport http mostrado antes.

Elige un modelo, escribe un prompt y genera tu primera imagen de cabecera o clip para el próximo README. Prueba algunas variaciones, compáralas lado a lado y quédate con la que encaje. Todo te espera en picassoia.com/en/all-models.