Configuração do servidor MCP no GitHub Copilot: registro, allowlist e config

Seu primeiro servidor MCP no GitHub Copilot conecta em cerca de dois minutos. Conseguir que a equipe de segurança aprove esse mesmo servidor, o registre e o coloque em uma allowlist leva o resto da semana, a menos que você saiba qual configuração faz o quê. Este artigo segue as três camadas em ordem: o arquivo de configuração que o desenvolvedor escreve, o registro que a equipe navega e a allowlist que o administrador aplica. Todos os exemplos JSON seguem a documentação atual do GitHub e do VS Code, e cada limitação é sinalizada exatamente onde afeta.

💡 Resumo rápido: desenvolvedores escrevem mcp.json, equipes escolhem servidores em um registro, e administradores aplicam allowedMcpServers em managed-settings.json. Três arquivos, três responsáveis e um bug em qualquer um deles parece "o Copilot não tem ferramentas."

O que o MCP faz dentro do Copilot

O Model Context Protocol (MCP) é o padrão aberto que permite ao Copilot chamar ferramentas que ficam fora do editor: uma consulta a banco de dados, uma consulta de issue no Sentry, uma sessão de navegador, um rastreador de tickets. Sem MCP, o Copilot só vê o que o seu editor mostra. Com MCP, o modo agente pode ler o problema que está falhando, consultar os dados por trás dele e depois editar o código que causou o erro, tudo em uma única conversa.

Cada servidor expõe ferramentas, e o Copilot pede sua aprovação antes de o agente executar uma delas. Servidores locais se comunicam por stdio, ou seja, o Copilot inicia um processo na sua máquina. Servidores remotos se comunicam por HTTP em streaming ou pelo transporte SSE, mais antigo, ou seja, o Copilot se conecta a uma URL. Essa diferença única, comando versus URL, define quase todas as decisões de configuração depois: quais campos JSON você escreve, como a autenticação funciona e como uma allowlist pode corresponder ao servidor.

Quais clientes oferecem suporte

A configuração do MCP não é idêntica em todas as superfícies do Copilot. O arquivo e o formato mudam em cada uma:

Arquivos de configuração e onde ficam

Se você colocar o arquivo no lugar errado, o Copilot o ignora sem nenhum erro evidente. Comece decidindo quem deve receber o servidor.

Escopo de workspace ou de usuário

.vscode/mcp.json fica no repositório, então todos que clonarem o repositório receberão os mesmos servidores. Isso faz dele o lugar certo para ferramentas do projeto, como um inspetor de banco de dados ou um navegador Playwright. A configuração do seu perfil de usuário vale para todos os workspaces da sua máquina. Abra-a pela Paleta de comandos com MCP: Open User Configuration e mantenha ali as ferramentas pessoais.

Uma regra simples funciona: se um colega ficaria confuso com a ausência do servidor, faça commit dele. Se só você usa, mantenha-o no seu perfil.

Arquivos portáteis para outros clientes

A referência de configuração MCP do VS Code também lista um formato portátil: .mcp.json na raiz do workspace, ou ~/.copilot/mcp-config.json para o seu usuário. Use-o quando o mesmo repositório for aberto em mais de um cliente do Copilot e você quiser uma única definição em vez de três.

Cada entrada de servidor é montada a partir do mesmo pequeno conjunto de campos:

Existem dois extras, apenas no macOS e no Linux: um objeto sandbox de nível superior (regras de sistema de arquivos e de rede) e uma chave sandboxEnabled por servidor.

Escreva seu primeiro mcp.json

Você pode escrever o arquivo à mão ou executar MCP: Add Server na Paleta de comandos e deixar o VS Code gerar a entrada. Vale a pena escrever uma vez à mão, porque todo problema posterior fica mais fácil de identificar quando você sabe como é um arquivo saudável.

Um servidor stdio local

Esta entrada inicia o servidor MCP do Playwright por meio de npx sempre que o Copilot precisar dele:

{
  "servers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Copiar prompt

Salve o arquivo e o VS Code mostra as ações Start, Stop e Restart acima da entrada. Inicie o servidor, abra o Copilot Chat no modo agente e verifique o seletor de ferramentas: as ferramentas do servidor devem aparecer agora, prontas para ativar.

Um servidor HTTP remoto

Um servidor remoto precisa de uma URL em vez de um comando. Este aponta para o servidor MCP hospedado do GitHub:

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

Copiar prompt

Se o servidor oferecer suporte a OAuth, o VS Code abre um fluxo de login na primeira vez que uma ferramenta é executada. Se ele esperar um token estático, envie-o por headers, e nunca cole o próprio token em um arquivo versionado.

Mantenha segredos fora da configuração

O VS Code resolve isso com variáveis de entrada. Você declara uma entrada uma vez, marca como senha e a referencia com ${input:id}:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "sentry-token",
      "description": "Sentry auth token",
      "password": true
    }
  ],
  "servers": {
    "sentry": {
      "type": "stdio",
      "command": "npx",
      "args": ["@sentry/mcp-server@latest"],
      "env": { "SENTRY_TOKEN": "${input:sentry-token}" }
    }
  }
}

