MCP en Claude Code: cómo añadir y gestionar servidores

Para configurar MCP en Claude Code, ejecuta claude mcp add en la terminal. Un servidor local es claude mcp add <nombre> -- <comando>, uno remoto es claude mcp add --transport http <nombre> <url>, y --scope decide si el servidor es solo para ti en este proyecto (local, el valor por defecto), para todo el equipo mediante un archivo .mcp.json (project) o para ti en todos tus proyectos (user). Después escribe /mcp dentro de una sesión para comprobar la conexión e iniciar sesión en los servidores que usan OAuth.

Esta guía recorre cada paso: transportes, el separador --, variables de entorno y cabeceras, scopes, escribir .mcp.json a mano, los comandos list, get y remove, OAuth, la importación desde Claude Desktop, timeouts y límites de salida, y qué revisar antes de fiarte de los servidores de un proyecto. Los comandos salen de la documentación de MCP de Claude Code de Anthropic, a octubre de 2026. Si MCP es nuevo para ti, empieza por qué es un servidor MCP; si quieres saber qué servidores añadir, mira los mejores servidores MCP para programar.

Referencia rápida

También valen las opciones cortas: -t para --transport, -s para --scope, -e para --env y -H para --header.

Elige un transporte: stdio, HTTP o SSE

Un servidor MCP llega a Claude Code de una de tres formas:

Ya casi nunca necesitas --transport sse. Desde Claude Code 2.1.265, claude mcp add --transport http prueba primero HTTP y cambia solo a SSE si el servidor no acepta HTTP. En versiones anteriores, pasa --transport sse de forma explícita.

Añadir un servidor stdio local

La regla que más confunde: las opciones propias de Claude Code (--transport, --scope, --env) van antes del nombre del servidor, y todo lo que va después de -- es el comando del servidor y se pasa tal cual.

# Forma básica
claude mcp add [opciones] <nombre> -- <comando> [argumentos...]

# Playwright, ejecutado con npx
claude mcp add playwright -- npx -y @playwright/mcp@latest

# Un servidor que necesita una API key en su entorno
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Sin --, una opción del servidor como --port 8080 se leería como opción de Claude Code y el comando fallaría. Otra trampa que cita la documentación: --env acepta varios pares KEY=value, así que si el nombre del servidor va justo detrás, se lee como otro par y se rechaza. Pon otra opción en medio, como --transport stdio, igual que en el ejemplo.

Claude Code define CLAUDE_PROJECT_DIR en el entorno de cada servidor stdio, así que el servidor puede encontrar la raíz del proyecto sin depender del directorio de trabajo.

Añadir un servidor HTTP remoto

Los servidores remotos reciben una URL en lugar de un comando. Añade cabeceras con --header cuando el servidor pida una API key o un bearer token:

# Un servidor alojado que inicia sesión con OAuth
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Un servidor que usa un token estático
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

La cabecera que escribas aquí se guarda en texto plano en el archivo de configuración. Para cualquier cosa compartida, mejor OAuth o una referencia ${VAR} en .mcp.json, como verás abajo.

Si ya tienes una definición JSON sacada del README del servidor, sáltate las opciones y pégala con add-json. Recibe el objeto que iría dentro de mcpServers, no el archivo completo:

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

Elige un scope

Cada claude mcp add escribe en uno de tres scopes:

claude mcp add --transport http stripe https://mcp.stripe.com                      # local
claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Regla práctica: las herramientas personales y todo lo que lleve tus credenciales va en user o local; los servidores que todo el equipo necesita para trabajar en el repo van en project.

Ojo: aquí «local» no es .claude/settings.local.json. Los servidores MCP locales viven en ~/.claude.json, en tu carpeta de usuario.

Cuando el mismo nombre está definido en más de un sitio, Claude Code toma el de mayor prioridad y no mezcla campos: primero local, luego project, luego user, luego los servidores de plugins y por último los conectores de claude.ai. Si dos scopes apuntan el mismo nombre a endpoints distintos, claude mcp list y /mcp te avisan.

Escribir .mcp.json a mano

