Estendendo o agente de nuvem do GitHub Copilot com o Protocolo de Contexto de Modelo (MCP)

Pré-requisito

Antes de configurar um servidor MCP para agente de nuvem Copilot, leia Protocolo de Contexto de Modelo (MCP) e agente na nuvem GitHub Copilot para garantir que você entenda os conceitos em torno de servidores MCP e agente de nuvem 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ção e corporativos também podem configurar servidores MCP como parte do agentes personalizados usando o frontmatter YAML. Para obter mais informações, consulte Configuração de agentes personalizados.

Aviso

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

Observação

* agente de nuvem Copilot só dá suporte a ferramentas fornecidas por servidores MCP. Ele não dá suporte a recursos ou prompts. * agente de nuvem Copilot atualmente, não dá suporte a servidores MCP remotos que aproveitam 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:

Em GitHub, acesse a página principal do repositório.
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.
Na seção "Código & automação" da barra lateral, clique em e depois em .
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.
Clique em Salvar.

Sua configuração será validada para garantir a sintaxe adequada.
Se o servidor MCP exigir uma variável, chave ou segredo, adicione uma variável ou segredo ao seu Copilot ambiente. Somente variáveis e segredos com nomes prefixados COPILOT_MCP_ estarão disponíveis para a configuração do MCP. Veja como configurar um Copilot ambiente para agente de nuvem Copilot.

Escrever uma configuração JSON para servidores MCP

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, sentry) 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 ],
      ...
    },
    ...
  }
}

{
  "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**

* 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. É 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. * type (string): agente de nuvem Copilot aceita "local", "stdio", "http"ou "sse".

          **Chaves específicas do MCP local**

* command (string): obrigatório. O comando a ser executado para iniciar o servidor MCP. * args (string[]): obrigatório. Os argumentos a serem passados a command. * env (object): 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 um dos seguintes:

Uma referência de substituição a um segredo ou variável em seu Copilot ambiente, como $COPILOT_MCP_API_KEY ou ${COPILOT_MCP_API_KEY}. Os nomes referenciados devem começar com COPILOT_MCP_.

Um valor de string literal.

      **Chaves específicas do MCP remoto**

        `url` (`string`): obrigatório. A URL do servidor MCP.

```
        `headers` (`object`): 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:
```
- Uma referência de substituição a um segredo ou variável em seu Copilot ambiente, como $COPILOT_MCP_API_KEY ou ${COPILOT_MCP_API_KEY}. Os nomes referenciados devem começar com COPILOT_MCP_.
- Um valor de string literal.

Observe que todos os campos string e string[], além de tools & type, dão suporte à substituição por uma variável ou segredo que você configurou em o seu Copilot ambiente.

Substituição de variável

Os seguintes padrões de sintaxe têm suporte para referenciar variáveis de ambiente configuradas em seu Copilot ambiente:

Sintaxe	Exemplo
`$VAR`	`$COPILOT_MCP_API_KEY`
`${VAR}`	`${COPILOT_MCP_API_KEY}`
`${VAR:-default}`	`${COPILOT_MCP_API_KEY:-fallback_value}`

Configurações de exemplo

Os exemplos abaixo mostram as configurações do servidor MCP para provedores diferentes.

```
        [Sentry](#example-sentry)
```
```
        [Notion](#example-notion)
```
```
        [Azure](#example-azure)
```

        [Cloudflare](#example-cloudflare)

        [Azure DevOps](#example-azure-devops)

        [Atlassian](#example-atlassian)

Exemplo: Sentry

O servidor MCP do Sentry fornece 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 string...
        "SENTRY_HOST": "https://contoso.sentry.io",
        // or refer to a variable or secret in your Copilot environment
        // with a name starting with `COPILOT_MCP_`
        "SENTRY_ACCESS_TOKEN": "$COPILOT_MCP_SENTRY_ACCESS_TOKEN"
      }
    }
  }
}

// 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 string...
        "SENTRY_HOST": "https://contoso.sentry.io",
        // or refer to a variable or secret in your Copilot environment
        // with a name starting with `COPILOT_MCP_`
        "SENTRY_ACCESS_TOKEN": "$COPILOT_MCP_SENTRY_ACCESS_TOKEN"
      }
    }
  }
}

Exemplo: Notion

O servidor NOÇÃO MCP fornece 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": ["*"]
    }
  }
}

// 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 compreender seus arquivos específicos do Azure e os 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 cloud-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": ["*"]
     }
   }
 }

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

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

Exemplo: Azure DevOps

O servidor MCP Azure DevOps cria uma conexão perfeita entre Copilot e seus serviços de Azure DevOps, incluindo itens de trabalho, pipelines ou documentação.

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

Configure o OIDC em um aplicativo Microsoft Entra, confiando em GitHub. Consulte Usar a ação de login do Azure com o OpenID Connect.
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.
Adicione um arquivo de fluxo de trabalho .github/workflows/copilot-setup-steps.yml Actions em seu repositório se ainda não tiver um.

Adicione uma etapa de login do Azure à tarefa de 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

# 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 azure/login ação seja executada quando agente de nuvem Copilot executada.

No ambiente do repositório Copilot, adicione segredos para o seu AZURE_CLIENT_ID e AZURE_TENANT_ID.
Configure o servidor MCP Azure DevOps adicionando um objeto ado à configuração do MCP com ferramentas definidas que você deseja usar agente de nuvem Copilot.

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", ...]
    }
  }
}

{
  "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", ...]
    }
  }
}

Exemplo: Atlassian

O servidor MCP atlassiano fornece Copilot acesso autenticado aos seus aplicativos Atlassian, incluindo Jira, Compass e Confluence.

