使用模型上下文协议 (MCP) 扩展 GitHub Copilot 云代理 - GitHub 文档

先决条件

在为 Copilot 云代理设置 MCP 服务器之前，请阅读模型上下文协议 (MCP) 与 GitHub Copilot 云代理，确保您了解关于 MCP 服务器和 Copilot 云代理的概念。

简介

作为仓库管理员，您可以为仓库内部使用配置 MCP 服务器。您需要使用 JSON 格式的配置文件来指定要使用的 MCP 服务器的详细信息，并将该 JSON 配置直接填写到 GitHub.com 上该仓库的设置中。

组织和企业管理员也可以通过使用 YAML 前置内容的自定义代理来配置 MCP 服务器。更多信息请参阅自定义代理配置。

警告

配置好 MCP 服务器后，Copilot 将能够自主使用该服务器提供的工具，且在使用前不会向您请求批准。

注意

Copilot 云代理仅支持 MCP 服务器提供的工具，不支持资源或提示。
Copilot 云代理目前不支持使用 OAuth 进行身份验证和授权的远程 MCP 服务器。

向仓库添加 MCP 配置

仓库管理员可按照以下步骤配置 MCP 服务器

在 GitHub 上，导航至仓库的主页面。
在仓库名称下方，点击 Settings。如果未看到 “Settings” 选项卡，请先点击下拉菜单，然后点击 Settings。
在侧边栏的 “Code & automation” 区域，点击 Copilot，随后点击 Cloud agent。
在 MCP 配置 部分添加您的配置。

本文后面的章节将说明如何编写需要在此处填写的 JSON 配置。
点击保存。

系统会验证您的配置，以确保语法正确。
如果您的 MCP 服务器需要变量、密钥或 secret，请在 Copilot 环境中添加相应的变量或 secret。仅以 COPILOT_MCP_ 为前缀的变量和 secret 会在 MCP 配置中可用。参见为 Copilot 云代理设置 Copilot 环境。

为 MCP 服务器编写 JSON 配置

您需要使用一种特殊的 JSON 格式来配置 MCP 服务器。JSON 必须包含一个 mcpServers 对象，其中键是 MCP 服务器的名称（例如 sentry），值是该服务器的具体配置对象。

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

配置对象可包含以下键：

本地和远程 MCP 服务器的必填键

tools (string[])：要启用的 MCP 服务器提供的工具。您可以在服务器的文档或代码中找到可用工具列表。强烈建议只白名单特定的只读工具，因为代理会自主使用这些工具且不会先征求您的批准。若想启用所有工具，可在数组中加入 *。
type (string)：Copilot 云代理接受的类型包括 "local"、"stdio"、"http" 或 "sse"。

本地 MCP 专用键

command (string)：必填。启动 MCP 服务器的命令。
args (string[])：必填。传递给 command 的参数。
env (object)：可选。传递给服务器的环境变量。该对象应将环境变量名称映射到以下任意一种形式：
- 对 Copilot 环境中 secret 或变量的替换引用，例如 $COPILOT_MCP_API_KEY 或 ${COPILOT_MCP_API_KEY}。被引用的名称必须以 COPILOT_MCP_ 开头。
- 字面字符串值。

远程 MCP 专用键

url (string)：必填。MCP 服务器的 URL。
headers (object)：可选。发送到服务器的请求所附加的 HTTP 头部。该对象应将头部键名映射到以下任意一种形式：
- 对 Copilot 环境中 secret 或变量的替换引用，例如 $COPILOT_MCP_API_KEY 或 ${COPILOT_MCP_API_KEY}。被引用的名称必须以 COPILOT_MCP_ 开头。
- 字面字符串值。

请注意，除 tools 和 type 外，所有 string 与 string[] 字段均支持使用您在 Copilot 环境中配置的变量或 secret 进行替换。

变量替换

以下语法模式可用于引用 Copilot 环境中配置的环境变量：

语法	示例
`$VAR`	`$COPILOT_MCP_API_KEY`
`${VAR}`	`${COPILOT_MCP_API_KEY}`
`${VAR:-default}`	`${COPILOT_MCP_API_KEY:-fallback_value}`

示例配置

以下示例展示了不同提供商的 MCP 服务器配置。

Sentry
Notion
Azure
Cloudflare
Azure DevOps
Atlassian

示例：Sentry

Sentry MCP 服务器为 Copilot 提供对 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"
      }
    }
  }
}

示例：Notion

Notion MCP 服务器为 Copilot 提供对 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": ["*"]
    }
  }
}

示例：Azure

Microsoft MCP 仓库包含 Azure MCP 服务器，使 Copilot 在进行代码更改时能够理解您 Azure 订阅中的特定文件和资源。

若想通过 copilot-setup-steps.yml 文件自动为仓库配置 Azure 身份验证（包括所需的 secret），请先在本地克隆该仓库，然后在仓库根目录运行 Azure Developer CLI 的 azd cloud-agent config 命令。

运行上述命令并合并生成的 Pull Request 后，即可在仓库中添加 MCP 配置。

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

示例：Cloudflare

Cloudflare MCP 服务器为您的 Cloudflare 服务创建连接，包括文档处理和数据分析。

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

示例：Azure DevOps

Azure DevOps MCP 服务器在 Copilot 与 Azure DevOps 服务之间建立无缝连接，涵盖工作项、流水线或文档等。

要在 Copilot 云代理中使用 Azure DevOps MCP 服务器，需在仓库的 copilot-setup-steps.yml 文件中加入 Azure 登录工作流步骤。

在 Microsoft Entra 应用中配置 OIDC，信任 GitHub。参见使用 OpenID Connect 的 Azure 登录操作。
为应用身份设置对 Azure DevOps 组织和项目的访问权限。参见添加组织用户并管理访问。
如果仓库尚未拥有 .github/workflows/copilot-setup-steps.yml 工作流文件，请新建该文件。

