Como estender o agente de codificação do Copilot com o MCP (Model Context Protocol)

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

Neste artigo

Observação

Agente de codificação do Copilot is in versão prévia pública and subject to change.

Para obter mais informações sobre Agente de codificação do Copilot, confira Sobre a atribuição de tarefas ao Copilot.

The Model Context Protocol (MCP) is an open standard that defines how applications share context with large language models (LLMs). MCP provides a standardized way to connect AI models to different data sources and tools, enabling them to work together more effectively.

You can use MCP to extend the capabilities of Agente de codificação do Copilot by connecting it to other tools and services.

O agente pode usar ferramentas fornecidas por servidores MCP locais. Por exemplo, o servidor MCP do Playwright fornece ferramentas para interagir com páginas da Web e efetuar pull em contexto adicional durante a execução na tarefa solicitada.

Para obter mais informações sobre o MCP, confira a documentação oficial do MCP. Para obter informações sobre alguns dos outros servidores MCP disponíveis no momento, confira o repositório de servidores MCP.

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.
  • O Agente de codificação do Copilot atualmente só é compatível com servidores MCP locais. Para saber mais sobre os tipos de transporte, confira a documentação oficial do MCP.

Manter-se seguro com servidores MCP

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.

Recomendamos que você restrinja seus servidores a ferramentas somente leitura. Você pode usar a opção de configuração tools para expor apenas ferramentas conhecidas e seguras para Copilot.

Sobre a configuração de servidores MCP em um repositório

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.

Depois que os servidores MCP forem configurados para uso em um repositório, as ferramentas especificadas na configuração estarão disponíveis para o Agente de codificação do Copilot em cada tarefa atribuída.

Como criar sua configuração de MCP JSON

Você configura servidores MCP usando um formato JSON especial. O JSON deve conter um objeto mcpServers, em que a chave é o nome do servidor MCP (por exemplo, playwright) 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:

  • command (string): o comando a ser executado para iniciar o servidor MCP.
  • args (string[]): os argumentos a serem passados a command.
  • tools (string[]): as ferramentas do servidor MCP para habilitar. Você pode encontrar uma lista de ferramentas na documentação do servidor ou em seu código. Recomendamos que você coloque ferramentas específicas na lista de permitidos, mas também pode habilitar todas as ferramentas incluindo * na matriz.
  • type (string): campo opcional. O Agente de codificação do Copilot só aceita "local".
  • env (object): 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 do GitHub Actions que você configurou, começando com COPILOT_MCP_.
    • Um valor da cadeia de caracteres.

Configurações de exemplo

Exemplo: Playwright

O servidor MCP do Playwright fornece ferramentas que permitem que o Copilot navegue na Internet.

JSON
{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "mcp/playwright"],
      "tools": ["*"]
    }
  }
}

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": {
      "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 string...
        "SENTRY_HOST": "https://contoso.sentry.io",
        // or refer to a GitHub Actions secret with a name starting with
        // `COPILOT_MCP_`
        "SENTRY_AUTH_TOKEN": "COPILOT_MCP_SENTRY_AUTH_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": {
      "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: AKS (Serviço

O servidor MCP do Azure cria uma conexão perfeita entre o Copilot e os principais serviços do Azure, como o Azure Cosmos DB e a plataforma de Armazenamento do Azure.

Para usar o MCP do Azure com Agente de codificação do Copilot, atualize 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. Confira Usar a ação de logon do Azure com OpenID Connect.

  2. Adicione um arquivo de fluxo de trabalho .github/workflows/copilot-setup-steps.yml Actions em seu repositório se ainda não tiver um.

  3. Adicione uma etapa de logon do Azure ao trabalho de fluxo de trabalho do copilot-setup-steps.

    YAML
    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@a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0
        with:
          client-id: $
          tenant-id: $
          subscription-id: $

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

  4. No ambiente Copilot do seu repositório, adicione segredos para AZURE_CLIENT_ID, AZURE_TENANT_ID e AZURE_SUBSCRIPTION_ID.

  5. Configure o servidor MCP do Azure adicionando um objeto azure à configuração do MCP.

    JSON
    {
  "mcpServers": {
    "Azure MCP Server": {
      "command": "npx",
      "args": [
        "-y",
        "@azure/mcp@latest",
        "server",
        "start"
      ]
    }
  }
}

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 .vscode/mcp.json do repositório ou no arquivo settings.json privado do computador.

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

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

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

Como adicionar sua configuração ao 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. Abaixo do nome do repositório, clique em Configurações. 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 "Code &automation" da barra lateral, clique em Copilot e em Agente do Copilot.

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

  5. Clique em Save (Salvar).

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

  6. Se o servidor MCP exigir uma chave ou segredo, adicione um segredo ao seu ambiente Copilot. Apenas os segredos com nomes que tenham o prefixo COPILOT_MCP_ 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.

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. Abaixo do nome do repositório, clique em Configurações. 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 copilot e clique em Configure environment.

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

  7. Dê ao segredo um nome que comece com COPILOT_MCP_, 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 uv e pipx, ou que precisem de etapas especiais de instalação, talvez seja necessário criar um arquivo de fluxo de trabalho de Ações copilot-setup-steps.yml para instalá-las. Para saber mais, confira Customizing the development environment for Copilot coding agent.

Como personalizar o servidor MCP do GitHub predefinido

O servidor MCP do GitHub está habilitado por padrão, dando a Copilot acesso a dados GitHub como issues e pull requests.

Por padrão, o servidor MCP se conecta ao GitHub com um token com escopo especial que 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 Gerenciar seus tokens de acesso pessoal.

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

  3. Abaixo do nome do repositório, clique em Configurações. 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 "Code &automation" da barra lateral, clique em Copilot e em Agente do Copilot.

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

  6. Clique em Save (Salvar).

  7. Na barra lateral esquerda, clique em Ambientes.

  8. Clique no ambiente copilot.

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

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

Práticas recomendadas

  • Habilitar servidores MCP de terceiros para uso pode afetar o desempenho do agente e a qualidade das saídas. Examine completamente o servidor MCP de terceiros e verifique se ele atende aos requisitos da sua organização.

  • Por padrão, Agente de codificação do Copilot não tem acesso para gravar ferramentas de servidor MCP. No entanto, alguns servidores MCP contêm essas ferramentas. Examine as ferramentas que você deseja usar disponíveis no servidor MCP. Atualize o campo tools na configuração do MCP apenas com as ferramentas necessárias.

  • Examine com atenção os servidores MCP configurados antes de salvar a configuração para garantir que os servidores corretos estejam configurados para uso.

Leitura adicional