Domingo, 22 de noviembre de 2026  ·  Español
Intermedio 30 min en total 6 pasos

Cómo agregar un servidor MCP a Claude Code

Conecta Claude Code a herramientas externas con claude mcp add: servidores remotos y locales, scopes y errores típicos.

Daniel Puentes Prias
Consultor de IA · Actualizado el 13 de noviembre de 2026
Requisitos
  • Claude Code instalado con el instalador nativo y sesión iniciada (plan Pro, Max, Team/Enterprise o cuenta de la Consola de Anthropic)
  • Terminal en macOS, Linux, WSL o Windows (PowerShell)
  • Node.js 18+ si vas a usar servidores MCP locales que se lanzan con npx
  • Un repositorio de prueba donde abrir Claude Code
  • Opcional: cuenta en un servicio con servidor MCP remoto (por ejemplo Notion o Sentry)
Lo que vas a aprender
  • Añadir servidores MCP remotos (HTTP) y locales (stdio) con el comando claude mcp add
  • Elegir el scope correcto (local, project o user) y compartir la configuración con tu equipo mediante .mcp.json
  • Pasar variables de entorno y credenciales sin dejarlas expuestas en el repositorio
  • Autenticarte con OAuth y verificar el estado de los servidores desde /mcp
  • Diagnosticar los fallos más comunes: el separador --, npx en Windows, timeouts y servidores que no arrancan
PASO 1 · ~4 min

Verificar la instalación de Claude Code

Antes de tocar MCP, confirma que tienes una versión reciente de Claude Code, porque el subcomando claude mcp y el soporte de transporte HTTP han ido mejorando en cada versión. Claude Code se instala con el instalador nativo, no con npm; si lo instalaste en su día con npm, conviene migrar para recibir actualizaciones automáticas. Ejecuta los comandos de abajo: el primero instala o actualiza en macOS, Linux o WSL; en Windows usa la línea de PowerShell. Después comprueba la versión y lanza claude mcp list. Si es la primera vez, verás que no hay servidores configurados, lo cual es perfecto como punto de partida. Un servidor MCP (Model Context Protocol) es simplemente un proceso o endpoint que expone herramientas, recursos y prompts que Claude puede invocar durante la sesión: consultar tu base de datos, leer issues, navegar una web, etc. Claude Code actúa como cliente MCP, así que tu trabajo se reduce a decirle dónde está el servidor y cómo arrancarlo.

bash
# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows (PowerShell)
# irm https://claude.ai/install.ps1 | iex

# Comprobar versión y estado general
claude --version
claude doctor

# Ver servidores MCP configurados (debería estar vacío)
claude mcp list
Consejoclaude doctor te avisa si tienes instalaciones duplicadas (por ejemplo, una antigua de npm y la nativa). Es la causa número uno de 'he añadido el servidor y no aparece': estás ejecutando otro binario.
Error comúnNo instales Claude Code con npm install -g. Si ya lo tienes así, desinstala esa versión tras instalar la nativa para que el comando claude apunte al binario correcto.
PASO 2 · ~6 min

Añadir un servidor MCP remoto por HTTP

Los servidores remotos son los más cómodos: no instalas nada, solo apuntas a una URL. La sintaxis es claude mcp add --transport http <nombre> <url>. El nombre es libre y es como lo verás dentro de Claude Code, así que usa algo corto y en minúsculas. En el ejemplo conectamos Notion y Sentry, que ofrecen endpoints MCP oficiales. Si el servicio requiere autenticación por cabecera (una API key), añade --header. Si usa OAuth, no pongas nada más: la autenticación se hace después desde la propia sesión. Abre Claude Code en tu proyecto con claude, escribe /mcp y verás la lista de servidores con su estado; selecciona el que pida autenticación y sigue el flujo en el navegador. Los tokens se guardan de forma segura y se refrescan solos. Existe también el transporte SSE, pero está en desuso: si un proveedor ofrece HTTP y SSE, elige siempre HTTP.

bash
# Servidor remoto con OAuth (te autenticarás luego con /mcp)
claude mcp add --transport http notion https://mcp.notion.com/mcp

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

# Servidor remoto con API key en cabecera
claude mcp add --transport http mi-api https://api.ejemplo.com/mcp \
  --header "Authorization: Bearer $MI_API_TOKEN"

