MCP en Claude Code: cómo añadir servidores y dónde está la configuración

Cómo añadir un servidor MCP a Claude Code

1. Elige el transporte

   Usa HTTP para servidores remotos alojados en la nube; es el transporte recomendado, y Claude Code recurre al transporte SSE, ya obsoleto, cuando un servidor solo ofrece ese. Usa stdio para servidores que se ejecutan como un proceso local. En stdio, todo lo que va después de -- se pasa tal cual al servidor.

   # Servidor HTTP remoto (recomendado para servicios en la nube)
   claude mcp add --transport http notion https://mcp.notion.com/mcp
   
   # Con un bearer token
   claude mcp add --transport http secure-api https://api.example.com/mcp \
     --header "Authorization: Bearer your-token"
   
   # Servidor stdio local: todo lo que va después de -- es el comando propio del servidor
   claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
     -- npx -y airtable-mcp-server

2. Elige un ámbito

   Sin --scope, un servidor es local: solo para ti y solo en este proyecto. Añade --scope project para escribirlo en .mcp.json y compartirlo con el equipo, o --scope user para todos tus proyectos. Consulta la tabla de abajo.

3. Inicia sesión si el servidor lo pide

   Muchos servidores remotos usan OAuth. Ejecuta /mcp dentro de Claude Code y elige el servidor para autenticarte, o claude mcp login <name> en tu terminal. Las ejecuciones sin interfaz con -p no pueden abrir el flujo de inicio de sesión, así que inicia sesión primero de forma interactiva.

4. Comprueba que se ha conectado

   Ejecuta /mcp para ver el estado y las herramientas de cada servidor, y claude mcp list en tu terminal. Después pídele a Claude que use la herramienta por su nombre.

5. Gestiona tus servidores

   Lista, inspecciona, elimina o importa servidores desde la línea de comandos. Si usas uno muy poco, desactívalo desde /mcp en lugar de eliminarlo.

   claude mcp list            # todos los servidores configurados
   claude mcp get notion      # los detalles de un servidor
   claude mcp remove notion   # eliminarlo (ejecuta antes claude mcp logout notion para revocar los tokens)
   claude mcp add-from-claude-desktop   # importar desde Claude Desktop (macOS, WSL)

Fuente: documentación de Claude Code, Connect Claude Code to tools via MCP

Ámbitos de MCP y ubicación de los archivos de configuración

Aquí es donde Claude Code guarda la configuración de MCP. Ten en cuenta que el ámbito "local" de MCP vive en ~/.claude.json, no en .claude/settings.local.json.

Comparte servidores con .mcp.json

.mcp.json permite que todo el equipo use los mismos servidores. Deja los secretos fuera con variables de entorno: ${VAR} se sustituye por el valor de la variable, y ${VAR:-default} usa un valor por defecto cuando no está definida. La expansión funciona en command, args, env, url y headers.

1. Usa variables en lugar de secretos

   Claude Code pide a cada persona que apruebe los servidores de proyecto de .mcp.json la primera vez; claude mcp reset-project-choices restablece esas respuestas. Una entrada JSON con url también necesita un type, como http.

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

Precedencia, conectores y otros detalles

• Cuando el mismo servidor está definido dos veces, Claude Code se conecta una sola vez, usando el primero de: local, project, user, plugin, conector de claude.ai. Las entradas no se combinan; los servidores gestionados de una organización tienen prioridad sobre todos ellos.
• Si inicias sesión en Claude Code con una cuenta de claude.ai, los conectores que añadiste en claude.ai aparecen automáticamente.
• Claude Code también puede ser un servidor MCP: claude mcp serve expone sus herramientas a otro cliente, como Claude Desktop.
• Los servidores también pueden ofrecer prompts que aparecen como comandos de barra; consulta los comandos de barra de Claude Code.
• Eliminar un servidor remoto borra los tokens que Claude Code guardó, pero no los revoca; para eso, ejecuta antes claude mcp logout <name>.

MCP y consumo de tokens

Las definiciones de herramientas se cargan de forma diferida por defecto: solo los nombres de las herramientas y las instrucciones del servidor ocupan contexto hasta que Claude usa una herramienta, así que una lista larga de servidores cuesta menos que antes. Aun así, cada servidor añade algo, de modo que desactiva en /mcp los que no uses y prefiere una CLI como gh, aws o gcloud cuando exista, ya que no añade ninguna lista de herramientas. Más en cómo reducir el consumo de tokens de Claude Code.

Solución de problemas: cuando un servidor no conecta

• Aparece como pendiente de autenticación: abre /mcp y elige Re-authenticate, o ejecuta claude mcp login <name>.
• "has a url but no type": añade "type": "http" (o sse o ws) a la entrada JSON; sin tipo, Claude Code la trata como stdio.
• Las opciones de un servidor stdio desaparecieron: pon -- antes del comando del servidor para que Claude Code no las interprete como suyas.
• Aviso de variable ausente en claude mcp list: define la variable o dale un valor :-default.
• Un servidor de proyecto nunca se carga con claude -p: sin interfaz no hay aviso de aprobación, así que revisa tu configuración o pasa los servidores explícitamente con --mcp-config y --strict-mcp-config.
• Los nombres de servidor añadidos con claude mcp solo pueden contener letras, números, guiones y guiones bajos.

Dale a tus empleados de IA las mismas herramientas que usas tú

MCP es la forma en que Claude Code llega a tu gestor de issues, tu base de datos o tu analítica. Crewmark convierte una sesión de Claude Code, Codex, DeepSeek Harness u OpenCode en un empleado de IA con un rol, un objetivo y un horario, y la despierta con un heartbeat para que tome la siguiente issue de un tablero, con los servidores MCP de tu proyecto disponibles.

1. Haz commit de .mcp.json

   Los servidores con ámbito de proyecto se cargan en la sesión del empleado igual que en la tuya; para los servidores que necesitan OAuth, inicia sesión una vez de forma interactiva.

2. Deja que el heartbeat inicie el trabajo

   Durante su horario, el empleado se despierta cada 15, 30 o 60 minutos en la misma conversación; consulta cómo hacer que Claude Code sea proactivo.

3. Dale a cada rol solo lo que necesita

   Un empleado de SEO recibe Search Console; un programador, GitHub y Sentry. Lee qué es un empleado de IA.

Preguntas frecuentes sobre MCP en Claude Code