Controlar el acceso al servidor MCP para su organización

Restrinja qué servidores MCP pueden agregar o conectar los usuarios con archivos de configuración administrados, listas de permitidos y listas de bloqueados.

De forma predeterminada, cualquiera que ejecute Claude Code puede conectar cualquier servidor MCP que elija. Anthropic revisa los conectores según sus criterios de listado antes de agregarlos al Directorio de Anthropic, pero no realiza auditorías de seguridad ni administra ningún servidor MCP. Como administrador, puede restringir qué servidores se ejecutan en su organización, desde implementar un conjunto fijo aprobado hasta deshabilitar MCP completamente.

Esta página cubre cómo:

• Elegir un patrón que se ajuste a cuánto control necesita
• Implementar un conjunto de servidor fijo con managed-mcp.json, incluido cómo deshabilitar MCP completamente
• Controlar servidores con listas de permitidos y listas de bloqueados
• Informar a los usuarios qué esperar cuando una restricción bloquea un servidor
• Monitorear qué servidores usa realmente su organización

Elegir un patrón

Claude Code admite una variedad de niveles de restricción. Cada patrón utiliza uno o ambos de los mecanismos cubiertos a continuación: managed-mcp.json para implementar un conjunto fijo, y allowedMcpServers/deniedMcpServers para filtrar lo que los usuarios configuran.

Control exclusivo con managed-mcp.json

Si implementa un archivo managed-mcp.json, Claude Code carga solo los servidores que ese archivo define. Los usuarios no pueden agregar, modificar ni usar ningún otro servidor MCP, incluidos los servidores proporcionados por plugins. El archivo también suprime los conectores de claude.ai a menos que los permita junto con el conjunto administrado.

Dos otras configuraciones pueden filtrar aún más el conjunto administrado:

• allowedMcpServers y deniedMcpServers también se aplican a servidores administrados, por lo que un servidor administrado que no los cumpla no se cargará.
• El propio deniedMcpServers de un usuario se fusiona desde su configuración, por lo que los usuarios pueden bloquear un servidor administrado para sí mismos.

Consulte Cómo se evalúa un servidor para el orden completo de verificaciones.

managed-mcp.json es un archivo independiente, por lo que no se puede entregar a través de configuración administrada por servidor. Cualquier proceso que pueda escribir en una ruta del sistema con privilegios de administrador puede implementarlo. A escala, eso suele ser a través de herramientas de administración de dispositivos, como Jamf o un perfil de configuración en macOS, Directiva de grupo o Intune en Windows, o su administración de flota de su elección en Linux. Claude Code busca el archivo en una de estas rutas:

El archivo utiliza el mismo formato que un archivo de proyecto .mcp.json:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"],
      "env": {
        "COMPANY_API_URL": "https://internal.example.com"
      }
    }
  }
}

Autenticar con credenciales por usuario

Cualquier usuario en la máquina puede leer este archivo, así que no almacene claves API u otras credenciales en bloques env. Pase credenciales por usuario con una de estas en su lugar:

• Expansión ${VAR} para leer secretos del entorno de cada usuario.
• OAuth o encabezados por usuario para que cada usuario se autentique como sí mismo.
• headersHelper para generar credenciales en el momento de la conexión.

Validar la configuración

Para confirmar que el archivo está en vigor, ejecute dos verificaciones en una máquina administrada:

1. claude mcp list muestra solo los servidores en managed-mcp.json. Si los propios servidores de un usuario aún aparecen, el archivo no se está leyendo; verifique la ruta y los permisos.
2. claude mcp add --transport http test https://example.com/mcp falla con Cannot add MCP server: enterprise MCP configuration is active and has exclusive control over MCP servers. La URL no necesita ser un servidor real, ya que la verificación de política rechaza el comando antes de que se contacte con nada.

Deshabilitar MCP completamente

Implemente un managed-mcp.json que contenga un mapa de servidor vacío para bloquear cada servidor MCP:

{
  "mcpServers": {}
}

Los usuarios no ven servidores MCP en /mcp, y claude mcp add falla con el error de política empresarial anterior. Los servidores que los usuarios habían configurado previamente dejan de cargarse la próxima vez que inician una sesión, sin advertencia de que la política es la razón.

Permitir conectores de claude.ai junto con el conjunto administrado

Implementar managed-mcp.json suprime conectores de claude.ai de forma predeterminada, incluidos los conectores que un administrador configuró para la organización en la consola de administración de claude.ai. Para cargar esos conectores junto con los servidores en managed-mcp.json, establezca "allowAllClaudeAiMcps": true en una fuente de configuración administrada. Requiere Claude Code v2.1.149 o posterior.