Un servidor con scope project no es más que un archivo .mcp.json que puedes editar y revisar en pull requests:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

${VAR} se expande al valor de una variable de entorno y ${VAR:-default} usa un valor por defecto si no existe. La expansión funciona en command, args, env, url y headers, y así commiteas el archivo sin commitear tokens: cada desarrollador define API_KEY en su propia shell. Si falta una variable sin valor por defecto, claude mcp list y /mcp avisan y dejan el texto sin expandir.

Un "timeout" por servidor, en milisegundos, fija un límite estricto para las llamadas a herramientas de ese servidor.

Gestionar servidores: list, get, remove y /mcp

Desde la shell:

claude mcp list          # todos los servidores con su estado de conexión
claude mcp get notion    # detalles de un servidor, incluido por qué falló
claude mcp remove notion # lo borra de su scope

list y get muestran el detalle del error con las credenciales ocultas. Un servidor de proyecto que aún no has aprobado aparece como pendiente hasta que abres claude en modo interactivo y lo apruebas.

Dentro de una sesión, /mcp es el panel de control. Muestra el estado y el número de herramientas de cada servidor, y desde el menú de un servidor puedes autenticarte, volver a autenticarte, borrar la autenticación, reconectar o desactivar el servidor sin borrar su configuración. /mcp reconnect all reintenta todos los servidores caídos a la vez (Claude Code 2.1.284 o posterior).

Los servidores conectados aportan más que herramientas. Escribe @ para referenciar recursos de un servidor junto a tus archivos, y escribe / para ver sus prompts, listados como /servidor:prompt (MCP). Las herramientas se llaman mcp__<servidor>__<herramienta>, y ese es el nombre que usas en las reglas de permisos y en los matchers de hooks.

Iniciar sesión en servidores OAuth

Muchos servidores alojados, como Sentry, Notion o Linear, usan OAuth en lugar de un token estático. Añade el servidor con --transport http y sin cabecera, y luego inicia sesión:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Dentro de Claude Code, ejecuta /mcp, elige el servidor y pulsa Authenticate. Se abre el navegador, inicias sesión, y Claude Code guarda el token y lo renueva. También puedes hacerlo desde la shell sin abrir una sesión:

claude mcp login sentry               # abre el navegador
claude mcp login sentry --no-browser  # imprime la URL, para sesiones SSH
claude mcp logout sentry              # olvida las credenciales guardadas

Las ejecuciones headless (claude -p) no pueden mostrar un login, así que inicia sesión una vez en modo interactivo antes. Algunos servidores necesitan un puerto de callback fijo o una app OAuth registrada de antemano; para ellos, pasa --callback-port, --client-id y --client-secret al añadir el servidor. El secreto se pide con entrada oculta, o se lee de MCP_CLIENT_SECRET en CI.

Importar servidores desde Claude Desktop

Si ya configuraste servidores en la app Claude Desktop, no tienes que volver a escribirlos:

claude mcp add-from-claude-desktop

Un diálogo te deja elegir qué servidores importar. A octubre de 2026 solo funciona en macOS y en WSL. Añade --scope user para importarlos a tu configuración de usuario. Los nombres solo pueden tener letras, dígitos, guiones y guiones bajos, así que un servidor de Desktop con un espacio en el nombre se omite y se informa, y un nombre que ya existe recibe un sufijo como server_1.

Solución de problemas

Los resultados de texto largos tienen un segundo límite: un resultado de más de 50.000 caracteres se guarda en un archivo en lugar de entrar directamente en el contexto.

Los servidores remotos que se caen a mitad de sesión se reintentan hasta cinco veces con espera creciente, pero los servidores stdio no se reintentan solos, así que un servidor local caído necesita reconectarse desde /mcp.

El contexto es el otro coste a vigilar. Claude Code usa por defecto la búsqueda de herramientas (tool search) en los modelos actuales: al arrancar solo carga los nombres de las herramientas y las instrucciones de los servidores, y las definiciones completas se cargan cuando Claude las necesita. Eso abarata una lista larga de servidores, pero cada servidor sigue siendo una pieza más que puede fallar o usarse mal, así que mantén la lista corta. Para scripts, --mcp-config <archivo> carga servidores extra para una sola ejecución, y --strict-mcp-config hace que Claude Code use solo esos.

