Controle o acesso ao servidor MCP para sua organização

• Escolher um padrão que corresponda ao quanto de controle você precisa
• Implantar um conjunto de servidor fixo com managed-mcp.json, incluindo como desabilitar MCP completamente
• Fornecer servidores através de configurações gerenciadas enquanto os usuários mantêm os seus próprios
• Controlar servidores com listas de permissão e listas de bloqueio
• Informar aos usuários o que esperar quando uma restrição bloqueia um servidor
• Monitorar quais servidores sua organização realmente usa

​

Escolha um padrão

​

Controle exclusivo com managed-mcp.json

• Os servidores que o arquivo define
• Servidores que você fornece através de managedMcpServers
• Servidores em processo que o aplicativo que iniciou a sessão registra, como o servidor próprio da extensão VS Code ou os conectores que o aplicativo desktop fornece
• O servidor integrado Claude in Chrome, se você permitir junto com o conjunto gerenciado

​

Implantar managed-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 com credenciais por usuário

• Expansão ${VAR} para ler segredos do ambiente de cada usuário.
• OAuth ou cabeçalhos por usuário para que cada usuário se autentique como si mesmo.
• headersHelper para gerar credenciais no momento da conexão.

​

Servidores passados com --mcp-config ou --strict-mcp-config

• Em uma estação de trabalho, Claude Code sai na inicialização com You cannot dynamically configure MCP servers when an enterprise MCP config is present.
• Em sessões na nuvem em um host onde o arquivo está implantado, como um executor auto-hospedado, Claude Code inicia apenas com os servidores gerenciados e ignora os conectores claude.ai e outros servidores que o host na nuvem fornece através de --mcp-config. Nada na sessão informa ao usuário quais servidores foram deixados de fora. Claude Code os nomeia em um aviso em seu stderr, que um executor auto-hospedado registra no nível de log debug.

​

Como listas de permissão e listas de negação se aplicam ao conjunto gerenciado

• deniedMcpServers também se aplica aos servidores gerenciados, portanto um servidor gerenciado que corresponda a uma entrada não será carregado.
• A própria deniedMcpServers de um usuário é mesclada a partir de suas configurações, portanto os usuários podem bloquear um servidor gerenciado para si mesmos.

​

Validar a configuração

1. claude mcp list mostra apenas os servidores em managed-mcp.json, além de qualquer um que você forneça através de managedMcpServers. Dois outros resultados significam que algo está errado:
   • Se os próprios servidores de um usuário ainda aparecerem, Claude Code não está lendo o arquivo, portanto verifique seu caminho e as permissões nos diretórios pai.
   • Se os servidores do arquivo não aparecerem e a seção MCP config diagnostics marca a configuração empresarial como falha ao analisar, Claude Code não consegue ler ou analisar o arquivo. Corrija o erro que essa seção nomeia e peça ao usuário para reiniciar Claude Code.
2. claude mcp add --transport http test https://example.com/mcp falha com Cannot add MCP server: enterprise MCP configuration is active and has exclusive control over MCP servers. A URL não precisa ser um servidor real, já que a verificação de política rejeita o comando antes de qualquer coisa ser contatada.

​

Desabilitar MCP completamente

{
  "mcpServers": {}
}

​

Permitir conectores claude.ai junto com o conjunto gerenciado

​

Permitir Claude in Chrome junto com o conjunto gerenciado

​

Fornecer servidores através de configurações gerenciadas

{
  "managedMcpServers": {
    "search": {
      "type": "http",
      "url": "https://search.example.com/mcp"
    },
    "records": {
      "type": "http",
      "url": "https://records.example.com/mcp",
      "headers": {
        "X-Records-Key": "key-issued-for-all-claude-code-users"
      }
    }
  }
}

​

O que uma entrada pode conter

• type é http ou sse. Como em .mcp.json, streamable-http é aceito como um alias para http.
• url é uma URL https://. Claude Code recusa uma URL simples http://, incluindo uma que aponta para localhost.
• A entrada não tem membro command, args, env ou headersHelper, portanto um documento de configurações gerenciadas nunca nomeia um programa para executar na máquina de um usuário.
• Nenhum valor contém uma referência ${VAR}. Claude Code não expande variáveis de ambiente nessas entradas, portanto escreva valores literais.
• O nome do servidor contém apenas letras, números, hífens e sublinhados, e nenhuma chave ou valor contém caracteres de controle ou formatação invisível.

