Cómo conectar un servidor MCP a Claude Code (tutorial)

Para conectar un servidor MCP a Claude Code se usa un solo comando: claude mcp add, con el nombre del servidor y su URL (si es remoto) o el comando que lo arranca (si corre en tu máquina). Después compruebas la conexión con claude mcp list o con /mcp dentro de una sesión, y Claude ya puede usar las herramientas de ese servidor. En este tutorial conectamos un servidor remoto y uno local, explicamos los alcances y cerramos con las reglas de seguridad que aplicamos en proyectos reales.

Todos los comandos salen de la documentación oficial de Claude Code y los probamos el 4 de noviembre de 2026 con la versión 2.1.318 en macOS. Si en tu empresa quieres conectar la IA con sistemas propios, este es el mismo mecanismo que usamos en nuestros proyectos de inteligencia artificial para empresas.

Qué es un servidor MCP

MCP (Model Context Protocol) es un protocolo abierto que estandariza cómo una aplicación de IA se conecta con datos y herramientas externas. Un servidor MCP es un programa que expone esas herramientas: leer archivos, consultar una base de datos, abrir un ticket, buscar en una documentación. Claude Code actúa como cliente: se conecta al servidor, ve qué herramientas ofrece y las usa cuando la tarea lo pide, con tu permiso.

La versión más reciente de la especificación es la 2026-07-28, que hace el protocolo sin estado (ya no hay sesión a nivel de protocolo). Para conectar un servidor no necesitas saber nada de eso: el comando es el mismo.

Hay dos formas de conectarse:

• HTTP: el servidor está en internet y te conectas por URL. Es la opción recomendada por la documentación cuando existe. El transporte SSE está obsoleto.
• stdio: el servidor es un programa que Claude Code arranca en tu equipo y con el que habla por la entrada y salida estándar.

Requisitos

• Claude Code instalado. La página de instalación indica macOS 13 o superior, Windows 10 1809 o superior, Ubuntu 20.04 o superior, Debian 10 o superior, o Alpine 3.19 o superior.
• Una cuenta con acceso a Claude Code: Pro, Max, Ultra, Team, Enterprise o Console. El plan gratuito de claude.ai no lo incluye.
• Para servidores locales que se distribuyen por npm, Node.js; para los que se distribuyen en Python, uvx. Cada servidor indica en su README qué versión necesita.

Comprueba tu versión antes de empezar:

claude --version

Cómo conectar un servidor MCP a Claude Code paso a paso

1. Conecta un servidor remoto (HTTP)

   La documentación de Claude Code ofrece su propio servidor MCP, sin autenticación, pensado como primer servidor de prueba. Desde la carpeta de tu proyecto:

   claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

   El formato general es claude mcp add --transport http <nombre> <url>. Si el servidor pide una cabecera de autorización, se añade con --header "Authorization: Bearer <token>"; si usa OAuth, te autenticas después desde /mcp.

2. Conecta un servidor local (stdio)

   Para un servidor que corre en tu equipo, todo lo que va después de -- es el comando que lo arranca. Este ejemplo usa el servidor de referencia Filesystem, que solo puede leer y escribir dentro de la carpeta que le indiques:

   claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ./docs

   Si el servidor necesita variables de entorno (por ejemplo, una clave de API), usa --env CLAVE=valor antes del nombre. El README del servidor Filesystem pide Node.js 24 o superior cuando se ejecuta con npx; en nuestra prueba funcionó también con Node.js 22, pero sigue la cifra oficial. Ese README recomienda además, en Windows, lanzar npx con cmd /c.

3. Verifica la conexión

   claude mcp list
   claude mcp get claude-code-docs

   claude mcp list comprueba cada servidor y muestra su estado: ✔ Connected si responde, ✘ Failed to connect si no arrancó y ! Needs authentication si falta iniciar sesión. Un servidor que se descarga con npx puede fallar la primera vez mientras se instala; vuelve a probar.

   Dentro de una sesión de Claude Code, el comando /mcp muestra los mismos servidores, permite autenticarte en los que usan OAuth y desactivar uno sin borrarlo.

