MCP (Model Context Protocol)

Ámbitos de configuración (por prioridad)

Los servidores se cargan desde 6 fuentes. Mayor prioridad sobreescribe a menor cuando hay conflicto de nombres. El ámbito enterprise es exclusivo: si existe managed-mcp.json, el resto de ámbitos se ignoran.

Ejemplo de config de proyecto (.mcp.json)

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "my-api": {
      "type": "sse",
      "url": "https://example.com/mcp/sse",
      "headers": { "Authorization": "Bearer ${API_TOKEN}" }
    }
  }
}

Todos los campos soportan expansión de ${VAR} y ${VAR:-default}. Los servidores en .mcp.json requieren aprobación explícita del usuario antes de conectar (almacenada en enabledMcpjsonServers en settings).

Tipos de transporte

Ciclo de vida de la conexión

Arranque

Flujo de llamada a herramienta

Apagado

Autenticación

"oauth": {
  "clientId": "my-app",
  "callbackPort": 8080,
  "authServerMetadataUrl": "https://auth.example.com/.well-known/..."
}

Exposición de herramientas

Ejemplos de nombres

Anotaciones de herramientas (especificación MCP)

Las descripciones de herramientas tienen un límite de 2.048 caracteres. Cuando la salida supera 100.000 caracteres, se guarda en un archivo temporal y el modelo recibe instrucciones para usar la herramienta Read.

Sistema de permisos

Todas las herramientas MCP devuelven checkPermissions() → passthrough. En modo default siempre se pregunta al usuario, en bypassPermissions se aprueban automáticamente, en modo auto decide el clasificador YOLO.

Reglas de permiso del usuario

{
  "permissions": {
    "allow": [
      "mcp__github__search_code",
      "mcp__slack__*"
    ],
    "deny": [
      "mcp__untrusted_server__*"
    ]
  }
}

Políticas enterprise de servidores (managed-mcp.json)

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverUrl": "https://*.company.com/*" },
    { "serverCommand": ["npx", "-y", "@company/mcp-*"] }
  ],
  "deniedMcpServers": [
    { "serverName": "untrusted" }
  ]
}

La lista de denegación siempre tiene prioridad sobre la de permiso.

Comandos CLI

# Agregar servidor stdio (scope por defecto: local)
claude mcp add my-server npx -y @org/mcp-server
  -s, --scope <scope>      # local, user o project
  -e, --env KEY=VALUE      # variables de entorno

# Agregar servidor remoto (transporte detectado automáticamente desde la URL)
claude mcp add my-api https://api.example.com/mcp
  -t, --transport sse|http
  -H, --header "Key: Value"
  --client-id <id>         # Client ID para OAuth
  --xaa                    # Habilitar Cross-App Access

# Agregar con config JSON completa
claude mcp add-json my-server '{"type":"http","url":"https://example.com/mcp"}'

# Otras operaciones
claude mcp remove my-server [-s scope]
claude mcp list
claude mcp get my-server

Comando /mcp

Características avanzadas

Constantes y timeouts clave

MCP_TIMEOUT, MCP_TOOL_TIMEOUT y MAX_MCP_OUTPUT_TOKENS están en el conjunto SAFE_ENV_VARS: pueden configurarse via managed settings sin disparar un diálogo de seguridad.

Gestión de errores