​

Como os servidores fornecidos são carregados

• Um servidor fornecido tem precedência sobre um servidor com o mesmo nome em escopo local, de projeto ou de usuário, e sobre um servidor de plugin ou conector claude.ai que aponta para a mesma URL.
• Se você também implantar managed-mcp.json, Claude Code carrega seus servidores e os servidores fornecidos juntos, e a entrada do arquivo tem precedência quando ambos definem um nome.
• Os servidores fornecidos continuam carregando quando strictPluginOnlyCustomization bloqueia a superfície mcp.
• deniedMcpServers se aplica aos servidores fornecidos, incluindo entradas das próprias configurações de um usuário, portanto um usuário pode bloquear um para si mesmo. Os servidores fornecidos não precisam de uma entrada allowedMcpServers.

• Um servidor que um usuário passa com --mcp-config sob o mesmo nome substitui o fornecido para essa execução e é verificado contra allowedMcpServers.
• --strict-mcp-config deixa os servidores fornecidos de fora junto com todos os outros servidores configurados.

​

O que os usuários podem ver e alterar

• claude mcp remove relata que o servidor é fornecido pela organização.
• Quando você também não implantou managed-mcp.json, uma entrada que um usuário adiciona sob o mesmo nome é salva mas não usada enquanto a sua está presente.
• Os usuários ainda podem desativar um servidor fornecido para si mesmos em /mcp, que lista servidores fornecidos em Managed MCPs.

​

Onde managedMcpServers se aplica

​

Quando os servidores fornecidos se conectam

• Em uma máquina com configurações em cache, Claude Code retém a cópia em cache dessa chave até que o servidor confirme as configurações para a sessão, e aguarda essa confirmação antes de carregar os servidores MCP. Se a confirmação falhar, a sessão continua sem os servidores fornecidos e /status diz que eles estão retidos.
• No primeiro lançamento de uma máquina, sem nada em cache ainda, uma sessão interativa que começa antes das configurações chegarem conecta os servidores fornecidos assim que chegam, e uma execução claude -p que já começou pode terminar sem eles.

• Adicionar um servidor: Claude Code o conecta quando as configurações atualizadas chegam, sem uma reinicialização.
• Alterar a entrada de um servidor: essas sessões se reconectam a ele com a nova definição.
• Remover um servidor: uma sessão interativa em execução o desconecta assim que lê as configurações alteradas. Uma execução não interativa (-p) o mantém até terminar.

​

Controle baseado em políticas com listas de permissão e bloqueio

​

Corresponder servidores por URL, comando ou nome

• Em deniedMcpServers, serverName aceita qualquer string não vazia sem espaço em branco à esquerda ou à direita, então você pode bloquear conectores claude.ai pelo seu nome de exibição. Por exemplo, { "serverName": "claude.ai Slack" } bloqueia o conector Slack. Prefira uma entrada serverUrl quando você precisar que a negação seja robusta a renomeações, ou quando um nome de conector colide e ganha um sufixo (N).
• Em allowedMcpServers, serverName é limitado a letras, números, hífens e sublinhados. Use serverUrl para colocar na lista de permissão um conector claude.ai que Claude Code busca a si mesmo; para conectores que um host na nuvem entrega para sessões auto-hospedadas, use as entradas listadas em O tráfego do conector sai de sua rede em vez disso.

​

Como um servidor é avaliado

