MCP Integration

What is the MCP Server?

The Sonzai MCP server exposes the entire Mind Layer API as tools that AI assistants can use directly. Instead of writing code to call the REST API, you configure Claude Desktop or Claude Code to connect to the MCP server and it can create agents, chat with them, manage memories, track behavior, and more -- all through natural language.

The server implements the Model Context Protocol open standard and provides 34 tools, 4 resources, and 3 guided prompts.

Quick Start

1. Build the MCP Server

cd services/platform/api
go build -o sonzai-mcp ./cmd/mcp-server

2. Set Your API Key

Get an API key from your project settings, then set it as an environment variable:

export SONZAI_API_KEY=sk-your-api-key

3. Connect to Your AI Assistant

Choose the setup for your preferred client:

Client Setup

// 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"
    }
  }
}
}

Configuration

Command-Line Flags

Available Tools (34)

The MCP server groups its 34 tools into six categories. Each tool maps directly to a Platform API endpoint.

Agent Management (5)

• list_agents: List agents with search and pagination
• get_agent: Get detailed agent info (personality, capabilities, status)
• create_agent: Create agent with personality, Big5, seed memories, goals
• update_agent: Update agent profile (name, personality, bio, greeting)
• delete_agent: Permanently delete an agent and all data

Chat (1)

• chat: Send a message and get a response with full context (memory, mood, personality, relationships)

Memory (5)

• get_memory: Get hierarchical memory tree
• search_memories: Natural language memory search
• list_facts: List atomic facts by type (profile, preference, emotion, etc.)
• get_memory_timeline: Chronological memory timeline
• reset_memory: Delete all memories (irreversible)

Behavior (11)

• get_personality: Big5 traits, BFAS dimensions, interaction preferences
• update_personality: Modify Big5 traits or behavioral characteristics
• get_mood: 4D emotional state (valence, arousal, tension, affiliation)
• get_mood_history: Mood changes over time
• list_goals: Active goals (growth, mastery, relationship, discovery)
• create_goal: Create a new goal for the agent
• update_goal: Update goal status or details
• get_habits: Behavioral patterns with strength scores
• get_relationships: Love scores, narratives, chemistry, relationship status
• get_interests: Detected interests with confidence levels
• get_diary: AI-generated diary entries

Sessions & State (5)

• start_session: Start a chat session for continuity and context
• end_session: End session, triggering memory extraction
• list_custom_states: List custom key-value entries
• upsert_custom_state: Create/update custom state (JSON or text)
• get_custom_state: Get a custom state entry by key

Generation & Events (7)

• generate_character: Generate full character from text description
• generate_and_create_agent: Generate + create agent in one step
• trigger_event: Trigger an event affecting mood, memory, or behavior
• list_notifications: List proactive agent notifications
• schedule_wakeup: Schedule proactive outreach (reminders, check-ins)
• generate_bio: Generate a biography for an existing agent
• list_voices: List available TTS voices

Resources

Resources provide read-only data that MCP clients can access as context. They use sonzai:// URIs.

Guided Prompts

Prompts are pre-built workflows that guide the AI assistant through multi-step tasks. Select a prompt and provide the required arguments.

create-companion

Guided workflow to create an AI companion with rich personality, backstory, and behavioral traits.

Arguments:

• concept -- Brief concept (e.g., "a philosophical barista who reads tarot cards")

Workflow:

1. Generate character from your concept
2. Review personality traits, Big5 scores, and backstory
3. Create the agent with refinements
4. Verify the agent was created

analyze-agent

Deep analysis of an agent's personality, mood, memories, and relationships.

Arguments:

• agent_id -- Agent UUID or name to analyze

Workflow:

1. Gather profile, personality, mood, relationships, goals, habits, interests, memory, diary
2. Provide comprehensive report with identity, emotional state, growth, and recommendations

mind-layer-setup

Set up Sonzai as a persistent mind layer for any AI assistant.

Arguments:

• assistant_name -- Name for your AI assistant
• personality_description -- Description of personality and communication style

Workflow:

1. Create an agent configured as a mind layer
2. Enable persistent memory, personality evolution, mood tracking
3. Provide guidance for using chat, sessions, and memory search in your app

Usage Examples

Once connected, you can interact with the Mind Layer through natural language in Claude:

• Create a character: Use the create-companion prompt with concept "a wise old librarian who speaks in riddles and loves mystery novels"
• Chat with an agent: Chat with agent "Luna" and say "I had a great day hiking in the mountains today!"
• Analyze an agent: Use the analyze-agent prompt for agent "Luna"
• Search memories: Search memories for agent "Luna" about "hiking adventures"
• Set up a mind layer: Use mind-layer-setup with assistant_name "Aria" and personality_description "warm, curious, speaks with gentle encouragement"

Architecture

The MCP server is a thin translation layer between MCP clients and the Platform API. It converts MCP tool calls into HTTP requests and returns the results.

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