Sonzai Docs

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-server

2. APIキーの設定

プロジェクト設定からAPIキーを取得し、環境変数として設定します：

export SONZAI_API_KEY=sk-your-api-key

3. 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"
      }
    }
  }
}

2つのトランスポート

stdio（デフォルト）はサーバーをローカルプロセスとして実行します -- Claude DesktopおよびClaude Codeに最適です。 SSEはリモートまたはネットワーク接続されたクライアント向けのHTTPサーバーを実行します。

設定

変数必須デフォルト説明
SONZAI_API_KEYはい--ダッシュボードから取得したプロジェクトAPIキー
SONZAI_API_URLいいえhttps://api.sonz.aiプラットフォームAPIのベースURL

コマンドラインフラグ

フラグデフォルト説明
-transportstdioトランスポートタイプ: stdio または sse
-port8919SSEトランスポート用ポート（stdioモードでは無視されます）

利用可能なツール（34）

MCPサーバーは34のツールを6つのカテゴリにグループ化しています。各ツールはプラットフォーム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_mood4次元の感情状態（快感、覚醒、緊張、親和）
get_mood_history時間経過に伴うムード変化
list_goalsアクティブな目標（成長、習熟、関係、発見）
create_goalエージェントの新しい目標を作成
update_goal目標のステータスまたは詳細を更新
get_habits強度スコア付きの行動パターン
get_relationships愛情スコア、ナラティブ、相性、関係ステータス
get_interests信頼度レベル付きの検出された興味
get_diaryAI生成の日記エントリ

セッション＆ステート (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 -- 簡単なコンセプト（例：「タロットカードを読む哲学的なバリスタ」）

ワークフロー:

  1. コンセプトからキャラクターを生成
  2. パーソナリティ特性、ビッグファイブスコア、バックストーリーを確認
  3. 調整を加えてエージェントを作成
  4. エージェントが作成されたことを確認

analyze-agent

エージェントのパーソナリティ、ムード、記憶、関係性の詳細分析。

引数:

  • agent_id -- 分析するエージェントのUUIDまたは名前

ワークフロー:

  1. プロフィール、パーソナリティ、ムード、関係性、目標、習慣、興味、記憶、日記を収集
  2. アイデンティティ、感情状態、成長、推奨事項を含む包括的なレポートを提供

mind-layer-setup

Sonzaiを任意のAIアシスタントの永続的なマインドレイヤーとして設定します。

引数:

  • assistant_name -- AIアシスタントの名前
  • personality_description -- パーソナリティとコミュニケーションスタイルの説明

ワークフロー:

  1. マインドレイヤーとして設定されたエージェントを作成
  2. 永続的な記憶、パーソナリティの進化、ムードトラッキングを有効化
  3. アプリでのチャット、セッション、記憶検索の使用に関するガイダンスを提供

使用例

接続後、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キーが必要であり、信頼されたマシン上でのみ実行する必要があります。適切な認証なしに信頼されていないネットワークに公開しないでください。

次のステップ

← APIリファレンスOpenClaw統合→