# Comprobar
claude mcp list
ConsejoSi trabajas desde España o LATAM con VPN corporativa o proxy, prueba primero la URL con curl -I. Muchos 'el servidor no conecta' son en realidad bloqueos del proxy de la empresa, no fallos de Claude Code.
Error comúnLas opciones (--transport, --header, --scope) van ANTES del nombre del servidor. Si las pones al final, el CLI las interpreta como parte de la URL o del comando y el servidor queda mal configurado.
PASO 3 · ~6 min

Añadir un servidor MCP local por stdio

Los servidores locales se ejecutan como un proceso en tu máquina y se comunican por entrada/salida estándar. Son ideales para herramientas que necesitan acceso a tu sistema: un navegador con Playwright, una base de datos local o tu sistema de ficheros. La clave está en el separador --: todo lo que va antes son opciones de Claude Code; todo lo que va después es el comando exacto que lanza el servidor. Para pasar credenciales usa --env CLAVE=valor (o -e), que se inyectan solo en ese proceso. En el ejemplo añadimos Playwright para que Claude pueda abrir y probar tu web, y un servidor de Postgres con su cadena de conexión. La primera vez que Claude use estas herramientas, npx descargará el paquete, así que tarda unos segundos más de lo normal. Si alguna vez cambias de opinión, puedes eliminar el servidor y volver a añadirlo con otros parámetros sin afectar al resto.

bash
# Playwright: navegador controlable por Claude
claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest

# Servidor con variables de entorno
claude mcp add --transport stdio postgres \
  --env DATABASE_URL="postgresql://lectura:secreto@localhost:5432/app" \
  -- npx -y mi-servidor-postgres-mcp

# Windows nativo (no WSL): envuelve npx con cmd /c
# claude mcp add --transport stdio playwright -- cmd /c npx -y @playwright/mcp@latest

# Ver el detalle de un servidor
claude mcp get playwright
ConsejoPara bases de datos, crea un usuario de solo lectura para el MCP. Claude no hará nada que no apruebes, pero limitar permisos en el origen es la forma más barata de dormir tranquilo.
Error comúnEn Windows nativo, lanzar npx directamente suele dar 'Connection closed' porque npx es un script .cmd. Usa cmd /c npx ... como en el ejemplo comentado.
PASO 4 · ~6 min

Elegir el scope y compartir con .mcp.json

Cada servidor se guarda en un scope que decide quién lo ve. Por defecto es local: solo tú, solo en este proyecto. Con --scope user lo tienes disponible en todos tus proyectos (útil para Playwright o herramientas personales). Con --scope project se escribe en un fichero .mcp.json en la raíz del repo, que puedes commitear para que todo el equipo tenga los mismos servidores. Cuando un compañero abra Claude Code en ese repo, se le pedirá aprobar los servidores del proyecto antes de usarlos, por seguridad. Para no meter secretos en Git, .mcp.json admite expansión de variables de entorno con la sintaxis ${VAR} y ${VAR:-valor_por_defecto}: cada desarrollador define la variable en su máquina y el fichero queda limpio. Si ya tienes la configuración en JSON (por ejemplo, copiada de la documentación de un proveedor), claude mcp add-json te ahorra traducirla a flags.

bash
# Disponible en todos tus proyectos
claude mcp add --transport stdio --scope user playwright -- npx -y @playwright/mcp@latest

# Compartido con el equipo (crea/actualiza .mcp.json)
claude mcp add --transport http --scope project sentry https://mcp.sentry.dev/mcp

