Cómo conectar servidores MCP a Claude Code paso a paso

El Model Context Protocol (MCP) es un estándar abierto para conectar herramientas de IA con fuentes de datos y servicios externos. Con él, Claude Code puede ir más allá de sus herramientas integradas: consultar tu gestor de incidencias, leer un servicio de errores como Sentry, controlar un navegador o usar tus propias herramientas.

En este tutorial conectamos tres tipos de servidores, que son las tres formas más comunes en las que te vas a encontrar MCP. Necesitas Claude Code instalado y una terminal abierta en cualquier carpeta.

1. Un servidor remoto sin autenticación

Vamos a conectar el servidor MCP de la documentación de Claude Code, que permite buscar en la documentación. Ejecuta esto en tu terminal, no dentro de una sesión de claude:

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

Qué significa cada parte:

• claude mcp add: registra un servidor.
• --transport http: el servidor está alojado en una URL.
• claude-code-docs: un nombre que tú eliges. Claude lo usa para etiquetar sus herramientas.
• La URL del servidor.

Verifica que quedó conectado:

claude mcp list

Debe aparecer con ✔ Connected. Ahora inicia claude y pídele algo que use el servidor, mencionándolo por su nombre:

Usa el servidor claude-code-docs para buscar qué hace MCP_TIMEOUT

La primera vez que Claude llame al servidor te pedirá permiso. Fíjate que la llamada a la herramienta aparece etiquetada con el nombre del servidor: así confirmas que la respuesta vino de MCP y no del conocimiento del modelo.

2. Un servidor local (stdio)

Un servidor local es un programa que Claude Code arranca en tu máquina. Sirve para herramientas que necesitan acceso a recursos locales. Un buen ejemplo es Playwright, que le da a Claude un navegador que puede abrir, leer y controlar. Requiere Node.js 18 o superior:

claude mcp add playwright -- npx -y @playwright/mcp@latest

Nota la diferencia: no hay --transport (stdio es el valor por defecto) y todo lo que va después de -- es el comando que arranca el servidor. Si olvidas el --, el servidor no funcionará.

La primera revisión con claude mcp list puede mostrar ✘ Failed to connect mientras npx descarga el paquete. Espera un momento y vuelve a correrlo.

Pruébalo:

Usa playwright para abrir https://example.com y dime el título de la página

Un ejemplo útil en desarrollo: apuntarlo a tu servidor local para comprobar que una página sigue viéndose bien después de un cambio.

3. Un servidor remoto con inicio de sesión (OAuth)

Servicios como Sentry, Linear o Notion alojan su servidor MCP detrás de OAuth. Se agrega igual que el primero:

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

Al principio claude mcp list mostrará ! Needs authentication, y es lo esperado. Inicia una sesión, escribe /mcp, elige sentry, selecciona Authenticate y aprueba la conexión en el navegador.

Los servidores que usan un token estático en lugar de OAuth lo reciben al agregarlos con --header "Authorization: Bearer <token>".

Scopes: dónde se guarda la configuración

Por defecto un servidor queda en alcance local: solo para ti y solo en ese proyecto. Puedes cambiarlo con --scope:

Por ejemplo, para tenerlo en todos tus proyectos:

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

Para compartirlo con tu equipo, usa --scope project y haz commit del .mcp.json resultante. Quienes lo clonen verán un aviso para aprobar el servidor antes de que se conecte, para que un repositorio no pueda ejecutar procesos en tu máquina sin tu consentimiento.

También puedes escribir el archivo a mano:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Claude Code lee .mcp.json al iniciar la sesión, así que reinicia después de editarlo.

Problemas frecuentes

• Failed to connect: ejecuta claude mcp get <nombre> para ver el detalle. Para servidores HTTP, prueba la URL con curl -I. Para servidores stdio, corre el comando directamente en la terminal y lee el error.

• Se agota el tiempo al iniciar: el límite por defecto es de 30 segundos. Aumenta con la variable MCP_TIMEOUT en milisegundos:

  MCP_TIMEOUT=60000 claude

• Conecta pero no aparecen herramientas: revisa en /mcp la lista del servidor. Suele faltar una variable de entorno, como una API key; pásala con --env CLAVE=valor.

• Server already exists: ya agregaste un servidor con ese nombre en ese scope. Elimínalo con claude mcp remove <nombre>.

Recomendaciones

• No agregues de más. Cada servidor conectado ocupa espacio en la ventana de contexto de Claude porque sus herramientas se cargan en cada sesión. Elimina los que no uses con claude mcp remove.
• Desconfía de servidores que no conoces. Un servidor MCP ejecuta código o recibe tus datos: agrega solo los de proveedores confiables.
• Un ejemplo real para desarrolladores de Shopify: el Dev MCP server de Shopify (shopify-dev-mcp) es un servidor local que no requiere autenticación y se agrega igual que el de Playwright. Te lo explico en el artículo del Shopify AI Toolkit.

Conclusión

Agregar un servidor MCP es un solo comando, y a partir de ahí Claude Code puede trabajar con las herramientas que ya usas. Lo esencial es recordar los tres formatos (HTTP, stdio y OAuth), el scope y comprobar siempre la conexión con claude mcp list.

Fuentes

• Connect to MCP servers (documentación oficial de Claude Code)