Seguridad: los servidores de proyecto son código del repo

Un .mcp.json en un repo puede lanzar cualquier comando local o apuntar a cualquier URL. Eso es lo que lo hace útil para equipos, y también la razón por la que Claude Code lo trata con cuidado:

• Primero, aprobación. En una sesión interactiva, Claude Code pregunta antes de usar servidores con scope project. claude mcp reset-project-choices borra tus respuestas anteriores.
• Un repo no puede aprobarse a sí mismo. Ajustes como enableAllProjectMcpServers commiteados en el .claude/settings.json del proyecto se ignoran hasta que confías en la carpeta, y el servidor sigue pendiente. Las aprobaciones de tu propia configuración de usuario sí cuentan.
• Las ejecuciones headless no preguntan. En claude -p y en el Agent SDK no hay diálogo, así que los servidores de proyecto se cargan sin él. Para bloquear un servidor en cualquier modo, inclúyelo en disabledMcpjsonServers.
• Las credenciales se quedan en casa. En url y headers de un servidor remoto, las variables sensibles como ANTHROPIC_API_KEY se expanden vacías aunque estén definidas, así que un proyecto no puede mandar tu clave de Anthropic a su servidor sin que lo notes.
• Fíate tan poco de lo que devuelve un servidor como de lo que ejecuta. La documentación de Anthropic avisa de que los servidores que traen contenido externo pueden exponerte a prompt injection. Prefiere modos de solo lectura y tokens con permisos mínimos.

Antes de aprobar, lee el command, los args y la url de cada servidor como leerías un script postinstall. El panorama completo está en seguridad de los agentes de código con IA.

Cuando usas algo más que Claude Code

Todo lo anterior es por CLI. Codex guarda sus servidores en ~/.codex/config.toml, Gemini CLI en su propio settings.json, y cada herramienta tiene sus comandos. Si Claude Code es el único agente que usas, claude mcp add y un .mcp.json commiteado es todo lo que necesitas, y nada de esto requiere otra herramienta.

Si usas varias CLI de código, las listas acaban divergiendo. Para eso está el gestor de MCP de AgentVera, la app de escritorio que publica este blog:

• Se añade una vez y se conecta al arrancar. Registras servidores stdio, HTTP y SSE en AgentVera, y se conectan cuando arrancan los agentes: a todos, a los que elijas, a los agentes de un grupo o a un rol de equipo. Claude Code, Codex y las demás CLI que admiten MCP los reciben.
• En sintonía con la configuración de Claude Code. Los servidores de la configuración de Claude Code y de Codex aparecen con su estado; puedes importarlos a AgentVera o quitarlos de la CLI, y los servidores de AgentVera también se pueden escribir en la configuración de la CLI.
• Un solo login, sin tokens en archivos. Los servidores remotos pasan por el gateway de AgentVera, inicias sesión una vez en la app en un servidor OAuth y la CLI del agente no guarda ninguna cabecera ni token. Las variables de entorno y cabeceras secretas se guardan en el llavero del sistema operativo.
• Costes visibles. Una prueba de conexión lista las herramientas, prompts y recursos de un servidor con un coste aproximado en tokens por herramienta.

En resumen

Empieza con un servidor que de verdad necesites, añadido con claude mcp add en el scope más estrecho que funcione. Compruébalo con claude mcp list o /mcp, inicia sesión con /mcp o claude mcp login, y pásalo a un .mcp.json commiteado solo cuando lo necesite todo el equipo, con los tokens en referencias ${VAR}. Cuando algo falle, claude mcp get, MCP_TIMEOUT y MAX_MCP_OUTPUT_TOKENS resuelven casi todo.

Para seguir leyendo:

• ¿Qué es un servidor MCP?
• Los mejores servidores MCP para agentes de código
• Gestor de MCP
• Claude Code como agente