Cómo configurar MCP en Claude Code CLI: guía práctica 2026

Claude Code te da un agente potente en la terminal, pero por defecto solo ve lo que hay en tu sistema de archivos y lo que puede hacer con bash. Si quieres que también acceda a GitHub issues, tu base de datos de staging, Notion, Linear, Figma o cualquier otra herramienta — necesitas MCP.

MCP (Model Context Protocol) es el estándar abierto que creó Anthropic en 2024 para que cualquier LLM pueda hablar con cualquier herramienta usando un único protocolo. En Claude Code CLI, añadir un MCP server es un comando. Saber qué comando usar, cómo funciona cada transport, y qué hacer cuando algo falla — es el objetivo de esta guía.

Es parte del cluster sobre cómo funciona Claude Code por dentro. Si quieres saber qué es un cliente MCP en general, mira primero nuestra guía.

El comando principal: claude mcp add

El comando que vas a usar el 90% del tiempo es:

claude mcp add <nombre> [-- <comando> <args...>]

• <nombre>: identificador que verás en Claude Code para referirte a este server.

• <comando>: binario o script que lanza el server.

• <args...>: argumentos del comando.

Ejemplo mínimo, añadir un server MCP local:

claude mcp add github -- npx @modelcontextprotocol/server-github

Desde Claude Code v2.1.1 en adelante, la forma canónica para configuraciones complejas es claude mcp add-json:

claude mcp add-json github '{
  "type": "stdio",
  "command": "npx",
  "args": ["@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_TOKEN": "ghp_xxxxx"
  }
}'

La documentación oficial está en code.claude.com/docs/en/mcp.

Los tres transports

MCP tiene tres formas de conectar Claude Code con el server, en orden de cuándo usar cada uno:

1. stdio (lo más común)

El server corre como proceso hijo de Claude Code. Se comunican por stdin/stdout con mensajes JSON-RPC. Es la forma por defecto.

claude mcp add filesystem -- npx @modelcontextprotocol/server-filesystem /tmp

Cuándo: la mayoría de MCP servers que se instalan localmente (filesystem, git, shell, SQLite, GitHub via npx).

Pros: simple, sin red, sin puertos.
Contras: no se puede compartir entre sesiones; cada instancia de Claude Code arranca su propio proceso.

2. HTTP

El server corre como servicio HTTP, normalmente en localhost o en un endpoint remoto. Claude Code envía peticiones HTTP POST con mensajes MCP.

claude mcp add my-server --transport http http://localhost:8080/mcp

Para servers remotos con OAuth:

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

Cuándo: server que corre como servicio persistente (puede atender a varias apps), o servers remotos gestionados por un tercero (Notion, Linear, servicios SaaS que publican endpoints MCP).

Pros: un server sirve a varios clientes. Ideal en equipo.
Contras: necesita autenticación (OAuth típicamente). Más setup.

3. SSE (Server-Sent Events)

Variante HTTP con streaming push desde el server. Uso más nicho: para servers que emiten eventos proactivamente (notificaciones, watchers).

claude mcp add my-watcher --transport sse http://localhost:8080/mcp

Cuándo: pocos casos. La mayoría de servers MCP funcionan con stdio o HTTP normal.

Scopes: dónde se guarda la config

Cuando añades un server, Claude Code guarda la config en uno de tres scopes:

Local (por defecto)

claude mcp add --scope local <nombre> ...

• Se guarda en ~/.claude.json (macOS/Linux) o equivalente en Windows.

• Solo disponible para ti, en este ordenador.

• Uso: tokens personales, MCP servers que solo necesitas tú.

Project

claude mcp add --scope project <nombre> ...

• Se guarda en .mcp.json dentro del repo.

• Se commitea al repo → todo el equipo lo usa al clonar.

• Uso: servers que el equipo comparte (GitHub del proyecto, base de datos de staging, Linear del producto).

Cuando abres Claude Code en un proyecto con .mcp.json, te pregunta si confías — y permite o deniega la carga. Es su mecanismo de seguridad para evitar que clonar un repo te instale MCP servers sin consentimiento.

User

claude mcp add --scope user <nombre> ...

• Se guarda en tu config global, disponible en cualquier proyecto.

• Uso: herramientas personales (tu Notion, tu Gmail) que quieres en todas partes.

Regla general: project scope para lo compartido por equipo, user scope para lo personal omnipresente, local scope para lo específico de una máquina.

Ejemplos reales paso a paso

Añadir GitHub como MCP server

# 1. Genera un Personal Access Token en github.com/settings/tokens
#    con scopes: repo, read:org (según lo que necesites).

# 2. Añade el server
claude mcp add github \
  --scope user \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxx \
  -- npx @modelcontextprotocol/server-github

# 3. Verifica
claude mcp list

Desde Claude Code ya puedes pedir: "¿qué PRs abiertos tengo en el repo X?" y el agente llamará al MCP server.

Añadir un server remoto con OAuth (Notion)

# 1. Añade el server (triggerea OAuth en el primer uso)
claude mcp add notion --transport http --callback-port 8080 https://mcp.notion.com/mcp

# 2. Al primer uso, Claude Code abre el navegador.
#    Autorizas Notion en el flujo OAuth.
#    El callback llega a localhost:8080 y guarda el token.

# 3. Lista para usar en cualquier sesión.

Nota: --callback-port es útil si tu firewall solo permite puertos específicos o si tu registro OAuth está preconfigurado con un redirect URI concreto.

Añadir un server propio (Python local)

