AuC MCP客户端教程:一行配置接入外部工具服务器,给AI装上新的手脚
AuC MCP客户端教程:一行配置接入外部工具服务器,给AI装上新的手脚
AuC(Agents-ufy-Core)是一个 Python 单智能体框架,它的 MCP 客户端(Model Context Protocol,模型上下文协议)让你只需在 settings.json 里加一小段配置,就能把外部工具服务器接入自己的 AI 智能体——查数据库、连 Jira、访问文件系统……统统变成 AI 可以直接调用的"手脚"。本教程带新手从零完成安装、配置、验证全流程,全程不到 3 分钟。
什么是 MCP,为什么 AuC 需要它
MCP 是 AI 与外部工具之间的"通用插头":工具服务器(MCP server)把自己的能力注册成一个个标准 tool,任何支持 MCP 的客户端都能发现和调用它们。
AuC 的 MCP 客户端实现在 auc/integration/mcp.py,核心机制一句话概括:
- 连接外部 MCP server,自动发现其全部工具;
- 工具统一注册为
mcp__<server>__<tool>命名,与本地工具走同一套 L1/L2/L3 权限裁决链(见 docs/tool-privilege.md); - 提供"连接器卡片"治理视图:传输方式、负责人、权限级别、允许/拒绝清单一目了然;
- 官方
mcpSDK 是可选依赖:没装或连接失败时安全降级,只告警、不注册任何工具,绝不影响主流程。
安装步骤:一条命令装好 MCP 支持
📦 从源码安装并启用 mcp 可选组件:
pip install -e ".[mcp]"
如果你已经装过 AuC,也可以直接升级:
pip install "ufy-auc[mcp]"
安装后 auc extras 可以查看所有可选组件。未安装 mcp SDK 时,AuC 会在日志中提示 未安装 MCP SDK;请 pip install -e '.[mcp]' 后重试,主功能照常运行。
配置方法:在 settings.json 中一行接入
AuC 的配置文件为 Claude Code 风格的 JSON(schema 参考 docs/schema/settings.schema.json),支持两种写法:顶层 mcpServers 映射,或 mcp.servers 列表。配置按作用域分层:全局 ~/.Au/AuC/settings.json、项目级 .auc/settings.json,自动合并生效。
场景一:接入本地 stdio 服务器(最常用)
比如接入一个命令行文件系统 MCP 工具 mcp-fs,在项目根目录创建 .auc/settings.json:
{
"mcpServers": {
"fs": {
"command": "mcp-fs",
"owner": "team",
"deny": ["rm*"]
}
}
}
command/args:启动本地 server 的命令与参数(args可省略);owner:标注负责人,方便团队协作治理;deny/allow:glob 工具黑名单/白名单,黑名单优先——示例中拒绝一切rm开头的工具。
完整测试用例可参考 tests/test_cli_mcp.py。
场景二:接入 HTTP 远程服务器
远端部署的 server 只需给一个 url,AuC 自动识别为 http 传输:
{
"mcpServers": {
"api": {
"url": "https://example.com/mcp",
"privilege": "L3",
"owner": "team-a"
}
}
}
privilege 控制权限级别(L1 只读 / L2 沙盒写 / L3 二次授权),默认 L2。需要鉴权的接口可通过 headers 传 Authorization 头。更多配置细节见 tests/test_mcp.py 与 auc/integration/mcp.py 中的 MCPServerConfig。
可选安全参数:sandbox_only 与 enabled
| 参数 | 说明 |
|---|---|
enabled |
设为 false 可临时停用某个 server |
sandbox_only |
默认 true,强制路径类参数做沙盒校验;仅当确认需要访问沙盒外资源时才显式关闭 |
transport |
显式指定 stdio 或 http(缺省时按有无 url 自动判断) |
验证连接:用 auc mcp list 查看连接器卡片
配置完成后,不需要等 AI 对话,先用 CLI 体检一遍。命令定义见 auc/cli.py:
# 列出已配置的 MCP server(连接器卡片)
auc mcp list --repo .
# 实际连接并拉取远端工具清单
auc mcp list --probe --sandbox ./my-project
# 以 JSON 输出,方便脚本处理
auc mcp list --probe --json
--probe 会真实连上每个 server,卡片里直接显示注册成功的工具数量与名称;连接失败则红色标出 error,定位问题不再靠猜。
Web UI 管理:可视化增删改 MCP 连接器
🖥️ 启动 Web UI 后(auc web --sandbox ./my-project),可以在设置面板里图形化管理 MCP 连接器:新增/编辑/停用 server、设置权限与白名单,保存时自动写入对应作用域的 settings.json。
面板后端由 auc/web/mcp_settings.py 实现,前端提交时会做规范化校验:server 名称不能为空且不含路径分隔符、http 必须给 url、stdio 必须给 command、重复名称会直接报错,从入口挡住脏配置。
接入之后:AI 如何调用这些工具
🚀 一切配置完成后,启动对话即可:
auc chat "用 fs 工具列出当前项目的目录结构"
对话启动时 AuC 会自动执行 auc/integration/mcp.py 中的 setup_mcp,把外部工具注册进工具表,成功时会提示 已接入 N 个 MCP 工具。此时 AI 看到的工具名形如 mcp__fs__read_file,调用时与本地工具一样经过权限裁决(L3 会触发 Telegram / QQ / Web 二次授权)。
另外,MCP server 暴露的资源(resources)可以直接用引用语法注入上下文:在对话中写 @mcp:fs:/path/to/file,AuC 会读取该资源内容附给模型。
常见问题速查
Q:日志提示"未安装 MCP SDK"?
执行 pip install -e ".[mcp]" 安装可选依赖后重试。
Q:某个 server 连接失败会拖垮整个对话吗? 不会。AuC 对每个 server 独立容错:连接失败只在该 server 的连接器卡片上记录 error,其余 server 与本地工具全部正常。
Q:工具名冲突或想限定 AI 只用部分工具?
用 allow 白名单精确圈定(支持 glob),deny 黑名单优先级最高;命名统一带 mcp__<server> 前缀,天然与本地工具隔离。
Q:配置写在哪里才能只对当前项目生效?
写入项目根目录 .auc/settings.json(项目作用域),全局配置放 ~/.Au/AuC/settings.json,两者自动合并。
小结
AuC 的 MCP 客户端把"接入外部工具"简化成了三件事:装依赖 → 写配置 → 跑 auc mcp list --probe 验证。stdio 与 HTTP 两种传输方式都支持,白名单/黑名单、权限分级、沙盒校验构成完整的安全护栏。现在就可以挑一个你常用的 MCP server 试手,给你的 AuC 智能体装上新手脚。