扩展 AI Agent 的能力边界:Axe 接入 MCP 服务器的完全指南
扩展 AI Agent 的能力边界:Axe 接入 MCP 服务器的完全指南
Axe 是一个轻量级 AI Agent 命令行工具:你用 TOML 文件定义专注的单一用途 Agent,就能从终端、管道、git hooks 或 cron 中随时触发。本文将带你完成 Axe 接入 MCP 服务器 的全部配置,只需在 Agent 配置里添加 3 个字段,即可让 Agent 调用外部 MCP 工具,快速扩展 AI Agent 的能力边界。
🧩 为什么 AI Agent 需要 MCP
MCP(Model Context Protocol)是一套让大模型安全调用外部工具的标准协议。Axe 内置了 read_file、run_command、web_search 等工具,但当你需要查询数据库、操作内部 API 或调用企业系统时,内置工具就不够用了。
Axe 作为 MCP 客户端,在启动时会:
- 连接 Agent 中声明的每个 MCP 服务器
- 通过
tools/list自动发现所有可用工具 - 把这些工具与内置工具一起交给大模型,由模型自主决定何时调用
整个过程无需写一行胶水代码。
⚡ 最快配置方法:3 个字段接入 MCP 服务器
在 Agent 的 TOML 配置中(位于 $XDG_CONFIG_HOME/axe/agents/),添加一个 [[mcp_servers]] 表即可:
[[mcp_servers]]
name = "my-tools"
url = "https://my-mcp-server.example.com/sse"
transport = "sse"
| 字段 | 必填 | 说明 |
|---|---|---|
name |
✅ | 服务器的可读标识,同一 Agent 内必须唯一 |
url |
✅ | MCP 服务器端点地址(http/https) |
transport |
✅ | "sse" 或 "streamable-http" |
headers |
❌ | HTTP 请求头,支持 ${ENV_VAR} 环境变量插值 |
配置字段的完整定义见 docs/src/tools/mcp.md 与 docs/src/configuration/agent-config.md。
💡 注意:Axe 目前只支持远程传输(
sse/streamable-http),不会像其他客户端那样拉起本地 stdio 子进程,这符合 Axe "执行器而非调度器" 的极简设计。
🔀 工具命名冲突规则
- 与内置工具同名:内置工具优先,MCP 工具会被静默跳过(
--verbose模式下会打印跳过日志) - 两个 MCP 服务器暴露同名工具:启动时直接报错,退出码
2,错误信息会同时指出两个服务器名称 - MCP 工具完全由
[[mcp_servers]]控制,不要写进tools字段——那个字段只管内置工具
这套路由与冲突检测逻辑实现在 internal/mcpclient/router.go,连接与会话管理在 internal/mcpclient/mcpclient.go。
🔐 用环境变量安全注入访问密钥
需要鉴权的 MCP 服务器,可在 headers 中使用 ${VAR} 语法引用环境变量:
[[mcp_servers]]
name = "my-tools"
url = "https://my-mcp-server.example.com/sse"
transport = "sse"
headers = { Authorization = "Bearer ${MY_TOKEN}" }
export MY_TOKEN="your-secret-token"
axe run my-agent
如果引用的环境变量未设置或为空,Axe 会以退出码 2 快速失败并明确提示变量名,避免带着无效凭证去连接服务器。
✅ 验证连接是否成功:dry-run 与 verbose 技巧
第一步,dry-run 检查配置(不建立任何真实连接):
axe run my-agent --dry-run
输出中会出现 --- MCP Servers --- 区块,逐行列出服务器名称、URL 和传输类型。
第二步,verbose 观察真实连接:
axe run my-agent --verbose
stderr 中会依次打印:
[mcp] Connecting to "local-mcp" ...
[mcp] "local-mcp" discovered 3 tool(s), registered 3
[mcp] Routing tool "mcp_echo" to server "local-mcp"
第三步,JSON 输出复核工具调用:加 --json 后,MCP 工具调用与内置工具一样出现在 tool_call_details 数组中,包含 name、input、output、is_error 字段,方便脚本化审计(见 cmd/run_mcp_integration_test.go 中的完整示例)。
🛠 常见问题排查清单
| 症状 | 退出码 | 原因与解法 |
|---|---|---|
| 启动即失败,提示连接错误 | 3 | 服务器不可达 / DNS / TLS / 握手失败;先手动确认 URL 可用,MCP 连接继承 --timeout 超时 |
提示 environment variable ... is not set |
2 | headers 引用的环境变量未导出 |
提示 tool collision between servers |
2 | 两个 MCP 服务器暴露了同名工具,改其一或只保留一个服务器 |
| 服务器可达但没有任何新工具 | 3 | tools/list 调用失败;检查传输类型是否与服务器实际提供的一致 |
工具返回 MCP tool returned no text content |
— | 服务器只返回了非文本内容,Axe 是纯文本 CLI,图片等内容会被忽略 |
完整设计决策与边界场景(如子 Agent 各自独立建立 MCP 连接、无重试机制等)可阅读规格文档 docs/plans/027_mcp_tool_support_spec.md。
📂 核心文件导航
- MCP 官方配置文档:docs/src/tools/mcp.md
- Agent 配置全字段参考:docs/src/configuration/agent-config.md
- MCP 客户端源码:internal/mcpclient/
- 环境变量插值实现:internal/envinterp/envinterp.go
- 项目总览与完整配置示例:README.md
- 示例 Agent(可复制改造):examples/
🎯 小结
接入 MCP 后,你的 Axe Agent 从"文件 + 命令"扩展到了任意外部工具生态:只需一段 [[mcp_servers]] 配置,--dry-run 验证、--verbose 调试、--json 审计,一套标准 Unix 工作流就能把 AI Agent 的能力边界推到多远算多远。
