MCP Integration

The Mind Layer ships a hosted Streamable HTTP MCP endpoint at https://api.sonz.ai/mcp/memory/{agent_id}. Point any MCP-compatible client at it with your Sonzai API key — no local binary, no SSE port to expose, no Go toolchain.

The server implements the Model Context Protocol spec and exposes 34 tools, 4 resources, and 3 guided prompts (see Tool catalogue below).

What you need

1. A project API key — create one in your project settings.
2. An agent ID — create an agent via the dashboard, the SDK, or by running the create-companion MCP prompt after first connect.

Pick your client

# Single command — registers the hosted MCP server with Claude Code:
claude mcp add --transport http sonzai \
https://api.sonz.ai/mcp/memory/AGENT_ID \
--header "Authorization: Bearer $SONZAI_API_KEY"

# Pick scope with --scope:
#   local   (default) — only this project, private to you
#   project           — writes .mcp.json (commit to share with team)
#   user              — across every project (~/.claude.json)

# Confirm the registration:
claude mcp list

Authentication

The Bearer-key route is what every example above uses — it's pinned to a specific agent and your project API key is the only secret. The OAuth-mode route lets clients discover available agents via a picker UI; it's currently in beta and exposed at the /.well-known/oauth-authorization-server discovery endpoint.

Tool catalogue

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 — 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, …)
• get_memory_timeline — chronological memory timeline
• reset_memory — delete all memories (irreversible)

Behavior (11)

• get_personality / update_personality — Big5 traits, BFAS dimensions
• get_mood / get_mood_history — 4D emotional state and history
• list_goals / create_goal / update_goal — agent goals
• get_habits — behavioral patterns with strength scores
• get_relationships — love scores, narratives, chemistry
• get_interests — detected interests with confidence
• get_diary — AI-generated diary entries

Sessions & State (5)

• start_session / end_session — chat sessions for continuity and context
• list_custom_states / upsert_custom_state / get_custom_state — custom key-value entries

Generation & Events (7)

• generate_character — generate full character from text description
• generate_and_create_agent — generate + create in one step
• trigger_event — affect mood, memory, or behavior
• list_notifications / schedule_wakeup — proactive outreach
• generate_bio — biography for an existing agent
• list_voices — available TTS voices

Resources

Resources are read-only data exposed as MCP sonzai:// URIs.

Guided prompts

Pre-built workflows your assistant can invoke by name.

create-companion

Generate a fully-populated agent from a one-line concept.

Args: concept — e.g. "a philosophical barista who reads tarot cards".

analyze-agent

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

Args: agent_id — UUID or name.

mind-layer-setup

Provision Sonzai as a persistent mind layer for any AI assistant.

Args: assistant_name, personality_description.

Architecture

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

For air-gapped or stdio-only clients the optional sonzai-mcp binary sits on the user's machine and proxies stdio JSON-RPC ↔ HTTPS REST.