Claude Code — MCP

Respuesta corta a “cómo conecto un servidor MCP a Claude Code”: ejecuta claude mcp add desde tu shell y luego gestiónalo dentro de la sesión con /mcp.

Añadir un servidor

# Servidor HTTP remoto (el transporte recomendado)
claude mcp add --transport http <nombre> <url>
claude mcp add --transport http notion https://mcp.notion.com/mcp

# ...con una cabecera de autenticación
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer tu-token"

# Servidor SSE remoto
claude mcp add --transport sse <nombre> <url>

# Servidor stdio local — todo lo que va después de -- es el comando del servidor
claude mcp add <nombre> -- <comando> [args...]
claude mcp add --env AIRTABLE_API_KEY=TU_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

# Desde una definición JSON en crudo (así se añaden también los servidores WebSocket: "type": "ws")
claude mcp add-json <nombre> '<json>'

Notas:

• --transport acepta http, sse y stdio — no ws. Los servidores WebSocket entran vía .mcp.json o con add-json usando "type": "ws". En las configuraciones JSON, streamable-http es un alias válido de http.
• Una entrada JSON con url pero sin type es un error (se trata como stdio y se ignora con un aviso).
• claude mcp add guarda la configuración sin validar las credenciales — comprueba después con claude mcp list.

Ámbitos

Ámbito	Se guarda en	Visibilidad
local (por defecto)	~/.claude.json (por proyecto)	Sólo tú, sólo en este proyecto
project	.mcp.json en la raíz del proyecto	Se sube a git y se comparte con el equipo; requiere aprobación interactiva (se omite en sesiones con -p, del SDK o en la nube)
user	~/.claude.json	Sólo tú, en todos tus proyectos

Precedencia con el mismo nombre: local > project > user > plugin > conectores de claude.ai.

Configuración del proyecto: .mcp.json

Súbelo a la raíz del repositorio para compartir servidores con el equipo. Admite expansión de ${VAR} y ${VAR:-valor-por-defecto} en command, args, env, url y headers:

{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    },
    "airtable": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "airtable-mcp-server"],
      "env": {
        "AIRTABLE_API_KEY": "${AIRTABLE_API_KEY}"
      }
    }
  }
}

Gestionar los servidores

claude mcp list                    # estado: Connected / Needs authentication / Failed to connect / Pending approval
claude mcp get <nombre>            # detalles de un servidor
claude mcp remove <nombre>         # lo elimina (--scope para apuntar a un ámbito)
claude mcp reset-project-choices   # reinicia las decisiones de aprobación de .mcp.json
claude mcp login                   # autentica servidores MCP desde el shell
claude mcp add-from-claude-desktop # importa los servidores de Claude Desktop

Dentro de la sesión, /mcp abre el panel de gestión: autenticar, reconectar y activar/desactivar (/mcp reconnect <servidor>, /mcp enable|disable [<servidor>|all]).

Una vez conectado

• Las herramientas aparecen como mcp__<servidor>__<herramienta> (si vienen en un plugin: mcp__plugin_<plugin>_<servidor>__<herramienta>).
• Los prompts de MCP se convierten en comandos slash: /mcp__<servidor>__<prompt>.
• La búsqueda de herramientas (MCPSearch) está activa por defecto y entra en juego cuando las herramientas superarían el 10% de la ventana de contexto (ENABLE_TOOL_SEARCH=auto).
• Timeouts: MCP_TIMEOUT (arranque), MCP_TOOL_TIMEOUT (~28 h por defecto), timeout por inactividad de 5 min en remoto y 30 min en stdio (CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT); las llamadas MCP de la conversación principal pasan solas a segundo plano tras 2 minutos (v2.1.212+).
• Nombres de servidor reservados que no puedes usar: workspace, claude-in-chrome, computer-use, Claude Preview, Claude Browser.
• Control corporativo: allowedMcpServers / deniedMcpServers en los ajustes gestionados; interruptores por proyecto con enableAllProjectMcpServers, enabledMcpjsonServers y disabledMcpjsonServers (ver Configuración).

---

Última verificación: 2026-09-07

Fuentes oficiales:

• https://code.claude.com/docs/en/mcp.md
• https://docs.claude.com/en/docs/claude-code/mcp
• https://docs.claude.com/en/docs/claude-code/settings

Las herramientas de IA para programar evolucionan rápido. Si encuentras información desactualizada, abre un issue o un pull request.