Estendendo o agente de codificação GitHub Copilot com o Protocolo de Contexto de Modelo (MCP)

Saiba como usar o MCP (Protocolo de Contexto de Modelo) para estender as funcionalidades do Agente de codificação do Copilot.

Neste artigo

Pré-requisito

Antes de configurar um servidor MCP para Agente de codificação do Copilot, leia AUTOTITLE para garantir que você entenda os conceitos relacionados a servidores MCP e o Agente de codificação do Copilot.

Introdução

Como administrador de repositório, você pode configurar servidores MCP para uso em seu repositório. Isso é feito por meio de uma configuração formatada em JSON que especifica os detalhes dos servidores MCP que você deseja usar. Insira a configuração JSON diretamente nas configurações do repositório em GitHub.com.

Administradores de organizações e empresas também podem configurar servidores MCP como parte de agentes personalizados usando o frontmatter YAML. Para saber mais, confira AUTOTITLE.

Aviso

Depois de configurar um servidor MCP, o Copilot poderá usar as ferramentas fornecidas pelo servidor de maneira autônoma, sem solicitar sua aprovação antes de usá-las.

Observação

  • O Agente de codificação do Copilot só é compatível com ferramentas fornecidas por servidores MCP. Ele não dá suporte a recursos ou prompts.
  • No momento, o Agente de codificação do Copilot não dá suporte a servidores MCP remotos que usam o OAuth para autenticação e autorização.

Adicionar uma configuração do MCP ao seu repositório

Os administradores do repositório podem configurar servidores MCP seguindo estas etapas:

  1. Em GitHub, acesse a página principal do repositório.

  2. No nome do repositório, clique em Settings. Caso não consiga ver a guia "Configurações", selecione o menu suspenso , clique em Configurações.

    Captura de tela de um cabeçalho de repositório que mostra as guias. A guia "Configurações" é realçada por um contorno laranja-escuro.

  3. Na seção "Código & automação" da barra lateral, clique em Copilot e em seguida em Agente de codificação.

  4. Adicione sua configuração na seção MCP configuration.

    As seções a seguir neste artigo explicam como escrever a configuração JSON que você precisa inserir aqui.

  5. Clique em Salvar.

    Sua configuração será validada para garantir a sintaxe adequada.

  6. Se o seu servidor MCP exigir uma variável, chave ou segredo, adicione uma variável ou segredo ao seu ambiente Copilot. Somente variáveis e segredos com nomes prefixados estarão disponíveis para a configuração do MCP. Confira Como configurar um ambiente do Copilot para o Agente de codificação do Copilot.

Escrever uma configuração JSON para servidores MCP

Você configura servidores MCP usando um formato JSON especial. O JSON deve conter um objeto , em que a chave é o nome do servidor MCP (por exemplo, ) e o valor é um objeto com a configuração desse servidor MCP.

JSON
{
  "mcpServers": {
    "MCP SERVER 1": {
      "command": "VALUE",
      "args": [ VALUES ],
      ...
    },
    "MCP SERVER 2": {
      "command": "VALUE",
      "args": [ VALUES ],
      ...
    },
    ...
  }
}

O objeto de configuração pode conter as seguintes chaves:

Chaves necessárias para servidores MCP locais e remotos

  • (): as ferramentas do servidor MCP para habilitar. Você pode encontrar uma lista de ferramentas na documentação do servidor ou em seu código. É altamente recomendável permitir a lista de ferramentas específicas somente leitura, pois o agente poderá usar essas ferramentas de maneira autônoma e não solicitará aprovação primeiro. Você também pode habilitar todas as ferramentas incluindo na matriz.
  • (): Agente de codificação do Copilot aceita , , ou , .

Chaves específicas do MCP local

  • (): obrigatório. O comando a ser executado para iniciar o servidor MCP.
  • (): obrigatório. Os argumentos a serem passados a .
  • (): opcional. As variáveis de ambiente a serem passadas para o servidor. Esse objeto deve mapear o nome da variável de ambiente que deve ser exposta ao servidor MCP para qualquer um dos seguintes:
  • O nome de um segredo que você configurou em seu ambiente Copilot, começando com .
  • O nome de uma variável que você configurou no seu ambiente Copilot, começando com .

