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.
- 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)
- 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
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.
# 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 listAñ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.
# 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 listAñ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.
# 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 playwrightElegir 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.
# 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"]}'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.
# 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-desktopDiagnosticar 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.
# 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 claudeAhora 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.