小智 MCP 连接说明

什么是小智 Token？

小智 Token 是连接 MBE（米塞斯行为引擎）与小智终端的授权凭证。

反向 MCP 连接模式

小智采用反向连接模式，与传统的服务器-客户端模式相反：

┌─────────────────────────────────────────────────────────────────┐
│                    小智 MCP 连接架构                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  【传统模式】                                                   │
│  客户端 ──────────▶ 服务器                                      │
│  (小智)              (MBE)                                      │
│  ❌ 需要MBE有公网IP，小智才能连进来                             │
│                                                                 │
│  【小智反向MCP模式】                                            │
│  MBE客户端 ──────────▶ 小智云服务器 ◀────────── 小智终端       │
│  (主动连出)           (中转站)                 (物联网设备)     │
│  ✅ MBE无需公网IP，只要能访问外网即可                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Token 的具体作用

wss://api.xiaozhi.me/mcp/?token=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...
                              ↑
                           这是 Token

作用	说明
身份认证	证明 MBE 是这台小智设备的授权服务
设备绑定	Token 内含 `userId` 和 `agentId`，绑定特定设备
安全隔离	不同用户/设备的 Token 不同，互不干扰
有效期控制	Token 有过期时间（通常1年），可以撤销

Token 内容解析

Token 采用 JWT 格式，解码后的内容：

{
  "userId": 404681,           // 小智账户ID
  "agentId": 1213656,         // 智能体ID（你的小智设备）
  "endpointId": "agent_1213656",
  "purpose": "mcp-endpoint",
  "iat": 1768721973,          // 签发时间
  "exp": 1800279573           // 过期时间（约1年后）
}

为什么采用反向连接？

问题	传统方案	小智反向MCP方案
MBE 在内网	需要公网IP或内网穿透	✅ 不需要
小智是物联网设备	需要配置服务器地址	✅ 只配云端
安全性	暴露服务器端口	✅ 只出不进，更安全
NAT穿透	复杂	✅ 自动处理

连接流程

1. 用户在小智APP生成MCP Token
         ↓
2. 将Token配置到MBE管理界面
         ↓
3. MBE客户端(mbe-mcp-client)启动
         ↓
4. 主动连接到 wss://api.xiaozhi.me/mcp/?token=xxx
         ↓
5. 小智云服务器验证Token
         ↓
6. 建立WebSocket长连接
         ↓
7. 小智终端的请求通过云服务器转发到MBE

获取 Token 的步骤

方法一：小智APP

打开小智 APP
进入 设备设置 → MCP 配置
点击 生成接入地址
复制完整的 wss://api.xiaozhi.me/mcp/?token=... 地址

方法二：小智开放平台

登录小智开放平台
进入 我的设备 → MCP管理
创建新的 MCP 接入点
复制生成的 Token

在 MBE 中配置 Token

方法一：管理界面

访问 http://localhost:8000/api/knowledge/admin/ui
点击 🔗 小智连接 标签
粘贴完整的 WebSocket 地址
填写设备名称（如"卡卡"、"MM"）
点击添加

方法二：配置文件

编辑 knowledge_bases/xiaozhi_tokens.json：

{
  "tokens": [
    {
      "id": "user_xxx",
      "name": "我的小智",
      "endpoint": "wss://api.xiaozhi.me/mcp/?token=eyJ...",
      "enabled": true
    }
  ]
}

多设备支持

MBE 支持同时连接多个小智设备：

{
  "tokens": [
    {
      "id": "user_50cde7a8",
      "name": "卡卡",
      "endpoint": "wss://api.xiaozhi.me/mcp/?token=...",
      "enabled": true
    },
    {
      "id": "user_03663817",
      "name": "MM",
      "endpoint": "wss://api.xiaozhi.me/mcp/?token=...",
      "enabled": true
    }
  ]
}

每个设备独立连接，互不干扰。

常见问题

Q: Token 过期了怎么办？

A: 在小智APP重新生成新的MCP接入地址，然后在MBE管理界面更新即可。

Q: 可以多人共用一个Token吗？

A: 不建议。每个Token绑定特定设备，共用可能导致消息混乱。

Q: MBE重启后需要重新配置吗？

A: 不需要。Token保存在 xiaozhi_tokens.json 文件中，重启后自动加载。

Q: 如何检查连接状态？

A: 查看 mbe-mcp-client 容器日志：

docker logs mbe-mcp-client --tail 20

正常状态会显示 Received message: {"method": "ping"} 的心跳消息。

安全建议

不要分享 Token - Token 相当于设备密码
定期检查 - 在小智APP查看MCP连接状态
及时撤销 - 如果Token泄露，立即在小智APP撤销并重新生成
使用HTTPS - Token传输应通过加密通道

文档版本: v1.0
最后更新: 2026-01-20