小智AI接入 MCP:从零配置教程(附 xiaozhi 端点示例)
小智AI 接入 MCP 工具只需四步:① 注册 MCP Gateway 租户并登录控制台;② 在控制台「小智端点」页拿到你的 MCP 接入点(wss://…/mcp/?token=…);③ 在小智服务端把 mcp_endpoint 参数指向该地址;④ 对音箱说话即可调用已分配工具,全程无需自己部署 server。MCP Gateway 把多个 MCP 服务聚合为一个接入点,小智AI 只需连这一个地址。
想让小智AI(xiaozhi)语音助手用上计算器、日历、高德地图这些工具?关键一步是给它接上 MCP。本教程从概念讲到落地:MCP 是什么、小智的接入点机制、自部署与托管两种接法怎么选,全程无需写代码,约 10 分钟。
MCP 是什么?为什么语音助手需要它?
MCP(Model Context Protocol,模型上下文协议)是 Anthropic 于 2024 年底开源的开放协议,用来统一「大模型 / 智能体」与「外部工具」之间的连接方式。
把 MCP 想象成工具世界的 USB-C:过去每个助手接每个服务都要单独写一套接口;现在只要服务方实现一个 MCP Server、助手方实现一个 MCP Client,两边就能互通。
对小智这类语音助手,MCP 的价值在于工具按需发现:助手不需要提前内置「计算器怎么做」「高德地图怎么调」,而是在需要时向 MCP 服务发现并调用。
对小智说「算一下 12 乘 18」,助手内部会走一遍 工具发现 → 选择 → 调用 的流程,全程自动。
小智AI 的「MCP 接入点」机制是什么?
先理解小智的架构:xiaozhi-esp32-server 服务端通过配置 mcp_endpoint 参数,去连接一个「MCP 接入点」——这个接入点是一个中间层,小智只连它,各种工具由它背后挂载。
官方做法是自部署 mcp-endpoint-server 项目(GitHub:xinnan-tech/mcp-endpoint-server)。启动后你会拿到两个地址:
- 智控台配置地址:
http://你的ip:8004/mcp_endpoint/health?key=abc - 单模块接入地址:
ws://你的ip:8004/mcp_endpoint/mcp/?token=def
小智服务端把 mcp_endpoint 指向 ws 地址后,就能发现并调用背后的工具。
两种接法:自部署还是托管?
自部署 mcp-endpoint-server
- 优点:免费、数据完全在自己手里、可任意定制
- 缺点:要自己维护 Docker 服务、处理升级和故障;每次换工具都要改配置
用托管的 MCP 接入点(如小智MCP)
- 优点:免运维,注册就有接入点地址;工具由平台从模板分配(计算器、高德等一键装)
- 缺点:多一个第三方依赖
只想快速跑通、或不想折腾 Docker,用托管接入点最快;想深度定制或数据敏感,自部署更合适。
本教程先讲托管接法(最快跑通),自部署的细节可参考《小智AI接高德地图 MCP》那篇。
怎么用托管接入点接上小智?
第一步:注册账号并登录控制台
打开 MCP Gateway 登录页(/login),点底部「注册账号」,填用户名、邮箱、密码,再点邮箱右侧的「获取验证码」,把收到的 6 位数字填进「邮箱验证码」,勾选同意协议后提交。登录后进入控制台。
验证码 10 分钟内有效、只能用一次;同一邮箱 60 秒内只能发一封。没收到请先检查垃圾邮件箱。
第二步:拿到你的 MCP 接入点地址
进「小智端点」页,你会看到平台为你生成的接入点地址,形如:
wss://…/mcp/?token=xxxx
完整复制这段地址(注意带上 token)。
第三步:把小智服务端指向该地址
按你的部署方式二选一:
全模块部署(用智控台):管理员登录 → 「参数字典 → 参数管理」→ 搜索 server.mcp_endpoint → 粘贴接入点地址保存。
单模块部署(改配置):编辑 data/.config.yaml:
mcp_endpoint: wss://…/mcp/?token=xxxx
保存重启,日志出现「mcp接入点是 …」即连接成功。
第四步:对音箱说第一句话
对小智说「用计算器算一下 12 乘 18」。语音助手会调用计算器工具,把结果念给你听。
接好后怎么验证工具能用了?
按这个顺序排查最省事:
- 控制台「小智端点」页是否显示已连接
- 「应用」页里计算器等应用是否已分配且连接
- 「工具」页里该工具是否已启用
- 打开「调用审计」,看语音调用是否到达、返回了什么
语音调用和你在控制台「工具」页点「试运行」走的是同一条工具通道,只是来源标记不同(voice / console)。
工具一多,上下文怎么办?
工具超过几十个后,把全部描述一次性塞给语音助手会挤占对话质量。解法是技能渐进披露:
- 平时只上报每个技能的一句话简介
- 语音真正触发某技能时,才加载它的完整指令(SKILL.md)
这样助手记得更准、响应更快,也是多工具场景控制成本的关键。
常见问题
- 连不上接入点:检查 mcp_endpoint 填的是 ws:// 而非 http://;防火墙是否放行端口
- 工具没出现在语音里:确认应用已分配给本租户、工具已启用;在「应用」页看连接状态
- 调用报错:打开「调用审计」看具体错误;平台应用问题联系平台管理员
接入点地址带 token 相当于你的「钥匙」,不要泄露到公开仓库或群聊。