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

URL: https://agentvera.dev/es/blog/claude-code-mcp-setup/ · Publicado: 2026-10-28

Cómo añadir servidores MCP a Claude Code: claude mcp add para stdio y HTTP, scopes, .mcp.json, /mcp y OAuth, importar desde Claude Desktop, timeouts y límites.

**En resumen:**

- Añades un servidor con claude mcp add: las opciones van antes del nombre y el comando de un servidor stdio local va después de --. Los servidores remotos usan --transport http con una URL.
- El scope decide dónde se guarda: local (por defecto) y user en ~/.claude.json; project en un .mcp.json en la raíz del repo que puedes commitear.
- Con /mcp dentro de una sesión ves el estado, inicias sesión en servidores OAuth y desactivas servidores. MCP_TIMEOUT y MAX_MCP_OUTPUT_TOKENS resuelven casi todos los fallos de arranque y de salida.
- Claude Code pregunta antes de usar los servidores del .mcp.json de un proyecto. Revísalos como cualquier código del repo y guarda los tokens en referencias ${VAR}, no en el archivo.

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](https://code.claude.com/docs/en/mcp "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](/es/blog/what-is-mcp-server/ "Qué es un servidor MCP"); si quieres saber qué servidores añadir, mira [los mejores servidores MCP para programar](/es/blog/best-mcp-servers-for-coding/ "Los mejores servidores MCP para programar").

## Referencia rápida

| Tarea | Comando |
| --- | --- |
| Añadir un servidor local (stdio) | `claude mcp add <nombre> -- <comando> [argumentos...]` |
| Añadir un servidor remoto (HTTP) | `claude mcp add --transport http <nombre> <url>` |
| Añadir desde un fragmento JSON | `claude mcp add-json <nombre> '<json>'` |
| Compartir con el equipo | añade `--scope project` (escribe `.mcp.json`) |
| Usarlo en todos tus proyectos | añade `--scope user` |
| Listar servidores y su estado | `claude mcp list` |
| Ver los detalles de un servidor | `claude mcp get <nombre>` |
| Eliminar un servidor | `claude mcp remove <nombre>` |
| Iniciar sesión en un servidor OAuth | `/mcp` en una sesión, o `claude mcp login <nombre>` |
| Importar desde Claude Desktop | `claude mcp add-from-claude-desktop` |
| Estado, login, desactivar, reconectar | `/mcp` dentro de Claude Code |

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](/es/glossary/mcp/ "MCP") llega a Claude Code de una de tres formas:

| Transporte | Qué es | Cuándo usarlo |
| --- | --- | --- |
| `stdio` | Un proceso local que Claude Code arranca y con el que habla por stdin y stdout | Servidores que ejecutas con `npx`, `uvx`, Docker o un script propio |
| `http` | Un servidor remoto por HTTP streamable | Servicios alojados: Notion, Sentry, GitHub, Stripe y otros. Anthropic lo recomienda para servidores remotos |
| `sse` | Server-Sent Events | Solo servidores remotos antiguos. La documentación marca SSE como obsoleto |

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.

```bash
# 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:

```bash
# 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:

```bash
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:

| Scope | Opción | Se guarda en | Quién lo recibe |
| --- | --- | --- | --- |
| Local (por defecto) | `--scope local` | `~/.claude.json`, bajo la ruta de este proyecto | Solo tú, solo en este proyecto |
| Project | `--scope project` | `.mcp.json` en la raíz del proyecto | Todos los que clonan el repo |
| User | `--scope user` | `~/.claude.json` | Solo tú, en todos los proyectos |

```bash
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:

```json
{
  "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:

```bash
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](/es/blog/claude-code-hooks-guide/ "Guía de hooks de Claude Code").

## 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:

```bash
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:

```bash
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:

```bash
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

| Síntoma | Qué probar |
| --- | --- |
| El servidor no conecta | `claude mcp get <nombre>` para ver el error y luego **Reconnect** en `/mcp` |
| Un servidor lento agota el tiempo al arrancar | Arranca con `MCP_TIMEOUT=10000 claude` (diez segundos) |
| Las llamadas largas se cortan | `MCP_TOOL_TIMEOUT` para todos los servidores, o `"timeout"` por servidor en `.mcp.json` |
| Aviso de salida o resultados truncados | Claude Code avisa por encima de 10.000 tokens y corta en 25.000 por defecto. Súbelo con `MAX_MCP_OUTPUT_TOKENS=50000` |
| Las opciones del servidor se ignoran o se rechazan | Opciones de Claude Code antes del nombre y comando del servidor después de `--` |
| Aviso de `${VAR}` en `/mcp` | Define la variable en la shell desde la que arrancas Claude Code, o añade `:-default` |
| El servidor se omite al cargar | El nombre está reservado (`workspace`, `claude-in-chrome`, `computer-use` y alguno más); cámbialo |
| El token funciona con curl pero aquí no | Busca un espacio o salto de línea al final del token pegado; Claude Code avisa de espacios ocultos |

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](/es/glossary/prompt-injection/ "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](/es/blog/ai-coding-agent-security/ "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](/es/features/mcp-manager/ "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?](/es/blog/what-is-mcp-server/ "Qué es un servidor MCP")
- [Los mejores servidores MCP para agentes de código](/es/blog/best-mcp-servers-for-coding/ "Los mejores servidores MCP para programar")
- [Gestor de MCP](/es/features/mcp-manager/ "Gestor de MCP")
- [Claude Code como agente](/es/agents/claude-code/ "Claude Code en AgentVera")

## Preguntas frecuentes

**¿Cómo añado un servidor MCP a Claude Code?** Ejecuta claude mcp add en la terminal. Para un servidor local: claude mcp add <nombre> -- <comando> [argumentos]. Para uno remoto: claude mcp add --transport http <nombre> <url>. Luego usa claude mcp list, o /mcp dentro de una sesión, para comprobar que conecta.

**¿Dónde guarda Claude Code los servidores MCP?** Los servidores con scope local (por defecto) y user viven en ~/.claude.json; los locales, bajo la ruta del proyecto actual. Los servidores con scope project viven en un archivo .mcp.json en la raíz del proyecto, que puedes commitear para tu equipo.

**¿Qué diferencia hay entre local, project y user?** Local es solo para ti y solo en este proyecto. Project es para todos los que clonan el repo, a través de .mcp.json. User es solo para ti, pero en todos los proyectos de tu máquina. Si un nombre existe en varios scopes, local gana a project y project gana a user.

**¿Cómo inicio sesión en un servidor MCP que usa OAuth?** Añádelo con --transport http y luego ejecuta /mcp en Claude Code y elige Authenticate, o usa claude mcp login <nombre> desde la shell. El login en el navegador completa el flujo, y Claude Code guarda y renueva el token por ti.

**¿Por qué mi servidor MCP agota el tiempo o corta su salida?** Los servidores lentos pueden necesitar más tiempo de arranque: inicia Claude Code con MCP_TIMEOUT=10000 para diez segundos. La salida de las herramientas tiene un tope de 25.000 tokens por defecto, con aviso por encima de 10.000; súbelo con MAX_MCP_OUTPUT_TOKENS.

**¿Es seguro usar el .mcp.json de un repo clonado?** Trátalo como cualquier código que no escribiste tú. Claude Code pide aprobación antes de usar servidores de proyecto en una sesión interactiva, y un repo clonado no puede aprobar sus propios servidores. Lee cada comando y cada URL antes de aceptar.

---

**Sobre AgentVera.** AgentVera es una app de escritorio para macOS, Windows y Linux, desarrollada por Solviera Teknoloji. Ejecuta 18 agentes de programación con IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) en paralelo, por proyecto, en terminales reales con las instalaciones y sesiones de CLI del propio usuario. El plan gratuito tiene agentes ilimitados. Descargar: https://agentvera.dev/es/download/ · Precios: https://agentvera.dev/es/pricing/