Con la configuración habilitada, Claude Code carga los mismos conectores de claude.ai que cargaría si managed-mcp.json no estuviera implementado. Las listas de permitidos y denegar aún se aplican a esos conectores, por lo que puede bloquear los específicos con deniedMcpServers. La configuración afecta solo a los conectores de claude.ai; los servidores proporcionados por plugins permanecen suprimidos.

Claude Code lee esta configuración solo desde niveles de política controlados por administrador: configuración administrada por servidor, una clave de registro plist o HKLM implementada por MDM, o un archivo managed-settings.json del sistema. Colocarla en configuración de usuario o proyecto no tiene efecto, por lo que los usuarios no pueden volver a habilitar los conectores que el control exclusivo suprimió.

Control basado en políticas con listas de permitidos y listas de bloqueados

Las listas de permitidos y listas de bloqueados filtran qué servidores configurados pueden cargarse. No son un registro: un servidor aún tiene que ser agregado por un usuario, un plugin o managed-mcp.json antes de que la lista de permitidos o la lista de bloqueados se aplique a él. Para implementar servidores a los usuarios, use managed-mcp.json.

Para hacer que la lista de permitidos sea autoritaria, establezca allowedMcpServers y allowManagedMcpServersOnly: true juntos en una fuente de configuración administrada, como configuración administrada por servidor o un archivo managed-settings.json implementado. Restringir la lista de permitidos solo a configuración administrada muestra la configuración. Sin allowManagedMcpServersOnly, las listas de permitidos de cada fuente de configuración se fusionan, incluido el propio ~/.claude/settings.json de un usuario, por lo que un usuario puede ampliar lo que su lista de permitidos permite. Las listas de bloqueados se fusionan desde cada fuente independientemente.

Hacer coincidir servidores por URL, comando o nombre

allowedMcpServers y deniedMcpServers son listas de entradas. Cada entrada es un objeto con una sola clave que identifica servidores por su URL, su comando o su nombre:

Dejar allowedMcpServers sin establecer es diferente a establecerlo en una matriz vacía:

La validación de serverName difiere entre las dos listas:

• {/* min-version: 2.1.182 */}En deniedMcpServers, serverName acepta cualquier cadena no vacía, por lo que puede bloquear conectores de claude.ai por su nombre mostrado. Por ejemplo, { "serverName": "claude.ai Slack" } bloquea el conector de Slack. Prefiera una entrada serverUrl cuando necesite que la denegación sea robusta ante cambios de nombre, o cuando un nombre de conector colisiona y gana un sufijo (N).
• En allowedMcpServers, serverName se limita a letras, números, guiones e guiones bajos. Use serverUrl para permitir un conector de claude.ai.

Para desactivar todos los conectores de claude.ai, vea disableClaudeAiConnectors.

Cómo se evalúa un servidor

Antes de cargar un servidor, incluido uno de managed-mcp.json, Claude Code ejecuta tres verificaciones en orden:

1. Fusionar las listas. Las entradas de lista de permitidos y lista de bloqueados de cada fuente de configuración se combinan en una lista de permitidos y una lista de bloqueados. Cuando allowManagedMcpServersOnly es true, solo se mantiene la lista de permitidos administrada; la lista de bloqueados siempre se fusiona desde cada fuente.
2. Verificar la lista de bloqueados. Un servidor que coincida con cualquier entrada de lista de bloqueados, por URL, comando o nombre, se bloquea. Nada anula una coincidencia de lista de bloqueados.
3. Verificar la lista de permitidos. Si allowedMcpServers no está establecido en ningún lugar, cada servidor que pasó la lista de bloqueados se carga. Si está establecido, lo que el servidor debe coincidir depende de su tipo, que se muestra en la tabla a continuación.

Dos reglas de coincidencia se aplican dentro de esas verificaciones:

• Los comandos coinciden exactamente. Cada argumento, en orden. ["npx", "-y", "server"] no coincide con ["npx", "server"] o ["npx", "-y", "server", "--flag"].
• Las URLs admiten comodines * en cualquier lugar del patrón, incluido el esquema. La coincidencia del nombre de host no distingue mayúsculas de minúsculas e ignora un punto FQDN final, por lo que https://Mcp.Example.com/* coincide con https://mcp.example.com/api. Las rutas permanecen sensibles a mayúsculas y minúsculas.