# Ejemplo de .mcp.json con variables de entorno, sin secretos
cat > .mcp.json <<'EOF'
{
  "mcpServers": {
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mi-servidor-postgres-mcp"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}
EOF

# Añadir desde JSON en una línea
claude mcp add-json github-local '{"type":"stdio","command":"npx","args":["-y","mi-servidor-github-mcp"]}'
ConsejoSi el mismo nombre existe en varios scopes, gana local sobre project y project sobre user. Útil para sobreescribir en tu máquina un servidor del equipo sin tocar el .mcp.json compartido.
Error comúnNunca commitees un .mcp.json con tokens o contraseñas en claro. Usa ${VAR} y documenta en el README qué variables tiene que exportar cada desarrollador.
PASO 5 · ~4 min

Usar y gestionar los servidores en una sesión

Abre Claude Code en tu proyecto y escribe /mcp para ver todos los servidores, su estado (conectado, fallido, pendiente de autenticación) y las herramientas que expone cada uno. A partir de aquí no hace falta invocarlos explícitamente: pide la tarea en lenguaje natural y Claude elegirá la herramienta adecuada, pidiéndote permiso la primera vez. Por ejemplo: 'Revisa los errores de Sentry de las últimas 24 horas en el proyecto web y propón un fix', o 'Abre localhost:3000 con Playwright y comprueba que el formulario de alta valida el NIF'. Si un servidor expone prompts, aparecen como comandos con barra del tipo /mcp__servidor__prompt. Y si expone recursos, puedes referenciarlos con @ en el prompt. Para mantener orden, elimina lo que no uses: cada servidor añade descripciones de herramientas al contexto y, con muchos activos, gastas tokens y Claude tiene más donde equivocarse al elegir.

bash
# Dentro de Claude Code:
#   /mcp            -> estado, autenticación y herramientas de cada servidor
#
# Desde la terminal:
claude mcp list
claude mcp get sentry
claude mcp remove mi-api

# Reutilizar los servidores que ya tienes en Claude Desktop (macOS y WSL)
claude mcp add-from-claude-desktop
ConsejoPara que Claude no te pida permiso cada vez en herramientas de solo lectura, añádelas a la lista de permitidas en la configuración de permisos del proyecto. Mantén con confirmación las que escriben o borran.
Error comúnSi añades o cambias un servidor con una sesión ya abierta, puede que no aparezca hasta reiniciar Claude Code. Sal y vuelve a lanzar claude antes de dar por hecho que está roto.
PASO 6 · ~4 min

Diagnosticar los errores más comunes

Cuando un servidor sale como fallido en /mcp, sigue este orden. Primero, ejecuta el comando del servidor a mano en la terminal (lo que pusiste tras el --): si falla ahí, el problema no es Claude Code sino el paquete, Node o las variables de entorno. Segundo, lanza Claude Code con --debug para ver los logs de conexión MCP. Tercero, si el servidor tarda en arrancar (descargas de npx en conexiones lentas, contenedores Docker), sube el tiempo de espera con la variable MCP_TIMEOUT en milisegundos. Cuarto, si una herramienta devuelve respuestas enormes y ves avisos de salida truncada, ajusta MAX_MCP_OUTPUT_TOKENS, aunque normalmente es mejor pedirle a Claude que filtre o pagine. Por último, si usas OAuth y deja de funcionar, entra en /mcp, borra la autenticación de ese servidor y vuelve a autenticarte: los tokens caducados o revocados son una causa frecuente tras cambiar de contraseña.

bash
# 1. Probar el servidor fuera de Claude Code
npx -y @playwright/mcp@latest --help

# 2. Ver logs detallados de conexión MCP
claude --debug

# 3. Más margen para arrancar servidores lentos (10 s)
MCP_TIMEOUT=10000 claude

# 4. Ampliar el límite de salida de herramientas MCP
MAX_MCP_OUTPUT_TOKENS=50000 claude
ConsejoSi un servidor stdio escribe logs por stdout en lugar de stderr, rompe el protocolo y la conexión se cae sin un error claro. Revisa los issues del paquete: suele haber un flag para silenciarlo.
Error comúnSolo instala servidores MCP de fuentes en las que confíes. Un servidor que lee contenido externo (webs, issues, emails) puede introducir instrucciones maliciosas (prompt injection) en la sesión.
Resultado

Ahora tienes Claude Code conectado a servidores MCP remotos y locales: sabes usar claude mcp add con transporte HTTP y stdio, elegir entre scope local, project y user, compartir la configuración con tu equipo mediante un .mcp.json sin secretos y autenticarte con OAuth desde /mcp. También tienes un método de diagnóstico para cuando un servidor no conecta, que es donde se pierde más tiempo en la práctica. Con esto, Claude Code deja de limitarse a tu código y puede consultar errores en producción, navegar tu web o leer tu base de datos dentro del mismo flujo. Si quieres ir más allá de consumir servidores y empezar a construir los tuyos, el siguiente paso natural es dar el salto a construir tus propias integraciones MCP y orquestarlas en agentes.

PRÓXIMOS PASOS
TÉRMINOS DE ESTE TUTORIAL
TEMA
MÁS DE CLAUDE CODE