Workbranch › Guías

Cómo conectar servidores MCP a Claude Code

Los servidores MCP dan a Claude Code acceso a herramientas que están fuera de tu código, como un gestor de incidencias, una base de datos o una herramienta de diseño. Esta guía muestra los comandos para añadir uno, dónde se guarda la configuración, cómo iniciar sesión y cómo saber si funciona.

Actualizado 30 de octubre de 2026

Los comandos de abajo siguen la documentación de Claude Code de Anthropic en octubre de 2026. Los comandos claude mcp se ejecutan en tu terminal normal, no dentro de una sesión de Claude Code.

Añade un servidor remoto (lo más habitual)

Un servicio alojado te da una dirección web para su servidor MCP, que encontrarás en sus propias instrucciones de configuración. Anthropic recomienda para estos el transporte HTTP.

1. En la terminal, entra con cd en el proyecto en el que lo vas a usar.
2. Ejecuta claude mcp add --transport http notion https://mcp.notion.com/mcp, cambiando el nombre y la dirección por los tuyos. El nombre es lo que verás en las listas y en /mcp.
3. Si el servicio usa una clave de API en lugar de un inicio de sesión, pásala como cabecera: --header "Authorization: Bearer your-token".

Los servidores más antiguos pueden ofrecer solo SSE, que está obsoleto. Las versiones recientes de Claude Code prueban primero HTTP y recurren a SSE por su cuenta; en versiones antiguas usa --transport sse.

Añade un servidor local

Un servidor local (stdio) es un programa que se ejecuta en tu ordenador y que a menudo se inicia con npx.

1. Escribe primero las opciones de Claude, luego -- y después el comando propio del servidor: claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server.
2. Claude Code pasa todo lo que va después de -- directamente al programa del servidor. Sin el separador, las opciones pensadas para el servidor (como -y) se leen como opciones de Claude Code.
3. Cuando uses --env, pon otra opción entre ella y el nombre del servidor, como en el ejemplo; si no, el nombre se lee como otra variable.

Elige un ámbito

Elige user para las herramientas que quieres en todas partes, como tu app de notas, y project para las que todo el equipo necesita en un repositorio. Si un servidor está definido en varios sitios, Claude Code se conecta una sola vez, con este orden de prioridad: local, project, user, después los servidores de plugins y por último los conectores de claude.ai. Los tres ámbitos se comparan por nombre; los servidores de plugins y los conectores cuentan como duplicados cuando apuntan a la misma dirección o al mismo comando. La entrada ganadora se usa completa; los campos no se combinan.

No pongas secretos directamente en un .mcp.json compartido. Admite variables como ${API_KEY} o ${API_BASE_URL:-https://api.example.com}, que cada persona define en su propio entorno.

Inicia sesión en un servidor que necesita cuenta

1. Inicia Claude Code con claude.
2. Escribe /mcp. El panel muestra los servidores en los que aún tienes que iniciar sesión.
3. Selecciona el servidor y sigue el inicio de sesión en el navegador. El token se guarda en tu ordenador y se renueva automáticamente.
4. Como alternativa, ejecuta en tu shell claude mcp login name. Cierra la sesión con claude mcp logout name.

Algunos servicios exigen que primero registres una app con ellos. En ese caso, añade el servidor con --client-id, --client-secret (se te pedirá que lo escribas) y, si su configuración pide una redirección fija, --callback-port.

Comprueba que funciona

• claude mcp list muestra cada servidor con su estado: Connected (conectado), Needs authentication (requiere autenticación), Failed to connect (no se pudo conectar), Pending approval (pendiente de aprobación) o Disabled for this project (desactivado en este proyecto).
• claude mcp get name muestra los detalles de un servidor, incluido el error HTTP cuando falla.
• Dentro de una sesión, /mcp muestra el mismo estado y te permite volver a conectar.
• Por último, pídele a Claude algo que solo ese servidor pueda hacer, como «list my open Linear issues» (muestra mis incidencias abiertas de Linear).

Quita un servidor con claude mcp remove name.

Conviene saber

• Los servidores del proyecto preguntan antes: la primera vez que una sesión encuentra servidores en el .mcp.json de un repositorio, Claude Code te pide que los apruebes. Deshaz tus elecciones con claude mcp reset-project-choices. Aprueba solo servidores de repositorios en los que confíes.
• Los permisos se siguen aplicando: cada llamada a una herramienta MCP puede pedirte confirmación como cualquier otra herramienta; consulta cómo gestionar los permisos en Claude Code.
• Resultados grandes: Claude Code avisa cuando una herramienta devuelve más de 10.000 tokens y limita la salida a 25.000 por defecto. Súbelo con la variable de entorno MAX_MCP_OUTPUT_TOKENS.
• Plugins: algunos plugins traen sus propios servidores MCP, así que instalar un plugin puede ser un camino más fácil; consulta cómo instalar plugins en Claude Code.

Si no funciona

• Failed to connect: ejecuta claude mcp get name para ver el error, revisa la URL y luego ejecuta /mcp reconnect all en una sesión (versiones recientes) para reintentarlo.
• Un servidor local lento agota el tiempo al arrancar: inicia Claude Code con un límite más largo, como MCP_TIMEOUT=10000 claude (en milisegundos).
• «has a url but no type»: a una entrada JSON de un servidor remoto le falta "type": "http".
• Se rechaza la clave de API: Claude Code avisa si hay espacios o saltos de línea al principio o al final de una cabecera. Vuelve a añadir el servidor con un token pegado limpiamente.

Fuentes

• Claude Code user FAQ (Centro de ayuda de Claude, consultado el 30 de octubre de 2026)
• Connect Claude Code to tools via MCP (Claude Code Docs, consultado el 30 de octubre de 2026)

Preguntas frecuentes