Para obter mais informações sobre como autenticar no servidor MCP do Atlassian usando uma chave de API, consulte Configurar a autenticação por meio do token de API na documentação do Atlassian.

JavaScript

// If you copy and paste this example, you will need to remove the comments prefixed with `//`, which are not valid JSON.
{
  "mcpServers": {
    "atlassian-rovo-mcp": {
      "command": "npx",
      "type": "local",
      "tools": ["*"],
      "args": [
        "mcp-remote@latest",
        "https://mcp.atlassian.com/v1/mcp",
        // We can use the $ATLASSIAN_API_KEY environment variable which is passed
        // to the server because of the `env` value below.
        "--header",
        "Authorization: Basic $ATLASSIAN_API_KEY"
      ],
      "env": {
        // The value of the `COPILOT_MCP_ATLASSIAN_API_KEY` secret will be passed
        // to the server command as an environment variable
        // called `ATLASSIAN_API_KEY`.
        "ATLASSIAN_API_KEY": "$COPILOT_MCP_ATLASSIAN_API_KEY"
      }
    }
  }
}

// If you copy and paste this example, you will need to remove the comments prefixed with `//`, which are not valid JSON.
{
  "mcpServers": {
    "atlassian-rovo-mcp": {
      "command": "npx",
      "type": "local",
      "tools": ["*"],
      "args": [
        "mcp-remote@latest",
        "https://mcp.atlassian.com/v1/mcp",
        // We can use the $ATLASSIAN_API_KEY environment variable which is passed
        // to the server because of the `env` value below.
        "--header",
        "Authorization: Basic $ATLASSIAN_API_KEY"
      ],
      "env": {
        // The value of the `COPILOT_MCP_ATLASSIAN_API_KEY` secret will be passed
        // to the server command as an environment variable
        // called `ATLASSIAN_API_KEY`.
        "ATLASSIAN_API_KEY": "$COPILOT_MCP_ATLASSIAN_API_KEY"
      }
    }
  }
}

Reutilizando a configuração do MCP de Visual Studio Code

Se você já tiver configurado servidores MCP, VS Code, pode aproveitar uma configuração semelhante para agente de nuvem Copilot.

Dependendo de como VS Code está configurado, você poderá encontrar as configurações do MCP no arquivo do .vscode/mcp.json repositório ou no arquivo privado settings.json do computador.

Para adaptar a configuração para agente de nuvem Copilot, você precisará:

Adicione uma tools chave para cada servidor MCP, especificando quais ferramentas estarão disponíveis para Copilot.
Se você tiver configurou o inputs, alterne para usar env diretamente.
Se você tiver configurado um envFile, alterne para usar env diretamente.
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, VS Codeconsulte os VS Code documentos.

Configurando um Copilot ambiente para agente de nuvem Copilot

Alguns servidores MCP exigirão chaves ou segredos. Para maximizar o uso desses servidores em agente de nuvem Copilot, você pode adicionar informações confidenciais 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 Copilot ambiente para seu repositório.

Em GitHub, acesse a página principal do repositório.
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.
Na barra lateral esquerda, clique em Ambientes.
Clique em Novo ambiente.
Chame o novo ambiente de copilot e clique em Configure environment.
Em "Environment secrets", clique em Add environment secret.
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.

Crie um problema no repositório e atribua-o a Copilot.
Aguarde alguns segundos e Copilot deixe uma reação 👀 sobre o problema.
Aguarde mais alguns segundos e Copilot crie uma solicitação de pull, que será exibida na linha do tempo do problema.
Clique na solicitação de pull criada na linha do tempo e aguarde até que um evento "Copilot começou a trabalhar" seja exibido.
Clique em Exibir sessão para abrir os agente de nuvem Copilot logs.
Clique no botão de reticências (...) no canto superior direito do visualizador de log e depois clique em Copilot na barra lateral.
Clique na etapa Start MCP Servers para expandir os logs.
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 estão instaladas no GitHub Actions executor por padrão, como uv e pipxou que precisam de etapas especiais de instalação, talvez seja necessário criar um copilot-setup-steps.yml arquivo de fluxo de trabalho actions para instalá-los. Para obter mais informações, consulte Personalizando o ambiente de desenvolvimento para GitHub Copilot agente de nuvem.

Personalizando o servidor MCP interno GitHub

O GitHub servidor MCP é habilitado por padrão e conecta-se a GitHub com um token de escopo especial que possui apenas acesso de leitura ao repositório atual.

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

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 personal access tokens, consulte Gerenciar seus tokens de acesso pessoal.
Em GitHub, acesse a página principal do repositório.
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.
Na seção "Código & automação" da barra lateral, clique em e depois em .

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"
       }
     }
   }
 }

 // 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 o LEIAME na documentação do GitHub Servidor MCP Remoto.

Clique em Salvar.
Na barra lateral esquerda, clique em Ambientes.
Clique no ambiente copilot.
Em "Environment secrets", clique em Add environment secret.
Chame o segredo COPILOT_MCP_GITHUB_PERSONAL_ACCESS_TOKEN, insira o personal access token no campo "Valor" e, então, clique em Adicionar segredo.

Para obter informações sobre como usar o GitHub servidor MCP em outros ambientes, consulte Using the GitHub MCP Server in your IDE.

Próximas Etapas

        [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers)

        [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/create-custom-agents)

        [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-environment)

        [AUTOTITLE](/copilot/customizing-copilot/extending-copilot-chat-with-mcp)

Estendendo o agente de nuvem do GitHub Copilot com o Protocolo de Contexto de Modelo (MCP)

Neste artigo