Copiar prompt

O VS Code pede o valor na primeira vez que o servidor inicia, então o repositório contém apenas o placeholder. As entradas têm três tipos: promptString para texto digitado, pickString para uma lista suspensa e command para um valor produzido ao executar um comando. Cada entrada precisa de type, de id e de description.

💡 Um .vscode/mcp.json versionado com um token colado é o vazamento mais comum de MCP. Se você usar envFile, adicione esse arquivo a .gitignore no mesmo commit.

Encontre servidores no registro

Escrever JSON à mão para cada servidor cansa rápido. O registro existe para você não precisar fazer isso.

O registro MCP do GitHub

github.com/mcp lista servidores da comunidade que conectam modelos a arquivos, APIs e bancos de dados. No momento em que este texto foi escrito, ele mostra 375 servidores, do Markitdown da Microsoft ao Stripe e Figma, cada um com um botão Install. Instalar adiciona uma entrada à sua configuração, então leia antes de iniciar o servidor: confira o comando, o nome do pacote e a URL.

O VS Code também lista servidores MCP dentro do editor. Digite @mcp na caixa de busca da visualização Extensões para navegar por eles, instale um, e o VS Code adiciona a entrada à sua configuração de usuário ou de workspace. Trate uma listagem do registro como ponto de partida, não como uma revisão de segurança.

Execute seu próprio registro

Organizações podem hospedar o próprio registro MCP e apontar o Copilot para ele. Se você o construir no Azure API Center, informe a URL base neste formato:

https://SERVICE-NAME.data.REGION.azure-apicenter.ms/workspaces/WORKSPACE-NAME

Não adicione um sufixo de rota como /v0.1/servers. O Copilot acrescenta o caminho do MCP v0.1 por conta própria, e um sufixo faz o registro retornar erro. Proprietários da empresa definem a URL em AI controls, depois em MCP. Proprietários da organização a definem em Copilot, depois em Policies.

Restrinja servidores com allowlists

Administradores têm duas formas de decidir quais servidores os desenvolvedores podem executar. Elas não são equivalentes, então escolha com intenção.

A própria documentação do GitHub chama as configurações gerenciadas de método mais seguro e disponível de forma geral, e descreve a política de registro como não recomendada.

O método de configurações gerenciadas

Adicione um ou ambos allowedMcpServers e deniedMcpServers em copilot/managed-settings.json no repositório .github-private da sua organização, depois faça um commit na branch padrão:

{
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverCommand": ["npx", "@playwright/mcp@latest"] }
  ],
  "deniedMcpServers": [
    { "serverUrl": "https://untrusted.example/*" }
  ]
}

Copiar prompt

Há três tipos de matcher:

• serverUrl corresponde a servidores HTTP e SSE remotos, aceita curingas * e normaliza as URLs para impedir burlas.
• serverCommand corresponde a um servidor stdio local pelo comando e pelos argumentos exatos.
• serverName corresponde ao rótulo que o usuário digitou na configuração. É uma conveniência, não um limite de segurança.

Como a correspondência funciona

O Copilot avalia um servidor em uma ordem fixa:

1. Os padrões embutidos são sempre permitidos.
2. A lista de bloqueio bloqueia tudo que corresponder.
3. Se existir uma allowlist, o servidor precisa corresponder a uma entrada ou é bloqueado.
4. Qualquer ${VARIABLE} não resolvida na configuração bloqueia o servidor.

Sem nenhuma allowlist, um servidor é executado a menos que esteja bloqueado ou contenha uma variável não resolvida. Quando várias fontes de managed-settings.json se aplicam, todas as configurações valem e uma regra de bloqueio de qualquer fonte bloqueia o servidor. Você pode marcar as configurações como overridable para que uma equipe personalize a própria camada.

💡 A correspondência de comando é exata. Se você permitir ["npx", "@playwright/mcp@latest"], um desenvolvedor que executar npx -y @playwright/mcp@latest não corresponde, porque os argumentos são diferentes. Publique a entrada exata que você quer que as pessoas copiem.

A política somente de registro

Ainda no caminho da prévia? Ative a política MCP servers in Copilot, informe a URL do seu registro e depois defina Restrict MCP access to registry servers como Registry only. A mudança é aplicada imediatamente. Como ela corresponde por nome ou ID, trate-a como uma barreira de proteção contra erros não intencionais, e leve ambientes de alto risco para as configurações gerenciadas. Os passos completos estão na documentação de acesso MCP do GitHub.

Configuração do agente em nuvem e da CLI

O agente em nuvem do Copilot (antes chamado de coding agent) roda na infraestrutura do GitHub, então não consegue ler seu .vscode/mcp.json local. Ele tem configuração própria, e é aí que acontece a maior parte dos erros de copiar e colar.

Abra o repositório, vá em Settings, escolha Copilot em Code & automation e edite a caixa MCP configuration:

{
  "mcpServers": {
    "sentry": {
      "type": "local",
      "command": "npx",
      "args": ["@sentry/mcp-server@latest"],
      "tools": ["list_issues"],
      "env": { "SENTRY_TOKEN": "$COPILOT_MCP_SENTRY_TOKEN" }
    }
  }
}

Copiar prompt

Cinco regras diferenciam isso do formato do VS Code:

• O campo de nível superior é mcpServers, não servers.
• type aceita local, stdio, http ou sse.
• tools é obrigatório. Use ["*"] para tudo, ou liste nomes de ferramentas para manter o agente em rédea curta.
• Segredos precisam ser adicionados como segredos ou variáveis do agente cujos nomes começam com COPILOT_MCP_, e a configuração deve referenciar exatamente esses nomes.
• Só há suporte a ferramentas, e servidores remotos não podem usar OAuth.

Os servidores MCP do GitHub e do Playwright já estão habilitados em todos os repositórios, então você só adiciona o que falta. Leia a documentação MCP do agente em nuvem antes de adicionar qualquer coisa que grave dados.

CLI do Copilot. A CLI lê ~/.copilot/mcp-config.json. Dentro de uma sessão interativa, /mcp add guia você na adição de um servidor sem editar o JSON à mão. As allowlists das configurações gerenciadas também são aplicadas aqui, então um servidor que funciona no VS Code mas é bloqueado no terminal geralmente indica uma divergência de política, não uma instalação quebrada.

Corrija erros comuns rapidamente

A maioria das falhas se resume a cinco causas. Compare seu sintoma com a tabela antes de reinstalar qualquer coisa.

O servidor inicia, mas sem ferramentas

Execute MCP: List Servers, escolha o servidor e abra a saída dele. Uma falha ao iniciar geralmente mostra um runtime ausente (Node ou Python fora do PATH) ou um nome de pacote errado. Se o processo estiver saudável, abra o seletor de ferramentas no modo agente e confirme que as ferramentas estão ativadas.

Bloqueado pela política

Um servidor bloqueado quase sempre tem uma de três causas: a allowlist existe e nada corresponde, uma regra de bloqueio de outra fonte de managed-settings.json se aplica, ou a configuração contém um ${VARIABLE} não resolvido. Como as políticas bloqueiam por padrão, um arquivo de configurações malformado bloqueia servidores em vez de deixá-los passar. Pergunte ao administrador qual fonte bloqueou antes de editar a sua configuração.

Trechos colados de outros clientes. Um trecho copiado da documentação de outro cliente MCP quase sempre usa mcpServers. Cole-o em .vscode/mcp.json e nada carrega, sem nenhum aviso. Renomeie o campo, adicione type explicitamente e mova os segredos para entradas enquanto estiver nisso.

Coloque o PicassoIA para trabalhar

Um segundo par de olhos pega os bugs chatos: um nome de campo errado, uma lista tools ausente, um argumento que quebra uma correspondência exata. Você consegue um em um minuto.

Use o Claude Sonnet 5 no PicassoIA

Claude Sonnet 5 lê configurações, raciocina sobre problemas em várias etapas e aceita imagem, então se encaixa bem nessa tarefa. Aqui está um jeito repetível de usá-lo:

1. Abra a página do Claude Sonnet 5 no PicassoIA.
2. Em System Prompt, defina o papel uma vez: "Você revisa configurações MCP do GitHub Copilot. Verifique o campo de nível superior, o tipo de transporte, a lista de ferramentas, o tratamento de segredos e as entradas de allowlist com correspondência exata."
3. Cole sua mcp.json ou managed-settings.json em Prompt. Substitua antes todo token real por um placeholder.
4. Defina Effort como high para a lógica de allowlist. O padrão low serve para verificar erros de digitação e responde em segundos.
5. Deixe Max Tokens em 8192, que é mais que suficiente para uma revisão completa.
6. Anexe uma captura de tela do erro no campo Image, se tiver uma, já que o modelo lê imagens.
7. Execute, depois aplique as correções uma por vez e reinicie o servidor após cada uma.

Para uma segunda opinião, envie o mesmo prompt para GPT 5.6 Sol, Gemini 3.1 Pro ou Kimi K2.6 e compare onde eles discordam. A discordância geralmente marca a linha que vale a pena ler você mesmo.

Crie suas próprias imagens em seguida

Levar isso a uma equipe significa uma página na wiki, um slide para a revisão de segurança e uma imagem de cabeçalho que não pareça clip-art de banco de imagens. A Picasso IA gera tudo isso a partir de um prompt de texto. Experimente o Qwen Image 3 para cenas fotorrealistas, o Seedream 5 Pro para saídas nítidas em 2K, ou o GPT Image 2.5 Flare quando precisar de um rascunho rápido. Descreva a cena, escolha a proporção 16:9 e itere até que ela se encaixe no seu documento. Abra a Picasso IA, escreva seu primeiro prompt e veja como fica seu próximo post de lançamento com uma imagem de cabeçalho real.