Servidores MCP

Qué es MCP y por qué conectar herramientas externas

El Model Context Protocol (MCP) es un estándar abierto que permite a Claude Code comunicarse con herramientas, bases de datos, APIs y servicios externos. Mientras que las herramientas integradas de Claude Code (Read, Edit, Bash, Grep) operan sobre el sistema de archivos local y la terminal, los servidores MCP amplían ese alcance hacia cualquier servicio que implemente el protocolo.

Con servidores MCP conectados, Claude Code puede realizar operaciones como:

• Consultar bases de datos directamente: "Busca los usuarios que no han iniciado sesión en los últimos 90 días"
• Gestionar repositorios en GitHub: "Revisa el PR #456 y sugiere mejoras"
• Monitorizar errores en Sentry: "Muestra los errores más frecuentes en las últimas 24 horas"
• Interactuar con APIs de terceros: "Crea un borrador en Gmail invitando a estos 10 usuarios"

MCP no reemplaza las herramientas integradas de Claude Code. Las complementa con capacidades que van más allá del sistema de archivos y la terminal local. Las herramientas MCP aparecen con el prefijo mcp__ seguido del nombre del servidor y la herramienta, como mcp__github__create_issue.

Tipos de transporte

Los servidores MCP se conectan a Claude Code mediante tres tipos de transporte, cada uno adecuado para un escenario distinto:

flowchart LR
    A["Claude Code"] --> B["HTTP<br>(remoto, recomendado)"]
    A --> C["SSE<br>(remoto, deprecado)"]
    A --> D["stdio<br>(local)"]
    B --> E["APIs cloud<br>GitHub, Sentry, Notion"]
    C --> F["Servicios legacy"]
    D --> G["Procesos locales<br>bases de datos, scripts"]

Servidores HTTP remotos

El transporte HTTP es la opción recomendada para servicios en la nube. Se conecta a una URL remota y soporta autenticación OAuth 2.0 de forma nativa.

claude mcp add --transport http notion https://mcp.notion.com/mcp

Para servicios que requieren autenticación por token:

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer tu-token"

Servidores SSE (Server-Sent Events)

El transporte SSE es una alternativa que algunos servicios todavía soportan, aunque se considera deprecado en favor de HTTP:

claude mcp add --transport sse asana https://mcp.asana.com/sse

Servidores stdio locales

Los servidores stdio se ejecutan como procesos locales en la máquina. Son la opción adecuada cuando se necesita acceso directo al sistema, por ejemplo para conectar con una base de datos local o ejecutar un script personalizado:

claude mcp add --transport stdio db \
  -- npx -y @bytebase/dbhub --dsn "postgresql://localhost:5432/mydb"

En Windows nativo (sin WSL), los servidores stdio que usan npx requieren el wrapper cmd /c para funcionar correctamente: claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package.

Orden de las opciones

Un detalle importante al usar claude mcp add: todas las opciones (--transport, --env, --scope, --header) deben ir antes del nombre del servidor. El separador -- (doble guion) separa el nombre del servidor de los argumentos que se pasan al proceso MCP:

claude mcp add --transport stdio --env API_KEY=abc123 myserver -- python server.py --port 8080

Ámbitos de instalación

Cada servidor MCP se almacena en un ámbito que determina su visibilidad y quién puede usarlo:

| Ámbito | Flag | Almacenamiento | Compartido | |---|---|---|---| | Local (por defecto) | --scope local | ~/.claude.json bajo la ruta del proyecto | No | | Proyecto | --scope project | .mcp.json en la raíz del proyecto | Si, via Git | | Usuario | --scope user | ~/.claude.json global | No, solo tu máquina |

El ámbito proyecto resulta especialmente útil para equipos, ya que el archivo .mcp.json se puede subir al repositorio y todos los miembros del equipo comparten la misma configuración de servidores:

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

El archivo .mcp.json generado tiene esta estructura:

{
  "mcpServers": {
    "paypal": {
      "type": "http",
      "url": "https://mcp.paypal.com/mcp"
    }
  }
}

Cuando existen servidores con el mismo nombre en distintos ámbitos, el de mayor prioridad prevalece: local > proyecto > usuario.

Variables de entorno en .mcp.json

El archivo .mcp.json soporta expansión de variables de entorno, lo que permite compartir configuraciones sin exponer credenciales en el repositorio:

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

La sintaxis ${VAR:-default} aplica un valor por defecto si la variable no está definida. Las variables se expanden en los campos headers, url, env, args y command.

Gestión de servidores

Una vez configurados los servidores, Claude Code proporciona comandos para administrarlos:

# Listar todos los servidores configurados
claude mcp list

# Ver detalles de un servidor concreto
claude mcp get github

# Eliminar un servidor
claude mcp remove github

Dentro de una sesión interactiva, el comando /mcp muestra el estado de todos los servidores conectados, permite autenticar servidores que requieren OAuth y gestionar las conexiones activas.

Autenticación con OAuth 2.0

Muchos servidores MCP en la nube requieren autenticación. Claude Code soporta flujo OAuth 2.0 para conexiones seguras:

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

Tras añadir el servidor, se completa la autenticación dentro de Claude Code:

/mcp

Claude Code abre el navegador para completar el flujo de login. Los tokens se almacenan de forma segura y se refrescan automáticamente.

Para servidores que requieren credenciales pre-configuradas (cuando no soportan registro dinámico de clientes OAuth), se proporcionan las credenciales al añadir el servidor:

claude mcp add --transport http \
  --client-id tu-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

Ejemplos prácticos

Conectar a GitHub

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

Tras autenticar con /mcp, Claude Code puede gestionar issues, revisar PRs y trabajar directamente con repositorios.

Consultar una base de datos PostgreSQL

claude mcp add --transport stdio db \
  -- npx -y @bytebase/dbhub --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

Claude Code puede entonces responder preguntas como "Muéstrame el esquema de la tabla orders" o "Calcula los ingresos totales de este mes".

Importar servidores desde Claude Desktop

Si ya tienes servidores configurados en Claude Desktop, se pueden importar directamente:

claude mcp add-from-claude-desktop

Recursos MCP

Los servidores MCP también pueden exponer recursos que se referencian mediante menciones con @, de forma similar a cómo se referencian archivos en el contexto:

> Analiza @github:issue://123 y sugiere una corrección
> Compara @postgres:schema://users con @docs:file://database/user-model

Los recursos se autocompletan al escribir @ en el prompt y se incluyen automáticamente como adjuntos en el contexto.

MCP Tool Search

Cuando se configuran muchos servidores MCP, las definiciones de herramientas pueden consumir una parte significativa de la ventana de contexto. MCP Tool Search resuelve esto cargando herramientas bajo demanda en lugar de precargar todas al inicio.

Tool Search se activa automáticamente cuando las definiciones de herramientas MCP superan el 10% de la ventana de contexto. Se puede ajustar el umbral o desactivar esta funcionalidad mediante la variable de entorno ENABLE_TOOL_SEARCH:

| Valor | Comportamiento | |---|---| | auto (por defecto) | Se activa cuando las herramientas MCP superan el 10% del contexto | | auto:5 | Se activa con un umbral personalizado del 5% | | true | Siempre activo | | false | Desactivado, todas las herramientas se cargan al inicio |

ENABLE_TOOL_SEARCH=auto:5 claude

Claude Code también puede actuar como servidor MCP para que otras aplicaciones se conecten a él. El comando claude mcp serve inicia Claude Code como servidor stdio, exponiendo sus herramientas integradas (Read, Edit, Bash) a cualquier cliente MCP compatible.