MCP 集成
使用 Model Context Protocol 将 Claude 等 AI 助手直接连接到心智层。
什么是 MCP 服务器？
Sonzai MCP 服务器将整个心智层 API 以工具的形式暴露出来，供 AI 助手直接使用。无需编写代码调用 REST API，只需配置 Claude Desktop 或 Claude Code 连接到 MCP 服务器，即可通过自然语言创建智能体、与其对话、管理记忆、 跟踪行为等。
该服务器实现了 Model Context Protocol 开放标准，提供 34 个工具、 4 个资源 和 3 个引导式提示。
快速入门
1. 构建 MCP 服务器
cd services/platform/api
go build -o sonzai-mcp ./cmd/mcp-server2. 设置 API 密钥
从 项目设置 获取 API 密钥，然后将其设置为环境变量：
export SONZAI_API_KEY=sk-your-api-key3. 连接到您的 AI 助手
选择适合您偏好客户端的配置：
客户端配置
// Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// or %APPDATA%/Claude/claude_desktop_config.json (Windows)
{
"mcpServers": {
"sonzai": {
"command": "/path/to/sonzai-mcp",
"env": {
"SONZAI_API_KEY": "sk-your-api-key"
}
}
}
}两种传输方式
stdio（默认）将服务器作为本地进程运行——最适合 Claude Desktop 和 Claude Code。 SSE 运行 HTTP 服务器，适用于远程或网络客户端。
配置
| 变量 | 必填 | 默认值 | 描述 |
|---|---|---|---|
| SONZAI_API_KEY | 是 | -- | 仪表板中的项目 API 密钥 |
| SONZAI_API_URL | 否 | https://api.sonz.ai | 平台 API 基础 URL |
命令行参数
| 参数 | 默认值 | 描述 |
|---|---|---|
| -transport | stdio | 传输类型：stdio 或 sse |
| -port | 8919 | SSE 传输端口（stdio 模式下忽略） |
可用工具（34 个）
MCP 服务器将其 34 个工具分为六个类别。每个工具直接映射到一个平台 API 端点。
智能体管理 (5)
| list_agents | 列出智能体，支持搜索和分页 |
| get_agent | 获取智能体详细信息（人格、能力、状态） |
| create_agent | 创建具有人格、大五人格、种子记忆和目标的智能体 |
| update_agent | 更新智能体配置文件（名称、人格、简介、问候语） |
| delete_agent | 永久删除智能体及所有数据 |
对话 (1)
| chat | 发送消息并获取包含完整上下文（记忆、心情、人格、关系）的响应 |
记忆 (5)
| get_memory | 获取分层记忆树 |
| search_memories | 自然语言记忆搜索 |
| list_facts | 按类型（档案、偏好、情感等）列出原子事实 |
| get_memory_timeline | 按时间排列的记忆时间线 |
| reset_memory | 删除所有记忆（不可逆） |
行为 (11)
| get_personality | 大五人格特质、BFAS 维度、交互偏好 |
| update_personality | 修改大五人格特质或行为特征 |
| get_mood | 四维情绪状态（效价、唤醒、紧张、亲和） |
| get_mood_history | 情绪随时间的变化 |
| list_goals | 活跃目标（成长、精通、关系、探索） |
| create_goal | 为智能体创建新目标 |
| update_goal | 更新目标状态或详情 |
| get_habits | 带强度评分的行为模式 |
| get_relationships | 亲密度评分、叙事、化学反应、关系状态 |
| get_interests | 带置信度的检测到的兴趣 |
| get_diary | AI 生成的日记条目 |
会话与状态 (5)
| start_session | 开始聊天会话以保持连续性和上下文 |
| end_session | 结束会话并触发记忆提取 |
| list_custom_states | 列出自定义键值条目 |
| upsert_custom_state | 创建/更新自定义状态（JSON 或文本） |
| get_custom_state | 按键获取自定义状态条目 |
生成与事件 (7)
| generate_character | 从文本描述生成完整角色 |
| generate_and_create_agent | 一步完成生成 + 创建智能体 |
| trigger_event | 触发影响情绪、记忆或行为的事件 |
| list_notifications | 列出主动通知 |
| schedule_wakeup | 安排主动触达（提醒、回访） |
| generate_bio | 为现有智能体生成传记 |
| list_voices | 列出可用的 TTS 语音 |
资源
资源提供 MCP 客户端可作为上下文访问的只读数据。使用 sonzai:// URI。
| URI | 描述 |
|---|---|
| sonzai://agents | 项目中的所有智能体 |
| sonzai://agents/{id}/profile | 智能体资料（人格、能力、状态） |
| sonzai://agents/{id}/memory | 记忆树快照 |
| sonzai://agents/{id}/personality | 大五人格特质、维度、偏好 |
引导式提示
提示是引导 AI 助手完成多步骤任务的预构建工作流。选择一个提示并提供所需参数。
create-companion
引导式工作流，用于创建具有丰富人格、背景故事和行为特征的 AI 伙伴。
参数：
concept-- 简要概念（例如："一个喜欢读塔罗牌的哲学咖啡师"）
工作流：
- 根据您的概念生成角色
- 审查人格特质、大五人格评分和背景故事
- 根据调整创建智能体
- 验证智能体已创建
analyze-agent
深入分析智能体的人格、情绪、记忆和关系。
参数：
agent_id-- 要分析的智能体 UUID 或名称
工作流：
- 收集资料、人格、情绪、关系、目标、习惯、兴趣、记忆、日记
- 提供包含身份、情绪状态、成长和建议的综合报告
mind-layer-setup
将 Sonzai 设置为任何 AI 助手的持久心智层。
参数：
assistant_name-- 您的 AI 助手名称personality_description-- 人格和沟通风格描述
工作流：
- 创建一个配置为心智层的智能体
- 启用持久记忆、人格演化、情绪追踪
- 提供在应用中使用对话、会话和记忆搜索的指导
使用示例
连接后，您可以在 Claude 中通过自然语言与心智层交互：
创建角色
"Use the create-companion prompt with concept "a wise old librarian who speaks in riddles and loves mystery novels""
与智能体对话
"Chat with agent "Luna" and say "I had a great day hiking in the mountains today!""
分析智能体
"Use the analyze-agent prompt for agent "Luna""
搜索记忆
"Search memories for agent "Luna" about "hiking adventures""
设置心智层
"Use mind-layer-setup with assistant_name "Aria" and personality_description "warm, curious, speaks with gentle encouragement""
架构
MCP 服务器是 MCP 客户端和平台 API 之间的薄翻译层。它将 MCP 工具调用转换为 HTTP 请求并返回结果。
Claude / AI Assistant
|
| MCP Protocol (stdio or SSE)
v
Sonzai MCP Server (Go binary)
|
| HTTP REST + SSE
v
Sonzai Platform API
|
+-- Context Engine (memory, personality, behavior)
+-- AI Service (LLM generation)
+-- ScyllaDB, Redis, CockroachDB仅限服务端
MCP 服务器需要您的 API 密钥，只应在受信任的机器上运行。切勿在没有适当身份验证的情况下将其暴露给不受信任的网络。