MCP Integration

Connect AI assistants like Claude directly to the Mind Layer using the Model Context Protocol.

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

Two Transports

stdio (default) runs the server as a local process -- best for Claude Desktop and Claude Code. SSE runs an HTTP server for remote or networked clients.

Configuration

Variable	Required	Default	Description
SONZAI_API_KEY	Yes	--	Project API key from the dashboard
SONZAI_API_URL	No	https://api.sonz.ai	Platform API base URL

Command-Line Flags

Flag	Default	Description
-transport	stdio	Transport type: `stdio` or `sse`
-port	8919	Port for SSE transport (ignored in stdio mode)

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.

URI	Description
sonzai://agents	All agents in the project
sonzai://agents/{id}/profile	Agent profile (personality, capabilities, status)
sonzai://agents/{id}/memory	Memory tree snapshot
sonzai://agents/{id}/personality	Big5 traits, dimensions, preferences

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:

Generate character from your concept
Review personality traits, Big5 scores, and backstory
Create the agent with refinements
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:

Gather profile, personality, mood, relationships, goals, habits, interests, memory, diary
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:

Create an agent configured as a mind layer
Enable persistent memory, personality evolution, mood tracking
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

Server-Side Only

The MCP server requires your API key and should only run on trusted machines. Never expose it to untrusted networks without proper authentication.

Next Steps

• Read the API Reference for the full REST API that the MCP server wraps
• Follow the Integration Guide for SDK-based integration
• Explore Personality System and Memory & Context to understand what the tools control

← API Reference Personality System→