为 Custom agent 配置 MCP

Custom agent 的 mcp-servers 为该角色提供额外 MCP 服务。仓库级 MCP 对仓库任务共享，而角色内的服务器只对该角色可用。

YAML 结构

mcp-servers 是仓库 MCP JSON 的 YAML 表达形式。下面组合已核实的 Cloudflare 文档服务和角色工具字段：

---
name: cloudflare-docs-helper
description: "Answers implementation questions using Cloudflare documentation."
tools: ["read", "search", "cloudflare/*"]
mcp-servers:
  cloudflare:
    type: sse
    url: https://docs.mcp.cloudflare.com/sse
    tools: ["*"]
---

Read the relevant project files and consult Cloudflare documentation.
Explain the proposed approach and cite the documentation used.

服务器下的 tools 选择其提供的工具；profile 顶层 tools 再过滤角色最终可使用的内置及 MCP 工具。* 的作用范围取决于所在位置，不能互换解释。

类型与环境差异

stdio 为兼容其他工具会映射为云端的 local 类型。其他配置字段遵循仓库 MCP 格式。

mcp-servers 在 VS Code 和其他 IDE 的 Custom agents 中不使用；云端 profile 中能声明，不意味着把同一文件放进 IDE 后会启动这些服务器。

引用凭据

凭据需保存在组织或仓库的 Agents secrets/variables，名称使用 COPILOT_MCP_ 前缀。仓库 JSON 与角色 YAML 都支持：

$COPILOT_MCP_API_KEY
${COPILOT_MCP_API_KEY}
${COPILOT_MCP_API_KEY:-default}

角色 YAML 还支持以下额外语法：

env:
  API_KEY: ${{ secrets.COPILOT_MCP_API_KEY }}
  SERVICE_NAME: ${{ vars.COPILOT_MCP_SERVICE_NAME }}

上面是放在服务器配置内的 env 片段，不是完整 profile。不要把 YAML 专用的额外引用语法直接推定为仓库 JSON 同样支持。

处理顺序

默认服务器先处理，其次为 custom agent 配置，最后为仓库设置中的 MCP 配置；后一级可覆盖前一级相应设置。因此，调试时应同时检查角色文件与仓库 MCP 设置，不能只看 profile。

完成后通过会话日志验证服务器和工具是否可用。远程 OAuth、resources/prompts 和自主调用边界与云端 MCP相同，不因使用 custom agent 自动获得额外支持。