Agregar servidores MCP a Claude Code (claude mcp add, .mcp.json, scopes)

HTTP es el transporte recomendado para servidores remotos. Los servidores stdio se ejecutan como procesos locales en tu máquina. Para stdio, el separador -- divide las opciones propias de Claude (como --transport, --env y --scope) del comando que inicia el servidor. Todo lo que va después de -- llega al servidor sin cambios.

# Remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# HTTP server with a Bearer token header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

# Local stdio server with an environment variable
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

• Define variables de entorno con -e o --env, por ejemplo -e KEY=value.
• Si el nombre del servidor va justo después de --env, la CLI lo interpreta como otro par y lo rechaza. Pon otra opción, como --transport stdio, entre --env y el nombre.
• --transport y --header también aceptan las formas cortas -t y -H.
• SSE está obsoleto. Aún puedes pasar --transport sse para conectarte a un servidor que solo admite SSE.
• Si ya tienes una configuración JSON para un servidor, agrégala con claude mcp add-json NAME 'JSON'.

Usa -s o --scope para elegir uno de tres scopes. Local (el predeterminado) se carga solo en el proyecto actual y se guarda en ~/.claude.json. Project se guarda en .mcp.json en la raíz del proyecto, así que tu equipo lo obtiene mediante control de versiones. User también se guarda en ~/.claude.json, pero se carga en todos tus proyectos. Cuando el mismo nombre de servidor se define en más de un scope, local gana sobre project, y project gana sobre user.

claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

.mcp.json admite la expansión ${VAR} y ${VAR:-default} en command, args, env, url y headers. Siempre define type en una entrada remota: una entrada con url pero sin type es un error de configuración, porque Claude Code trata una entrada sin type como un servidor stdio.

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    },
    "local-weather": {
      "type": "stdio",
      "command": "/path/to/weather-cli",
      "args": ["--api-key", "${WEATHER_API_KEY}"],
      "env": { "CACHE_DIR": "/tmp" }
    }
  }
}

• Claude Code te pide aprobar los servidores con scope de proyecto de .mcp.json antes de usarlos. Restablece esas decisiones con claude mcp reset-project-choices.
• Si una variable referenciada no está definida y no tiene valor predeterminado, el servidor igual se carga con el texto literal ${VAR}, y claude mcp list muestra una advertencia.

Claude Code admite OAuth 2.0 para servidores remotos. Después de agregar un servidor que requiere inicio de sesión, ejecuta /mcp dentro de Claude Code y completa el login en tu navegador. Los tokens se guardan de forma segura y se renuevan automáticamente. Usa Clear authentication en el menú /mcp para revocar el acceso.

claude mcp list
claude mcp get notion
claude mcp remove notion
claude mcp login sentry
claude mcp logout sentry

Quitar un servidor remoto también elimina los tokens OAuth que Claude Code guardó para él. Para quitar una definición de un scope, ejecuta claude mcp remove NAME --scope SCOPE.

• MCP_TIMEOUT define el timeout de inicio del servidor en milisegundos, por ejemplo MCP_TIMEOUT=10000 claude.
• MCP_TOOL_TIMEOUT define el timeout de ejecución de herramientas. Anúlalo para un servidor con un campo timeout (milisegundos) en la entrada .mcp.json de ese servidor.
• Claude Code avisa cuando la salida de una herramienta MCP supera los 10,000 tokens y la limita a 25,000 tokens por defecto. Sube el límite con MAX_MCP_OUTPUT_TOKENS.

export MAX_MCP_OUTPUT_TOKENS=50000
MCP_TIMEOUT=10000 claude