Supón que has escrito un MCP server en Python que expone tu API interna:

claude mcp add internal-api \
  --scope project \
  --env API_TOKEN=secretxxx \
  -- python /ruta/a/server.py

Se guarda en .mcp.json del proyecto. Cualquier compañero que clone el repo puede usar el mismo server (aportando su API_TOKEN personal).

Importar todos los servers desde Claude Desktop

Si ya usas Claude Desktop con varios MCP servers configurados:

claude mcp add-from-claude-desktop

Te lista los servers detectados y te deja elegir cuáles importar a Claude Code CLI. Útil para no reconfigurarlos.

Gestión día a día

Listar servers configurados

claude mcp list

Muestra todos los servers con nombre, transport, scope y estado.

Ver detalle de un server

claude mcp get <nombre>

Imprime la configuración completa (comando, args, env, etc.) para debug.

Eliminar un server

claude mcp remove <nombre>

También puedes pasar --scope project si tu server vive en el .mcp.json del repo.

Actualizar un server

No hay comando update directo. Puedes remove y add de nuevo, o editar la config manualmente.

Archivos de configuración: dónde viven

Si quieres editar la config a mano (útil para automatizar con scripts o migrar config):

• Local/user scope: ~/.claude.json (macOS/Linux) o %USERPROFILE%\.claude.json (Windows).

• Project scope: .mcp.json en la raíz del repo.

Formato típico de .mcp.json:

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Soporta interpolación ${VAR} para que no tengas que commitear secretos.

Debugging: qué hacer cuando no funciona

"Server added but no tools appear"

El server arrancó pero Claude Code no ve tools. Posibles causas:

• Handshake MCP falló: el server no respondió al initialize. Mira logs.

• Lista de tools vacía: el server responde OK pero no expone ninguna tool. Revisa el código del server.

Para ver logs:

# Lanza Claude Code con debug
claude --debug

# O activa verbosity en settings.json
{ "mcp": { "logLevel": "debug" } }

"Command not found" al arrancar

Si configuraste command: "npx", asegúrate de que npx está en tu PATH cuando Claude Code arranca. En shells no-interactivos el PATH puede ser más corto.

Solución: usa ruta absoluta.

claude mcp add github -- /Users/yo/.volta/bin/npx @modelcontextprotocol/server-github

"Authentication failed" en servers HTTP

Si el OAuth falla, revisa:

• El --callback-port coincide con el redirect URI registrado en el proveedor.

• La URL del server es la correcta (con /mcp al final, normalmente).

• El firewall permite la redirección a localhost:<port>.

"Server too slow"

Un MCP server lento ralentiza el agente entero. Un server HTTP con latencia 500ms+ penaliza cada tool call. Si es local, revisa qué hace el server; si es remoto, considera si hay una versión local.

"Claude Code pregunta siempre si confío en el .mcp.json"

Es el mecanismo de seguridad para repos nuevos. Tras aceptar la primera vez, se recuerda. Si te lo pregunta repetidamente, limpia caché con:

claude mcp reset-project-choices

Patrones útiles

Secretos en variables de entorno, no en JSON

Commitear un .mcp.json con tokens inline es un desastre de seguridad. Usa interpolación:

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Y cada dev exporta GITHUB_TOKEN en su shell o .env local (gitignored).

Servers dev-only vs prod-shared

Si en tu equipo unos tienen MCP server de "staging DB" y otros no, no lo metas en .mcp.json del proyecto. Usa scope user para los individuales, scope project solo para lo verdaderamente compartido.

MCP para infraestructura crítica: piensa Platform

Si tu equipo necesita control centralizado de qué MCP servers usa cada miembro, versionado, auditoría de calls y gestión de credenciales fuera de cada máquina — Levante Platform ofrece MCP Control centralizado bajo infraestructura europea.

Ecosistema de MCP servers

A abril de 2026, el catálogo de MCP servers oficiales y comunitarios es muy amplio. Algunos destacados:

• Oficiales de Anthropic: filesystem, git, memory, time, fetch, brave-search.

• GitHub, GitLab, Notion, Linear: integraciones de los propios proveedores.

• Bases de datos: PostgreSQL, SQLite, MongoDB.

• Productividad: Slack, Gmail, Calendar, Drive.

• Observabilidad: Grafana, Datadog, Sentry.

• Levante MCP Store: catálogo curado con paquetes listos para instalar.

Nuevo MCP server cada semana. El directorio oficial lo mantiene modelcontextprotocol.io.

Conclusión

Configurar MCP en Claude Code CLI es simple en cuanto entiendes el modelo: claude mcp add + elegir scope + elegir transport. Los gotchas están en PATH, secretos y OAuth callbacks, pero son problemas que se resuelven una vez y no vuelven.

Si estás arrancando con MCP, los servers que más rápido dan valor son filesystem (ya lo tienes de base), GitHub (issues y PRs) y tu base de datos de staging (para queries asistidas). A partir de ahí, escalas según cada equipo.

Para profundizar:

• Cómo funciona Claude Code por dentro — pillar del cluster.

• Qué es un cliente MCP — concepto base.

• Hooks de Claude Code — el otro mecanismo de extensión.

• Subagentes de Claude Code — para workflows compuestos.

Fuentes verificadas

• Documentación oficial MCP en Claude Code: code.claude.com/docs/en/mcp.

• Comando add-json disponible desde Claude Code v2.1.1: confirmado en changelog.

• Especificación oficial MCP: modelcontextprotocol.io.

• Datos verificados el 23 de abril de 2026.