Chaves específicas do MCP remoto

  • (): obrigatório. A URL do servidor MCP.
  • (): opcional. Os cabeçalhos a serem anexados às solicitações ao servidor. Esse objeto deve mapear o nome das chaves de cabeçalho para um dos seguintes:
  • O nome de um segredo que você configurou em seu ambiente Copilot, começando com precedido por .
  • O nome de uma variável que você configurou em seu ambiente Copilot, começando com precedido por um .
  • Um valor da cadeia de caracteres.

Observe que todos os campos e , exceto , suportam substituição por uma variável ou segredo que você configurou em seu ambiente Copilot, começando com precedido por um .

Configurações de exemplo

Exemplo: Sentry

O servidor MCP do Sentry dá ao Copilot acesso autenticado a exceções registradas no Sentry.

JavaScript
// If you copy and paste this example, you will need to remove the comments prefixed with `//`, which are not valid JSON.
{
  "mcpServers": {
    "sentry": {
      "type": "local",
      "command": "npx",
      // We can use the $SENTRY_HOST environment variable which is passed to
      // the server because of the `env` value below.
      "args": ["@sentry/mcp-server@latest", "--host=$SENTRY_HOST"],
      "tools": ["get_issue_details", "get_issue_summary"],
      "env": {
        // We can specify an environment variable value as
        // a variable in your Copilot environment
        // where `COPILOT_MCP_SENTRY_HOST` = "https://contoso.sentry.io"...
        "SENTRY_HOST": "COPILOT_MCP_SENTRY_HOST",
        // or refer to a secret with a name starting with
        // `COPILOT_MCP_`.
        "SENTRY_ACCESS_TOKEN": "COPILOT_MCP_SENTRY_ACCESS_TOKEN"
      }
    }
  }
}

Exemplo: Notion

O servidor MCP do Notion dá ao Copilot acesso autenticado a anotações e outros conteúdos do Notion.

JavaScript
// If you copy and paste this example, you will need to remove the comments prefixed with `//`, which are not valid JSON.
{
  "mcpServers": {
    "notionApi": {
      "type": "local",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        // We can use the $NOTION_API_KEY environment variable which is passed to
        // the server because of the `env` value below.
        "OPENAPI_MCP_HEADERS={\"Authorization\": \"Bearer $NOTION_API_KEY\", \"Notion-Version\": \"2022-06-28\"}",
       "mcp/notion"
      ],
      "env": {
        // The value of the `COPILOT_MCP_NOTION_API_KEY` secret will be passed to the
        // server command as an environment variable called `NOTION_API_KEY`
        "NOTION_API_KEY": "COPILOT_MCP_NOTION_API_KEY"
      },
      "tools": ["*"]
    }
  }
}

Exemplo: Azure

O repositório MCP da Microsoft inclui o servidor MCP do Azure, que permite que Copilot entenda seus arquivos específicos do Azure e recursos do Azure na sua assinatura ao fazer alterações de código.

Para configurar automaticamente o repositório com um arquivo copilot-setup-steps.yml para autenticar com Azure, além de segredos para autenticação, clone o repositório localmente e execute o comando Azure Developer CLIazd coding-agent config na raiz do repositório.

Depois de executar o comando e mesclar a solicitação de pull criada, você poderá adicionar a configuração do MCP ao repositório.

JSON
 {
   "mcpServers": {
     "Azure": {
      "type": "local",
      "command": "npx",
      "args": [
        "-y",
        "@azure/mcp@latest",
        "server",
        "start"
       ],
      "tools": ["*"]
     }
   }
 }

Exemplo: Cloudflare

O servidor MCP Cloudflare cria conexões entre seus serviços do Cloudflare, incluindo documentação de processamento e análise de dados.

