MCP Tools: Nine Operations, One Protocol

Local Brain exposes nine tools through the Model Context Protocol. Any MCP-compatible client — Claude Code, Claude Desktop, Cursor — discovers and uses them automatically. The user doesn't invoke tools directly. They say "remember this" or "what did I think about X" and the AI decides which tool to call.

The Core Four

capture_thought — The write path. Takes a content string and optional expiration (1–3650 days). The server generates an embedding via the configured API, extracts structured metadata via the chat API (type, topics, people, action items, dates), stores everything in PostgreSQL, and computes similarity links to existing thoughts. Returns a confirmation with metadata, linked thoughts, and the assigned ID.

search_thoughts — Semantic search. Takes a query string, embeds it, and finds the nearest neighbors by cosine distance. Returns results ranked by similarity percentage with full metadata. Supports filtering by archived status and respects user isolation.

list_thoughts — Browse with filters. Supports filtering by type (observation, task, idea, reference, person_note), topic tag, person mentioned, time range (last N days), and archived status. Paginated via limit parameter.

thought_stats — Aggregate view. Returns active/archived counts, type breakdown, top topics, people mentioned, connection count, and date range. All scoped to the authenticated user.

The Extended Set

get_thought_connections — Explore the similarity graph. Pass a thought ID to see what it's connected to, or call with no ID for the top connections across all thoughts. Each link has a similarity score. This is how you discover that a note you captured in January is 87% similar to something you thought about last week.

archive_thought — Soft delete. Archived thoughts are excluded from search and list by default but not removed from the database. Pass unarchive: true to restore. The admin panel shows archived thoughts with a dedicated filter.

export_thoughts — Full data export as JSON or Markdown. Respects user scoping. This is the anti-lock-in tool — your data is always portable. Every export is tracked for health monitoring (the system warns if you haven't exported in 90+ days).

usage_stats — AI API cost reporting. Shows total cost, token counts, and breakdowns by operation, model, and day. Helps answer "what does this memory layer cost me to run?"

system_health — Operational dashboard. Returns version (with update check against GitHub releases), database stats, backup schedule and last verification, export freshness, key age warnings, active notifications, and configuration summary. This is the tool an AI agent would call to proactively monitor the system.

Input Validation

All tool inputs go through Zod schemas with enforced limits:

content: max 50,000 characters
query: max 10,000 characters
expires_in_days: integer, 1–3650
limit: number with sensible defaults (10 for search/list, 50 for connections)

These limits prevent resource abuse — a malicious MCP client can't send a 100MB thought to exhaust memory or generate unbounded API costs.

User Isolation

Every tool respects the authenticated user's scope. User A's search only returns User A's thoughts. User B can't archive User A's thoughts. The global MCP access key (for backward compatibility) scopes to unassigned thoughts. This isolation is enforced at the SQL level — every query includes a user_id clause generated by the userScope() helper.

What Tools Don't Do