1. Mescle as listas. Entradas de lista de permissão e bloqueio de todos os escopos de configurações se combinam em uma lista de permissão e uma lista de bloqueio. Quando allowManagedMcpServersOnly é true, apenas a lista de permissão gerenciada é mantida; a lista de bloqueio sempre se mescla de todos os escopos. Quando mais de uma fonte gerenciada está presente, Chaves lidas de todas as fontes de administrador diz qual delas fornece as listas do escopo gerenciado.
2. Verifique a lista de bloqueio. Um servidor que corresponde a qualquer entrada de lista de bloqueio, por URL, comando ou nome, é bloqueado. Nada substitui uma correspondência de lista de bloqueio.
3. Verifique a lista de permissão. Se allowedMcpServers não estiver definido em nenhum lugar, todos os servidores que passaram na lista de bloqueio carregam. Se estiver definido, o que o servidor deve corresponder depende de seu tipo, mostrado na tabela abaixo. Três grupos de servidores pulam essa verificação:
   • Os próprios servidores da organização: toda entrada managedMcpServers, e qualquer entrada managed-mcp.json cujos valores não usam expansão ${VAR}.
   • Servidores integrados, como Claude no Chrome, o servidor ide que Claude Code se conecta em um IDE VS Code ou JetBrains em execução, e servidores que a própria CLI configura.
   • Ferramentas Slack de uma sessão Claude Tag: os servidores que ela usa para ler a thread e postar suas respostas carregam sem uma entrada de lista de permissão.
   Um servidor managed-mcp.json que usa expansão ${VAR} em seu comando, argumentos, env, URL ou cabeçalhos ainda é verificado. Assim como todos os servidores que um usuário, um plugin, ou claude.ai adiciona, e todos os servidores que um usuário passa com --mcp-config.

• Comandos correspondem exatamente. Cada argumento, em ordem. ["npx", "-y", "server"] não corresponde a ["npx", "server"] ou ["npx", "-y", "server", "--flag"].
• Valores serverCommand e serverUrl se expandem antes de corresponder. Tanto a entrada de política quanto o valor configurado do servidor passam por expansão ${VAR} e ${VAR:-default}, então uma entrada escrita como ["${HOME}/bin/server"] corresponde a uma configuração de servidor que usa a mesma referência ou o caminho expandido. No Windows, referencie uma variável de ambiente que está definida lá, como ${USERPROFILE} em vez de ${HOME}. Valores serverName correspondem literalmente e nunca se expandem. Os dois lados leem ambientes diferentes; Como entradas de política se expandem cobre qual, e como entradas de lista de permissão e bloqueio diferem.
• URLs suportam wildcards * em qualquer lugar do padrão, incluindo o esquema. A correspondência de nome de host não diferencia maiúsculas de minúsculas e ignora um ponto FQDN à direita, então https://Mcp.Example.com/* corresponde a https://mcp.example.com/api. Caminhos permanecem sensíveis a maiúsculas e minúsculas.

​

Como entradas de política se expandem

​

Configuração de exemplo

{
  "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/*" }
  ]
}

• Linha 3: a primeira entrada serverUrl. Uma vez que uma existe, todos os servidores remotos devem corresponder a um padrão de URL, então um usuário não pode obter um servidor remoto não listado dando a ele um nome permitido.
• Linha 5: a primeira entrada serverCommand. Mesmo efeito para servidores stdio, então todos os servidores locais devem corresponder a um comando listado exatamente.
• Linha 11: uma entrada serverName na lista de bloqueio. Entradas de lista de bloqueio sempre se aplicam, então qualquer servidor nomeado dangerous-server é bloqueado independentemente de sua URL ou comando.

{
  "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/*" }
  ]
}

​

Restrinja a lista de permissão apenas às configurações gerenciadas

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

​

Como as restrições aparecem aos usuários

​

Monitorar o uso de MCP

​

Resumo de configuração

​

Recursos relacionados

• Decidir o que aplicar: restrições de MCP junto com regras de permissão, sandboxing e os outros controles de administrador
• Conectar Claude Code a ferramentas via MCP: a referência completa de MCP, incluindo transportes, escopos e autenticação
• Configurações: a hierarquia de configurações e como as configurações gerenciadas têm precedência
• Configurações gerenciadas pelo servidor: entregar allowedMcpServers e deniedMcpServers do console de administrador do Claude.ai
• Segurança: o modelo de ameaça que esses controles defendem
• Guia do Administrador Empresarial Claude: SSO, SCIM, gerenciamento de assentos e playbook de implementação