JSON
{
  "mcpServers": {
    "cloudflare": {
      "type": "sse",
      "url": "https://docs.mcp.cloudflare.com/sse",
      "tools": ["*"]
    }
  }
}

Exemplo: Azure DevOps

O servidor MCP Azure DevOps cria uma integração contínua entre Copilot e seus serviços do Azure DevOps, incluindo itens de trabalho, pipelines e documentação.

Para usar o servidor de MCP do Azure DevOps com o Agente de codificação do Copilot, você deve atualizar o arquivo copilot-setup-steps.yml do repositório para incluir uma etapa de fluxo de trabalho de logon do Azure.

  1. Configure o OIDC em um aplicativo do Microsoft Entra, confiando em GitHub. Veja Use a ação de login do Azure com o OpenID Connect.

  2. Configurar o acesso à organização e aos projetos do Azure DevOps para a identidade do aplicativo. Confira Adicionar usuários da organização e gerenciar o acesso.

  3. Adicione um arquivo de fluxo de trabalho Actions em seu repositório se ainda não tiver um.

  4. Adicione uma etapa de login do Azure no fluxo de trabalho copilot-setup-steps.

    YAML
    # Esse fluxo de trabalho usa ações que não são certificadas pelo GitHub.
# São fornecidas por terceiros e regidas por
# termos de serviço, política de privacidade e suporte separados
# online.
on:
  workflow_dispatch:
permissions:
  id-token: write
  contents: read
jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    environment: copilot
    steps:
      - name: Azure login
        uses: azure/login@a457da9ea143d694b1b9c7c869ebb04ebe844ef5
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          allow-no-subscriptions: true

    Essa configuração garante que a ação seja executada quando o Agente de codificação do Copilot é executado.

  5. No ambiente do Copilot do seu repositório, adicione segredos para e .

  6. Configure o servidor de MCP do Azure DevOps adicionando um objeto ado à sua configuração de MCP com ferramentas definidas que você deseja que o Agente de codificação do Copilot use.

JSON
{
  "mcpServers": {
    "ado": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "<your-azure-devops-organization>", "-a", "azcli"],
      "tools": ["wit_get_work_item", "wit_get_work_items_batch_by_ids", ...]
    }
  }
}

Como reutilizar a configuração do MCP do Visual Studio Code

Se você já tiver configurado servidores MCP no VS Code, poderá aproveitar uma configuração semelhante para Agente de codificação do Copilot.

Dependendo de como os dados do VS Code estão configurados, você poderá encontrar as configurações do MCP no arquivo do repositório ou no arquivo privado do computador.

Para adaptar a configuração de dados Agente de codificação do Copilot, você precisará:

  1. Adicione uma chave para cada servidor MCP, especificando quais ferramentas estarão disponíveis para Copilot.
  2. Se você tiver configurou o , alterne para usar diretamente.
  3. Se você tiver configurado um , alterne para usar diretamente.
  4. Atualize todas as referências a em sua configuração do para se referir a variáveis de ambiente de em vez disso.

Para obter mais informações sobre o MCP no VS Code, confira os documentos do VS Code.

Como configurar um ambiente do Copilot para o Agente de codificação do Copilot

Alguns servidores MCP exigirão chaves ou segredos. Para aproveitar esses servidores no Agente de codificação do Copilot, adicione segredos a um ambiente para Copilot. Isso garante que os segredos sejam reconhecidos corretamente e passados para o servidor MCP aplicável que você configurou.

Você deve ser um administrador de repositório para configurar um ambiente Copilot para seu repositório.

  1. Em GitHub, acesse a página principal do repositório.

  2. No nome do repositório, clique em Settings. Caso não consiga ver a guia "Configurações", selecione o menu suspenso , clique em Configurações.

    Captura de tela de um cabeçalho de repositório que mostra as guias. A guia "Configurações" é realçada por um contorno laranja-escuro.

  3. Na barra lateral esquerda, clique em Ambientes.

  4. Clique em Novo ambiente.

  5. Chame o novo ambiente de e clique em Configure environment.

  6. Em "Environment secrets", clique em Add environment secret.

  7. Dê ao segredo um nome que comece com , adicione o valor do segredo e clique em Add secret.

