Archon 工作流节点级 MCP 服务器接入指南为 DAG 节点按需挂载外部工具【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon导读本文是 Archon 中「按节点挂载 MCPModel Context Protocol服务器」的完整技术指南覆盖从.archon/mcp/*.json配置文件编写、三种传输类型stdio / HTTP / SSE选型、环境变量展开规则到多服务器共存、MCP-Only 沙箱节点、连接失败处理与常见故障排查的全过程。读完本文你将掌握如何在 Archon 的 DAG 工作流中为单个节点精确声明外部工具GitHub、PostgreSQL、Slack、Brave Search 等让 AI 在运行该节点时自动拉起 MCP 服务器、结束后自动回收同时理解 Claude、Codex、Copilot 与 Pi/OpenCode 等 Provider 在该机制下的行为差异并学会用hooks、allowed_tools组合出只读分析、纯 MCP 沙箱等实战模式。什么是节点级 MCP核心设计在 Archon 的 DAG 工作流中每个节点都支持一个mcp字段用于把 MCP 服务器附着到单个节点上而不是全局。这是与「用户级 / 项目级 / 插件级」环境 MCP 最本质的区别mcp声明的服务器只在该节点执行期间存在。Claude 工作流节点默认排除环境中的用户 / 项目 / 插件 MCP只暴露其声明文件中的外部服务器再加上 Archon 在当前工作流适用时注入的受治理governed原生工具。Codex 是显式例外它的 SDK 会把声明的服务器追加到环境配置之上而不是替换它详见下文「Codex 环境 MCP 的叠加限制」。Provider 支持矩阵支持Claude、Codex、Copilot 工作流节点警告并忽略Pi 与 OpenCode 节点目前会对mcp字段给出警告并忽略。从源码结构看mcp字段在 dag-node.ts 中被定义为z.string().min(1, ...)即一个非空字符串路径节点配置在 dag-executor.ts 中被传入nodeConfig.mcp交给 Provider 翻译执行。快速开始一个最小可用示例创建 MCP 配置文件例如.archon/mcp/github.json{ github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_PERSONAL_ACCESS_TOKEN: $GITHUB_TOKEN } } }在工作流中引用它name: triage-issues description: Triage GitHub issues using MCP nodes: - id: triage prompt: List open issues and label them by priority mcp: .archon/mcp/github.json仅此两步即可生效节点运行时 MCP 服务器启动其工具对 AI 可见节点完成后服务器关闭。.archon/mcp/目录默认被 git 忽略见 .gitignore所以含密钥的配置文件不会进入版本库。配置文件格式详解MCP 配置文件是 JSON 对象每个键是服务器名值是服务器配置。支持三种传输类型stdio默认运行本地进程最常用HTTP连接远程 HTTP 端点SSEServer-Sent Events连接 SSE 端点。Archon 还接受通用包装格式{ mcpServers: { ... } }方便直接从其他导出 MCP JSON 的工具拷贝配置。底层解析实现在 packages/providers/src/mcp/config.tsnormalizeMcpConfig会剥离mcpServers包装层且不允许mcpServers与其他顶层键混用否则抛错MCP config cannot mix top-level mcpServers with other keys。stdio默认{ github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_PERSONAL_ACCESS_TOKEN: $GITHUB_TOKEN } } }字段类型必填说明typestdio否缺省时为 stdiocommandstring是要执行的可执行程序argsstring[]否命令参数envRecordstring, string否进程环境变量HTTP{ api: { type: http, url: https://mcp.example.com/v1, headers: { Authorization: Bearer $API_KEY } } }字段类型必填说明typehttp是必须为httpurlstring是HTTP 端点 URLheadersRecordstring, string否请求头SSEServer-Sent Events{ realtime: { type: sse, url: https://mcp.example.com/sse, headers: { Authorization: Bearer $SSE_TOKEN } } }字段类型必填说明typesse是必须为sseurlstring是SSE 端点 URLheadersRecordstring, string否请求头环境变量展开把密钥留在进程环境里env与headers字段的值支持$VAR_NAME与${VAR_NAME}两种引用形式在执行时从 Archon 的进程环境展开不是工作流 YAML 加载时。Codex 工作流节点还会把 codebase 作用域的 env vars 纳入展开来源——从源码看codex/provider.ts 调用loadMcpConfig时传入的是buildMcpEnvSource(requestOptions.env)即合并了 codebase 环境变量后的来源。{ db: { command: npx, args: [-y, mcp/server-postgres], env: { DATABASE_URL: ${DATABASE_URL}, POOL_SIZE: $DB_POOL_SIZE } } }规则匹配模式$UPPER_CASE_VAR或${UPPER_CASE_VAR}对应正则[A-Z_][A-Z0-9_]*只展开env与headers的值——command、args、url保持原样未定义变量会被替换为空字符串并显示警告Warning: Node X MCP config references undefined env vars: VAR_NAME展开发生在执行时刻而非工作流 YAML 加载时。底层实现位于 mcp/config.tsexpandEnvVarsInRecord用正则\$(?:\{([A-Z_][A-Z0-9_]*)\}|([A-Z_][A-Z0-9_]*))替换每个值未命中环境变量的名称会被收集进missingVars随后由各 Provider 以MCP config references undefined env vars: ...的形式上报警告Claude 见 claude/provider.tsCopilot 见 copilot/provider.ts。为什么用独立文件而不是内联 YAMLMCP 配置常含机密API Token、数据库 URL而工作流 YAML 会被提交进 git。把配置放到独立 JSON 文件后可以整体 gitignore或借助环境变量引用让密钥永不落入源码。单节点多服务器一个文件挂载多个工具单个配置文件可定义多个服务器节点执行时全部拉起{ github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_PERSONAL_ACCESS_TOKEN: $GITHUB_TOKEN } }, postgres: { command: npx, args: [-y, modelcontextprotocol/server-postgres], env: { DATABASE_URL: $DATABASE_URL } } }Provider 工具接线Claude 的自动通配符与 Codex 的叠加覆盖Claude自动添加mcp__server__*通配符Claude 节点会自动向allowed_tools追加工具通配符。例如服务器名为github与postgres时节点获得mcp__github__*mcp__postgres__*对应实现见 claude/provider.ts加载配置后生成mcpWildcards serverNames.map(name \mcp__${name}__*)并合并进options.allowedTools。**注意**若未声明mcp:Claude 工作流节点不会收到任何环境级或作者声明的 MCP 服务器Archon 仍可能为请求引擎能力的节点注入自身的受治理原生工具服务器如manage_run见 [claude/provider.ts](https://gitcode.com/GitHub_Trending/archon3/Archon/blob/66901430d26fffae66c1fd2a00091170c16af9b5/packages/providers/src/claude/provider.ts?utm_sourcegitcode_repo_files#L1519-L1530。此行为不会禁用CLAUDE.md、内置 agents 或文件系统定义的 agents。Codex作为 per-nodemcp_servers覆盖传入Codex 节点会把同一份 MCP 配置作为节点级mcp_servers覆盖传给 Codex SDK无需全局~/.codex/config.toml即可让服务器对单节点可用。实现上由buildCodexMcpConfigOverridescodex/provider.ts把服务器配置转换成 SDK 的{ mcp_servers: {...} }覆盖结构。MCP-Only 节点把 AI 关进「工具沙箱」对支持工具限制的 Provider把mcp与allowed_tools: []组合可以创建只能使用 MCP 工具、无法访问内置工具Bash、Read、Write 等的节点nodes: - id: query-db prompt: Find all users who signed up in the last 24 hours mcp: .archon/mcp/postgres.json allowed_tools: []这非常适合沙箱化——AI 只能通过 MCP 服务器交互既不能触碰文件系统也不能执行 shell 命令。注意Codex 目前不支持 Archon 的allowed_tools/denied_tools限制因此该模式仅对 Claude 节点生效见下文 Limitations 与 Troubleshooting 中对应的两行。连接失败处理MCP 服务器连接在节点开始执行时建立。如果工作流通过mcp:配置的服务器连接失败你会看到类似消息MCP server connection failed: github (failed)节点会继续执行只是缺少失败服务器的工具。遇到这种情况请检查配置文件路径、服务器命令与环境变量。Claude 的严格工作流配置会阻止未声明的用户 / 插件 MCP 启动因此它们的连接失败不会影响本次运行Codex 仍可能继承环境级服务器见下节。Codex 环境 MCP 的叠加限制Codex 的 SDK 把节点mcp:服务器作为追加式配置覆盖而非替换不声明mcp:时环境级服务器仍可能可用声明了文件时环境级与声明级服务器可能同时存在。mcp_servers{}无法清空继承项且当前 SDK 没有通配符 / 默认全局关闭控制。因此 Archon 不把 Codex 的mcp:描述为「排他工具边界」——它保留可运行的追加行为并如实上报限制而不是改写用户配置或拒绝工作流。这一点在 dag-executor.ts 的失败消息解析逻辑中也得到印证parseMcpFailureServerNames解析 SDK 的MCP server connection failed: a (status), b (status)消息并配合loadMcpConfigdag-executor.ts过滤出工作流声明的失败服务器上报给用户而用户级插件失败只进 debug 日志——这正是 Troubleshooting 表中「Plugin MCP missing from workflow output」一行的行为来源。实战工作流示例GitHub Issue 自动分诊name: triage-issues description: Fetch and label GitHub issues nodes: - id: triage prompt: | List all open issues in this repo. For each issue, add a priority label (P0-P3) based on: - P0: Security vulnerabilities, data loss - P1: Broken core functionality - P2: Important but not blocking - P3: Nice to have mcp: .archon/mcp/github.json数据库感知的代码变更name: schema-aware-feature description: Build features with live database context nodes: - id: inspect-schema prompt: List all tables and their columns in the database mcp: .archon/mcp/postgres.json allowed_tools: [] - id: implement command: implement-feature depends_on: [inspect-schema]多服务编排name: full-stack-fix description: Fix a bug using GitHub issues, database, and code nodes: - id: fetch-context prompt: Get issue details and related database schema mcp: .archon/mcp/all-services.json allowed_tools: [] - id: fix command: implement-fix depends_on: [fetch-context] - id: verify prompt: Run the relevant query to verify the fix depends_on: [fix] mcp: .archon/mcp/postgres.json allowed_tools: []结合 hooks 的只读分析节点把 MCP 与 hooks 组合创建可以查询外部服务、但无法修改代码库的节点nodes: - id: analyze prompt: Analyze our GitHub PR review patterns mcp: .archon/mcp/github.json hooks: PreToolUse: - matcher: Write|Edit|Bash response: hookSpecificOutput: hookEventName: PreToolUse permissionDecision: deny permissionDecisionReason: Analysis only — no code changes推送通知ntfy把工作流结果推送到手机部分内置工作流如archon-smart-pr-review包含可选的通知节点工作流完成时向手机发送推送通知。它由when:条件门控——未配置 ntfy 时节点被静默跳过archon-smart-pr-review是仓库内置工作流之一见 bundled-defaults.generated.ts。配置约 30 秒在手机上安装 ntfy 应用iOS / Android打开应用点「」订阅一个主题名如archon-yourname-a8f3x。把主题名当密码对待——知道它的人都能给你发通知在仓库中创建.archon/mcp/ntfy.json{ ntfy: { command: npx, args: [-y, ntfy-me-mcp], env: { NTFY_TOPIC: archon-yourname-a8f3x } } }完成。该文件已被 gitignore.archon/mcp/在.gitignore中主题名只留在本地。工作流中的运作方式工作流用 bash 节点检查配置文件是否存在- id: check-ntfy bash: test -f .archon/mcp/ntfy.json echo true || echo false depends_on: [last-work-node] - id: notify depends_on: [check-ntfy, last-work-node] when: $check-ntfy.output true mcp: .archon/mcp/ntfy.json allowed_tools: [] prompt: | Send a push notification summarizing what was accomplished. Keep it under 2 sentences. Use priority 3.若.archon/mcp/ntfy.json不存在check-ntfy输出falsewhen:条件跳过 notify 节点工作流照常运行。给自己工作流加通知把上述两个节点check-ntfy notify追加到任意 DAG 工作流末尾。notify 节点的 prompt 应引用上游节点输出如$synthesize.output来生成有意义的摘要。快速测试# 验证手机能收到通知 curl -d Hello from Archon ntfy.sh/YOUR_TOPIC_NAME # 运行带通知的工作流 bun run cli workflow run archon-smart-pr-review Review PR #123mcp vs allowed_tools/denied_tools vs hooks功能mcpallowed_tools/denied_toolshooks添加外部工具是否否移除内置工具否是是注入上下文否否是修改工具输入否否是仅限 MCP 沙箱mcpallowed_tools: []——限制Codex 工具限制—— Codex 节点支持mcp但 Archon 的allowed_tools/denied_tools限制仍被 Codex 忽略Haiku 模型—— Haiku 不支持工具搜索多工具懒加载你会看到警告。MCP 节点建议改用 Sonnet 或 Opus无加载时校验—— MCP 配置文件在执行时读取而非工作流 YAML 加载时。路径拼写错误要到节点运行时才暴露不支持内联配置—— MCP 配置必须放在独立 JSON 文件中不能内联进 YAML。这是有意设计让机密不进入受版本控制的工作流文件。需要补充说明的是mcp值本身会在 YAML 加载阶段被 trim见 dag-node.ts且在validate workflows资源校验阶段会提前检查文件存在性与 JSON 合法性见 validator.ts其中对不支持的 Provider 会给出 warningMCP servers are not supported by provider X — this will be ignored——静态校验只能前置发现「文件缺失 / JSON 非法」这类问题真正的环境变量展开与服务器启动仍发生在执行时。故障排查问题原因修复MCP config file not found路径错误或文件不存在检查相对仓库根目录cwd的路径MCP config file is not valid JSONJSON 语法错误用cat .archon/mcp/config.json \| python3 -m json.tool校验MCP config must be a JSON object顶层是数组或字符串用{ server-name: { ... } }包裹undefined env vars: VAR_NAME环境变量未设置导出该变量或加入你的.envMCP server connection failed服务器进程崩溃或 URL 不可达检查命令 / URL单独测试服务器Plugin MCP 未出现在工作流输出用户级插件 MCP 被过滤出工作流警告用--verbose运行并查看 Provider MCP 调试日志使用 Codex 时allowed_tools被忽略Codex Provider 尚不支持 Archon 工具限制不要依赖allowed_tools: []对 Codex 做沙箱Haiku 模型配 MCP 服务器Haiku 不支持工具搜索改用model: sonnet或model: opus寻找 MCP 服务器常用集成的主流 MCP 服务器GitHubmodelcontextprotocol/server-githubPostgreSQLmodelcontextprotocol/server-postgresFilesystemmodelcontextprotocol/server-filesystemSlackmodelcontextprotocol/server-slackGoogle Drivemodelcontextprotocol/server-gdriveBrave Searchmodelcontextprotocol/server-brave-search进一步阅读hooks 指南配合mcp实现工具级权限决策与上下文注入authoring-workflows 指南DAG 工作流节点的完整字段体系MCP 配置加载实现环境变量展开、mcpServers包装格式与错误信息的源码级定义Claude Provider 的 MCP 接线mcp__*通配符与缺失环境变量警告的生成逻辑。【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考