Configuración de ejemplo

La configuración a continuación configura una lista de permitidos dura con una lista de bloqueados. Las líneas resaltadas cambian cómo se evalúa el resto de la lista, y las llamadas después del bloque explican cada una:

{
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverUrl": "https://mcp.sentry.dev/*" },
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."] },
    { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },
    { "serverUrl": "https://mcp.example.com/*" },
    { "serverUrl": "https://*.internal.example.com/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" },
    { "serverCommand": ["npx", "-y", "unapproved-package"] },
    { "serverUrl": "https://*.untrusted.example.com/*" }
  ]
}

• Línea 3: la primera entrada serverUrl. Una vez que existe una, cada servidor remoto debe coincidir con un patrón de URL, por lo que un usuario no puede obtener un servidor remoto no listado dándole un nombre permitido.
• Línea 5: la primera entrada serverCommand. El mismo efecto para servidores stdio, por lo que cada servidor local debe coincidir exactamente con un comando listado.
• Línea 11: una entrada serverName en la lista de bloqueados. Las entradas de lista de bloqueados siempre se aplican, por lo que cualquier servidor llamado dangerous-server se bloquea independientemente de su URL o comando.

Una entrada serverName en esta lista de permitidos nunca coincidiría con nada, ya que ambos tipos de transporte ya tienen entradas más estrictas.

Los acordeones a continuación recorren cómo se evalúa un servidor contra otras combinaciones de lista de permitidos y lista de bloqueados.

{
"allowedMcpServers": [
{ "serverUrl": "https://mcp.example.com/*" },
{ "serverUrl": "https://*.internal.example.com/*" }
]
}

{
"allowedMcpServers": [
{ "serverCommand": ["npx", "-y", "approved-package"] }
]
}

{
"allowedMcpServers": [
{ "serverName": "github" },
{ "serverCommand": ["npx", "-y", "approved-package"] }
]
}

{
"allowedMcpServers": [
{ "serverName": "github" },
{ "serverName": "internal-tool" }
]
}

{
"allowedMcpServers": [
{ "serverUrl": "https://*.example.com/*" }
],
"deniedMcpServers": [
{ "serverUrl": "https://staging.example.com/*" }
]
}

Restringir la lista de permitidos solo a configuración administrada

Para hacer que la lista de permitidos administrada sea la única que se aplique, establezca allowManagedMcpServersOnly en el archivo de configuración administrada:

{
  "allowManagedMcpServersOnly": true,
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverUrl": "https://*.internal.example.com/*" }
  ]
}

Cuando allowManagedMcpServersOnly es true, las listas de permitidos de configuración de usuario, proyecto y local se ignoran. La lista de bloqueados aún se fusiona desde todas las fuentes, por lo que los usuarios siempre pueden bloquear servidores para sí mismos.

Cómo aparecen las restricciones a los usuarios

Cuando una restricción bloquea un servidor, el usuario ve un error de claude mcp add o el servidor deja de cargarse silenciosamente. Use esta tabla para reconocer esos informes y para informar a los usuarios qué esperar antes de implementar un cambio:

En el último caso, el usuario no recibe ninguna señal de que la política es la razón por la que su servidor desapareció, así que informe a los usuarios afectados qué servidores se bloquean cuando implemente una nueva restricción.

Monitorear el uso de MCP

Cuando se configura exportación de OpenTelemetry, Claude Code puede registrar qué servidores MCP y herramientas invocan los usuarios. Establezca OTEL_LOG_TOOL_DETAILS=1 para incluir nombres de servidor MCP y herramientas en eventos de herramientas, luego agréguelos en su recopilador para ver qué servidores conectan realmente sus usuarios. Consulte Monitoring para configurar el exportador y para el esquema de evento completo.

Resumen de configuración

Cada archivo y configuración que cubre esta página, qué controla y cómo entregarlo:

Recursos relacionados

• Decide what to enforce: restricciones de MCP junto con reglas de permisos, sandboxing y los otros controles de administrador
• Connect Claude Code to tools via MCP: la referencia completa de MCP, incluidos transportes, alcances y autenticación
• Settings: la jerarquía de configuración y cómo la configuración administrada tiene prioridad
• Server-managed settings: entregar allowedMcpServers y deniedMcpServers desde la consola de administrador de Claude.ai
• Security: el modelo de amenaza que estos controles defienden
• Claude Enterprise Administrator Guide: SSO, SCIM, administración de asientos y guía de implementación