AuC MCP客户端教程:一行配置接入外部工具服务器,给AI装上新的手脚

原创2026-10-15 09:03:431,636 阅读

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);
  • 提供"连接器卡片"治理视图:传输方式、负责人、权限级别、允许/拒绝清单一目了然;
  • 官方 mcp SDK 是可选依赖:没装或连接失败时安全降级,只告警、不注册任何工具,绝不影响主流程。

安装步骤:一条命令装好 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 智能体装上新手脚。

登录后查看全文
AuC