4. Úsalo en una tarea

   Abre Claude Code y pide algo que necesite el servidor, por ejemplo: «Busca en la documentación de Claude Code cómo se comparten servidores MCP con el equipo». La primera vez que Claude quiera usar una herramienta del servidor te pedirá permiso.

5. Quítalo cuando no lo necesites

   claude mcp remove claude-code-docs

   Cada servidor conectado carga los nombres de sus herramientas y sus instrucciones al iniciar todas tus sesiones; las definiciones completas de las herramientas se cargan solo cuando hacen falta. Aun así, conecta solo los que uses.

Alcances: local, proyecto o usuario

La opción --scope decide dónde se guarda la configuración y quién la ve:

Para compartir un servidor con tu equipo, usa el alcance project y versiona el archivo .mcp.json:

claude mcp add --transport http claude-code-docs --scope project https://code.claude.com/docs/mcp

Por seguridad, Claude Code pide aprobación en sesiones interactivas antes de usar un servidor que llega desde un .mcp.json. Hasta que lo apruebes, claude mcp get lo muestra como pendiente de aprobación. Si necesitas volver a decidir, claude mcp reset-project-choices borra esas elecciones.

En .mcp.json no escribas secretos: la documentación admite variables de entorno con ${VARIABLE} o ${VARIABLE:-valor_por_defecto} en el comando, los argumentos, la URL y las cabeceras.

{
  "mcpServers": {
    "api-interna": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

Errores comunes

• El nombre va después de --env. Si escribes claude mcp add --env CLAVE=valor mi-servidor -- …, la CLI puede leer el nombre como otro valor de --env. Pon otra opción entre ambos, por ejemplo --transport stdio.
• El servidor tarda en arrancar. Sube el tiempo de espera con la variable MCP_TIMEOUT (en milisegundos), por ejemplo MCP_TIMEOUT=10000 claude.
• Respuestas demasiado largas. Claude Code avisa cuando una herramienta MCP devuelve más de 10.000 tokens y limita la salida a 25.000 por defecto; se ajusta con MAX_MCP_OUTPUT_TOKENS.
• No aparece un servidor del equipo. Revisa que lo aprobaste: los servidores de .mcp.json no se conectan hasta entonces.

Seguridad: qué permisos estás dando

Un servidor MCP ejecuta acciones con los permisos que le das. La documentación de seguridad de Claude Code recomienda escribir tus propios servidores o usar los de proveedores de confianza, y aclara que Anthropic no audita la seguridad de los servidores MCP. La guía de MCP añade que los servidores que traen contenido externo exponen a riesgos de inyección de instrucciones (prompt injection).

Las reglas que aplicamos:

• Conecta solo servidores de proveedores que conoces o código que revisaste.
• Da el mínimo acceso: una carpeta concreta, un usuario de base de datos de solo lectura, un token con permisos acotados.
• No pongas secretos en .mcp.json; usa variables de entorno.
• Revisa los permisos de herramientas en Claude Code antes de aprobar acciones que escriben o borran.
• Para sistemas internos (ERP, facturación, CRM), un servidor MCP propio te da control sobre qué datos y acciones expone, con registro de cada llamada.

Preguntas frecuentes

¿Cuál es el comando para añadir un servidor MCP a Claude Code? claude mcp add. Para un servidor remoto: claude mcp add --transport http <nombre> <url>. Para uno local: claude mcp add <nombre> -- <comando> [argumentos].

¿Dónde guarda Claude Code la configuración de MCP? En ~/.claude.json para los alcances local y user, y en .mcp.json en la raíz del proyecto para el alcance project.

¿Funciona igual en Windows? Sí. La documentación indica que claude mcp add funciona igual en PowerShell y en el Símbolo del sistema. Algunos servidores locales piden lanzar npx con cmd /c; revisa su README.

¿Puedo conectar Claude Code a los sistemas de mi empresa? Sí, con un servidor MCP que exponga solo lo que necesitas de esos sistemas. Es un proyecto de integración: definimos qué datos y acciones se publican, con qué permisos y cómo se auditan.