Como validar a configuração do MCP

Depois de definir a configuração do MCP, teste-a para verificar se está configurada corretamente.

  1. Crie um issue no repositório e atribua-o a Copilot.
  2. Aguarde alguns segundos e Copilot deixará uma reação sobre o issue.
  3. Aguarde mais alguns segundos e Copilot criará uma pull request, que será exibida na linha do tempo do issue.
  4. Clique na pull request criada na linha do tempo e aguarde até que um evento de linha do tempo "Copilot iniciou o trabalho" seja exibido.
  5. Clique em View session para abrir os logs do Agente de codificação do Copilot.
  6. Clique no botão de reticências (...) na parte superior direita do visualizador de log e clique em Copilot na barra lateral.
  7. Clique na etapa Start MCP Servers para expandir os logs.
  8. Se os servidores MCP tiverem sido iniciados com êxito, você verá suas ferramentas listadas na parte inferior dos logs.

Se os servidores MCP exigirem dependências que não estejam instaladas no executor GitHub Actions por padrão, como e , ou que precisem de etapas especiais de instalação, talvez seja necessário criar um arquivo de fluxo de trabalho de Ações para instalá-las. Para saber mais, confira AUTOTITLE.

Como personalizar o servidor MCP do GitHub predefinido

O servidor MCP GitHub está habilitado por padrão e se conecta ao GitHub com um token com escopo especial que só tem acesso somente leitura ao repositório atual.

Se você quiser permitir que o Copilot acesse dados fora do repositório atual, poderá fornecer a ele um personal access token com acesso mais amplo.

  1. Crie um personal access token com as permissões apropriadas. É recomendável usar um fine-grained personal access token, em que você pode limitar o acesso do token a permissões somente leitura em repositórios específicos. Para obter mais informações sobre o personal access tokens, confira AUTOTITLE.

  2. Em GitHub, acesse a página principal do repositório.

  3. No nome do repositório, clique em Settings. Caso não consiga ver a guia "Configurações", selecione o menu suspenso , clique em Configurações.

    Captura de tela de um cabeçalho de repositório que mostra as guias. A guia "Configurações" é realçada por um contorno laranja-escuro.

  4. Na seção "Código & automação" da barra lateral, clique em Copilot e em seguida em Agente de codificação.

  5. Adicione sua configuração na seção MCP configuration. Por exemplo, você pode adicionar o seguinte:

    JavaScript
     // If you copy and paste this example, you will need to remove the comments prefixed with `//`, which are not valid JSON.
 {
   "mcpServers": {
     "github-mcp-server": {
       "type": "http",
       // Remove "/readonly" to enable wider access to all tools.
       // Then, use the "X-MCP-Toolsets" header to specify which toolsets you'd like to include.
       // Use the "tools" field to select individual tools from the toolsets.
       "url": "https://api.githubcopilot.com/mcp/readonly",
       "tools": ["*"],
       "headers": {
         "X-MCP-Toolsets": "repos,issues,users,pull_requests,code_security,secret_protection,actions,web_search"
       }
     }
   }
 }

    Para obter mais informações sobre conjuntos de ferramentas, consulte LEIAME na documentação do GitHub Remote MCP Server.

  6. Clique em Salvar.

  7. Na barra lateral esquerda, clique em Ambientes.

  8. Clique no ambiente .

  9. Em "Environment secrets", clique em Add environment secret.

  10. Chame o segredo , insira seu personal access token no campo "Value" e clique em Add secret.

Para obter informações sobre como usar o servidor de MCP do GitHub em outros ambientes, consulte AUTOTITLE.

Próximas etapas

  • AUTOTITLE
  • AUTOTITLE
  • AUTOTITLE
  • AUTOTITLE