MCP 集成

心智层提供托管的 Streamable HTTP MCP 端点： https://api.sonz.ai/mcp/memory/{agent_id}。把任意兼容 MCP 的客户端 指向它，再带上 Sonzai API 密钥即可 — 无需本地二进制、无需开放 SSE 端口、 无需 Go 工具链。

服务器实现 Model Context Protocol 规范，暴露 34 个工具、4 个资源 和 3 个引导式提示词 （参见下文 工具目录）。

你需要

1. 项目 API 密钥 — 在 项目设置 创建。
2. Agent ID — 通过仪表板或 SDK 创建一个 agent；如果还没有， 首次连接后运行 create-companion MCP 提示词即可生成。

选择客户端

# 单条命令 — 把托管的 MCP 服务器注册到 Claude Code:
claude mcp add --transport http sonzai \
https://api.sonz.ai/mcp/memory/AGENT_ID \
--header "Authorization: Bearer $SONZAI_API_KEY"

# 用 --scope 指定作用域:
#   local   (默认) — 仅当前项目，私有
#   project         — 写入 .mcp.json (提交以共享给团队)
#   user            — 全局 (~/.claude.json)

# 检查注册结果:
claude mcp list

鉴权

上面所有示例都使用 Bearer 密钥路径 — 锁定到某个 agent，使用项目 API 密钥 作为唯一秘密。OAuth 模式让客户端通过选择器 UI 发现可用 agent，目前处于 beta，通过 /.well-known/oauth-authorization-server 端点暴露。

工具目录

MCP 服务器把 34 个工具分成六个类别。每个工具直接对应一个 Platform API 端点。

Agent 管理 (5)

• list_agents — 列出 agents，支持搜索与分页
• get_agent — 获取详情 (人格、能力、状态)
• create_agent — 创建 agent (人格、Big5、种子记忆、目标)
• update_agent — 更新档案 (姓名、人格、bio、问候语)
• delete_agent — 永久删除 agent 与所有数据

对话 (1)

• chat — 发送消息并获取带完整上下文的回复 (记忆、情绪、人格、关系)

记忆 (5)

• get_memory — 获取层级化记忆树
• search_memories — 自然语言记忆搜索
• list_facts — 按类型 (profile, preference, emotion …) 列出原子事实
• get_memory_timeline — 按时序的记忆时间线
• reset_memory — 删除所有记忆 (不可逆)

行为 (11)

• get_personality / update_personality — Big5 特质、BFAS 维度
• get_mood / get_mood_history — 4D 情绪状态及历史
• list_goals / create_goal / update_goal — agent 目标
• get_habits — 行为模式与强度分数
• get_relationships — Love 分、叙事、化学反应
• get_interests — 检测到的兴趣与置信度
• get_diary — AI 生成的日记条目

会话与状态 (5)

• start_session / end_session — 用于上下文连贯性的会话
• list_custom_states / upsert_custom_state / get_custom_state — 自定义键值条目

生成与事件 (7)

• generate_character — 从文本描述生成完整角色
• generate_and_create_agent — 一步生成 + 创建
• trigger_event — 影响情绪、记忆或行为
• list_notifications / schedule_wakeup — 主动外联
• generate_bio — 为已有 agent 生成 bio
• list_voices — 可用 TTS 声音

资源

资源以 MCP sonzai:// URI 暴露只读数据。

引导式提示词

助手可按名调用的预制工作流。

create-companion

从一句话概念生成完整人设的 agent。

参数: concept — 例如 "a philosophical barista who reads tarot cards"。

analyze-agent

深入分析某个 agent 的人格、情绪、记忆与关系。

参数: agent_id — UUID 或名字。

mind-layer-setup

把 Sonzai 配置为任意 AI 助手的持久化心智层。

参数: assistant_name、personality_description。

架构

Claude Code · Cursor · ChatGPT · VS Code · Claude Desktop
         │
         │ Streamable HTTP (JSON-RPC 2.0)
         ▼
https://api.sonz.ai/mcp/memory/{agent_id}
         │
         ├─ Context Engine (memory, personality, behavior)
         ├─ AI Service (LLM generation)
         └─ ScyllaDB · Redis · CockroachDB

对于离网或仅 stdio 的客户端，可选的 sonzai-mcp 二进制运行在用户机器上， 将 stdio JSON-RPC 与 HTTPS REST 互相代理。