MCP API Reference

Rust MCP server · localhost:3721 · rooms as tools

loci exposes rooms and search as MCP tools. Any MCP-compatible client (Claude Code, Cursor, Zed) can call these tools to access your indexed conversations and room context.

---

Tool reference

Tool	Description	Parameters	Returns
loci_search	Search all indexed conversations	query: string, tags?: string[], room?: string, limit?: number	SearchResult[]
room_dev	Dev Room context + recent conversations	none	RoomContext
room_design	Design Room context	none	RoomContext
room_research	Research Room context	none	RoomContext
room_hatchery	Hatchery context	none	RoomContext
room_garden	Garden context + active plants	none	RoomContext
loci_get	Retrieve a specific locus by slug	slug: string	Locus
loci_crystallise	Create a new locus from a conversation	conversationId: string, name: string, room: string, tags?: string[]	Locus

---

loci_search

Search all indexed conversations. Returns ranked results with matched excerpts.

Parameters:

Name	Type	Required	Description
query	string	yes	Search query (supports fuzzy matching)
tags	string[]	no	Filter by tags
room	string	no	Filter by room (dev, design, research, hatchery, garden)
limit	number	no	Max results (default: 10)

Example invocation (Claude Code):

loci_search query="authentication flow" tags=["security"] limit=5

Example response:

{
  "results": [
    {
      "id": "conv-20260501-abc123",
      "title": "Debugging the auth redirect",
      "platform": "claude.ai",
      "room": "dev",
      "date": "2026-05-01T14:30:00Z",
      "excerpt": "...the **authentication** **flow** breaks when the session expires...",
      "score": 0.89,
      "tags": ["security", "auth"]
    }
  ],
  "total": 1
}

---

room_dev

Returns the Dev Room context file and recent conversations assigned to this room.

Parameters: none

Example invocation:

room_dev

Example response:

{
  "room": "dev",
  "context": "# Dev Room\n\nCurrent focus: payment webhook integration...",
  "recent": [
    {
      "id": "conv-20260503-xyz789",
      "title": "Webhook signature validation",
      "date": "2026-05-03T09:15:00Z",
      "turns": 12
    }
  ],
  "loci": [
    {
      "slug": "kafka-vs-sqs",
      "name": "Message queue decision: Kafka",
      "created": "2026-05-02T16:00:00Z"
    }
  ]
}

The context field contains the room's context.md file: this is the accumulated memory of the room.

---

room_design, room_research, room_hatchery, room_garden

Same signature as room_dev. Each returns the context and recent conversations for that room.

The Garden room additionally includes an activePlants field:

{
  "room": "garden",
  "context": "# Garden\n\nSlow synthesis space...",
  "recent": [...],
  "loci": [...],
  "activePlants": [
    { "name": "Invisible Proof", "status": "active" },
    { "name": "Political Voice", "status": "active" }
  ]
}

---

loci_get

Retrieve a specific locus by its slug.

Parameters:

Name	Type	Required	Description
slug	string	yes	The locus slug (filename without .locus)

Example invocation:

loci_get slug="kafka-vs-sqs"

Example response:

{
  "slug": "kafka-vs-sqs",
  "name": "Message queue decision: Kafka",
  "room": "dev",
  "created": "2026-05-02T16:00:00Z",
  "tags": ["architecture", "messaging"],
  "sourceConversation": "https://claude.ai/chat/abc123",
  "content": "# Message Queue Decision\n\nWe chose Kafka over SQS for the event pipeline..."
}

---

loci_crystallise

Create a new locus from an existing conversation.

Parameters:

Name	Type	Required	Description
conversationId	string	yes	The conversation to crystallise
name	string	yes	Human-readable name for the locus
room	string	yes	Target room (dev, design, research, hatchery, garden)
tags	string[]	no	Tags to apply

Example invocation:

loci_crystallise conversationId="conv-20260503-xyz789" name="Webhook signature validation" room="dev" tags=["security", "webhooks"]

Example response:

{
  "slug": "webhook-signature-validation",
  "name": "Webhook signature validation",
  "room": "dev",
  "created": "2026-05-03T10:00:00Z",
  "path": "~/.loci/loci/webhook-signature-validation.locus"
}

---

Wiring to your IDE

Claude Code

Add to ~/.claude/claude_code_config.json:

{
  "mcpServers": {
    "loci": {
      "command": "loci-server",
      "args": ["--port", "3721"]
    }
  }
}

Or if running via the Tauri app:

{
  "mcpServers": {
    "loci": {
      "url": "http://localhost:3721"
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "servers": {
    "loci": {
      "url": "http://localhost:3721",
      "tools": ["loci_search", "room_dev", "room_design", "room_research", "loci_get"]
    }
  }
}

Zed

Add to ~/.config/zed/settings.json:

{
  "assistant": {
    "mcp_servers": {
      "loci": {
        "command": "loci-server",
        "args": ["--port", "3721"]
      }
    }
  }
}

---

Type definitions

interface SearchResult {
  id: string;
  title: string;
  platform: "claude.ai" | "chatgpt.com" | "gemini.google.com";
  room?: string;
  date: string;       // ISO 8601
  excerpt: string;    // matched text with highlighting
  score: number;      // relevance score 0-1
  tags: string[];
}

interface RoomContext {
  room: string;
  context: string;    // contents of context.md
  recent: Conversation[];
  loci: LocusSummary[];
  activePlants?: Plant[];  // garden only
}

interface Locus {
  slug: string;
  name: string;
  room: string;
  created: string;
  tags: string[];
  sourceConversation?: string;
  content: string;
}

---

Server status

Check if the MCP server is running:

curl http://localhost:3721/health

Response: { "status": "ok", "version": "1.0.0" }

See Architecture for how the MCP server fits into the loci stack.