在 copilot-setup-steps 工作流作业中添加 Azure 登录步骤。

YAML

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.
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

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.
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

此配置可确保 Copilot 云代理运行时执行 azure/login 动作。

在仓库的 Copilot 环境中，为 AZURE_CLIENT_ID 与 AZURE_TENANT_ID 添加 secret。
通过在 MCP 配置中添加 ado 对象，并定义您希望 Copilot 云代理使用的工具，来配置 Azure DevOps MCP 服务器。

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

示例：Atlassian

Atlassian MCP 服务器为 Copilot 提供已认证访问您的 Atlassian 应用（包括 Jira、Compass 和 Confluence）。

有关使用 API Key 对 Atlassian MCP 服务器进行身份验证的更多信息，请参阅 Atlassian 文档中的使用 API Token 配置身份验证。

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

在 Visual Studio Code 中复用您的 MCP 配置

如果您已经在 VS Code 中配置了 MCP 服务器，可将类似的配置用于 Copilot 云代理。

根据 VS Code 的配置方式，您可能在仓库的 .vscode/mcp.json 文件或本机的私有 settings.json 文件中找到 MCP 设置。

要将配置适配到 Copilot 云代理，您需要：

为每个 MCP 服务器添加 tools 键，指定 Copilot 可使用的工具。
如果您使用了 inputs，请改为直接使用 env。
如果您使用了 envFile，请改为直接使用 env。
将 args 配置中对 inputs 的所有引用改为引用 env 中的环境变量。

有关 VS Code 中 MCP 的更多信息，请参阅 VS Code 文档。

为 Copilot 云代理设置 Copilot 环境

部分 MCP 服务器需要密钥或 secret。要在 Copilot 云代理中使用这些服务器，您需要在 Copilot 环境中添加相应的 secret，以确保这些 secret 能被正确识别并传递给已配置的 MCP 服务器。

您必须是仓库管理员才能为仓库配置 Copilot 环境。

在 GitHub 上，导航至仓库的主页面。
在仓库名称下方，点击 Settings。如果未看到 “Settings” 选项卡，请先点击下拉菜单，然后点击 Settings。
在左侧边栏，点击环境。
点击 New environment（新建环境）。
将新环境命名为 copilot，然后点击 Configure environment（配置环境）。
在 “Environment secrets”（环境 secret）下，点击 Add environment secret（添加环境 secret）。
为 secret 命名时使用以 COPILOT_MCP_ 开头的名称，填写 secret 值，然后点击 Add secret（添加 secret）。

验证您的 MCP 配置

完成 MCP 配置后，请进行测试以确保配置正确。

在仓库中创建一个 issue，并将其指派给 Copilot。
稍等几秒，Copilot 将在该 issue 上留下 👀 表情。
再等待几秒，Copilot 将创建一个 Pull Request，并显示在该 issue 的时间线中。
点击时间线中的创建的 Pull Request，直至出现 “Copilot started work” 时间线事件。
点击 View session（查看会话）打开 Copilot 云代理日志。
在日志查看器右上角点击省略号按钮（...），然后在侧边栏点击 Copilot。
点击 Start MCP Servers（启动 MCP 服务器）步骤以展开日志。
如果 MCP 服务器成功启动，您将在日志底部看到它们的工具列表。

如果您的 MCP 服务器依赖于在 GitHub Actions 运行器上默认未安装的组件（如 uv、pipx），或需要特殊的安装步骤，您可能需要创建 copilot-setup-steps.yml Actions 工作流文件以进行相应安装。更多信息请参阅自定义 GitHub Copilot 云代理的开发环境。

自定义内置的 GitHub MCP 服务器

GitHub MCP 服务器默认已启用，并使用仅对当前仓库具有只读权限的专属作用域 token 连接到 GitHub。

如果希望 Copilot 访问当前仓库之外的数据，可为其提供具有更广泛访问权限的个人访问令牌。

创建具备相应权限的个人访问令牌。我们建议使用精细化的个人访问令牌，以便将令牌的访问限制在特定仓库的只读权限上。有关个人访问令牌的更多信息，请参阅管理您的个人访问令牌。
在 GitHub 上，导航至仓库的主页面。
在仓库名称下方，点击 Settings。如果未看到 “Settings” 选项卡，请先点击下拉菜单，然后点击 Settings。
在侧边栏的 “Code & automation” 区域，点击 Copilot，随后点击 Cloud agent。

在 MCP 配置 部分添加您的配置。例如，您可以添加如下内容：

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

有关工具集的更多信息，请参阅 GitHub 远程 MCP 服务器文档中的 README。

点击保存。
在左侧边栏，点击环境。
点击 copilot 环境。
在 “Environment secrets”（环境 secret）下，点击 Add environment secret（添加环境 secret）。
将 secret 命名为 COPILOT_MCP_GITHUB_PERSONAL_ACCESS_TOKEN，在 “Value”（值）字段中输入您的个人访问令牌，然后点击 Add secret（添加 secret）。

有关在其他环境中使用 GitHub MCP 服务器的说明，请参阅在 IDE 中使用 GitHub MCP 服务器。

使用模型上下文协议（MCP）扩展 GitHub Copilot 云代理

本文内容

先决条件

简介

向仓库添加 MCP 配置

为 MCP 服务器编写 JSON 配置

变量替换

示例配置

示例：Sentry

示例：Notion

示例：Azure

示例：Cloudflare

示例：Azure DevOps

示例：Atlassian

在 Visual Studio Code 中复用您的 MCP 配置

为 Copilot 云代理设置 Copilot 环境

验证您的 MCP 配置

自定义内置的 GitHub MCP 服务器

后续步骤