如何用 gh-aw 接入自定义 MCP Server：新手也能上手的完整配置教程

如何用 gh-aw 接入自定义 MCP Server：新手也能上手的完整配置教程

【免费下载链接】gh-awGitHub Agentic Workflows项目地址: https://gitcode.com/GitHub_Trending/gha/gh-aw

gh-aw（GitHub Agentic Workflows）让你用 Markdown 就能定义 AI 自动化工作流，并通过 GitHub Actions 安全运行 AI Agent。本文是一份面向新手的完整配置教程，带你逐步学会在 gh-aw 中接入自定义 MCP Server——只需在前置元数据（frontmatter）里加一段mcp-servers:配置，就能让 AI Agent 调用 Notion、DeepWiki、数据库等外部工具，且全程受沙箱与网关保护。

一、先搞懂：gh-aw 里 MCP Server 是怎么工作的

在 gh-aw 中，每个工作流由两部分组成：YAML frontmatter（配置触发器、权限、工具、AI 引擎）+ Markdown 正文（告诉 Agent 要做什么）。gh aw compile会把源文件编译成 GitHub Actions 可执行的.lock.yml。

接入 MCP Server 时有两个关键设计，新手务必了解：

• MCP Gateway 统一代理：所有 MCP 调用经一个网关中转，网关负责协议转换、服务器隔离、鉴权与健康检查（规范见 mcp-gateway.md）。
• 只读优先原则：自定义 MCP Server 应保持只读，所有写操作必须走 safe outputs 受控通道，Agent 默认运行在只读沙箱中。

官方 MCP 使用指南在 mcps.md，建议收藏。

二、前置准备：安装 gh-aw 并配好 Secrets

如果你的自定义 MCP Server 需要 Token（如 Notion、私有 API），先在仓库的Settings → Secrets and variables → Actions中创建对应的 Secret：

在 gh-aw 工作流中通过${{ secrets.NOTION_TOKEN }}这样的表达式引用即可，密钥不会明文出现在工作流文件里。

三、4 种 MCP Server 类型，按部署方式对号入座

在 frontmatter 的mcp-servers:下，每个服务名对应一种传输方式：

类型	字段	适用场景
Stdio 本地可执行	command+args	Python 模块、Node.js 脚本（如uvx、npx启动）
Docker 容器	container	打包好的本地服务，支持env、args（卷挂载）、entrypointArgs
HTTP 远程	url	远程服务，支持headers静态鉴权或auth动态 OIDC 令牌
注册表	registry	附带 GitHub MCP 注册表元数据，便于工具管理

四、三种最常见配置方式，直接抄作业

1️⃣ Docker 容器型（最常用）：适合需要环境变量与私有凭据的服务器。

mcp-servers: notion: container: "mcp/notion" env: NOTION_TOKEN: "${{ secrets.NOTION_TOKEN }}" allowed: - "search_pages" - "get_page" - "query_database"

2️⃣ HTTP 远程型：零部署成本，指向一个远程端点即可。以仓库自带的 DeepWiki 示例（deepwiki.md）为例：

mcp-servers: deepwiki: url: "https://mcp.deepwiki.com/sse" allowed: - read_wiki_structure - ask_question

3️⃣ 免部署捷径：直接导入共享配置。仓库内置了 20+ 份预配置的 MCP 规格（Jupyter、Serena、Sentry、Slack、Datadog 等），位于 shared/mcp/，用imports一行引入：

imports: - shared/mcp/deepwiki.md

五、关键安全项：用 allowed 白名单收紧权限

allowed:是 gh-aw 的看家功能——它在MCP 网关层强制生效，网关只会把白名单内的工具暴露给 Agent，与 AI 引擎、权限模式无关：

• allowed: ["*"]：放行全部工具（仅限你完全信任的公共只读服务）
• allowed: ["search_pages", "get_page"]：精确放行，推荐做法

另外两个进阶能力：

• OIDC 鉴权：远程服务器支持auth: { type: github-oidc }时，网关会自动换取短时 JWT 并注入Authorization头，无需长期 API Key（记得加permissions: { id-token: write }）。
• 内联 MCP 脚本：不想跑外部服务器时，可以用 mcp-scripts.md 里的mcp-scripts:直接用 JS/Shell/Python 写工具，轻量且天然隔离（同样只允许只读）。

六、编译、检查与调试三步走

配置完成后，按这个顺序验证：

1. 编译：gh aw compile my-workflow，校验 frontmatter 并生成.lock.yml。
2. 检查：gh aw mcp inspect my-workflow，确认工作流实际暴露了哪些服务器和工具；加--server <name> --verbose看单服务器细节。
3. 看工具：gh aw mcp list-tools <server> my-workflow列出某服务器的工具清单。

想更省事地加服务器，还有gh aw mcp add命令可直接从 GitHub MCP 注册表浏览并添加。

七、跑通之后：Agent 用起来是什么效果

接入 MCP 工具后，Agent 就能在任务里直接调用它们。比如下面这个工作流会调用外部文档问答工具，分析 Issue 并生成结构化评论：

常见故障速查（详见 mcps.md 的 Debugging 章节）：

现象	大概率原因	排查手段
连接失败	语法错误、Secret 未配置、网络域未放行	gh aw mcp inspect+ 检查network.allowed
工具缺失	不在toolsets或allowed白名单中	gh aw mcp list-tools对照确认
容器起不来	镜像名或args卷挂载顺序错误	注意卷挂载参数要放在镜像名之前

小结

接入自定义 MCP Server 的核心就三步：frontmatter 里声明mcp-servers→ 用allowed白名单限权 →gh aw mcp inspect验证。记住"自定义 MCP 只读、写入走 safe outputs"这条安全主线，你就能放心地把 Notion、知识库、监控面板等外部能力装进 gh-aw 的 AI 工作流，让 Agent 真正干起活来。🚀

【免费下载链接】gh-awGitHub Agentic Workflows项目地址: https://gitcode.com/GitHub_Trending/gha/gh-aw