MCP Server

smartchats-mcp exposes the SmartChats data layer over the Model Context Protocol. Add it to Claude Desktop, Claude Code or any other MCP client and the model can read, search and write your logs, metrics, todos and knowledge graph, run read-only queries, and import or export your data.

It uses the same data path as the web app and the CLI. Each tool in src/tools.ts is a thin wrapper that calls a query builder from smartchats-database (or an operation such as operations.exportBundle) against the active DataAPI handle. There is no MCP-only data plane.

Install and run

cd packages/smartchats-mcp
npm run build
node dist/index.js --target=cloud   # or --target=local

You don’t usually run it by hand. Your MCP client starts it and talks to it over stdio.

Targets

The server picks its data target at startup with --target:

--target=cloud (the default): your SmartChats cloud account.
--target=local: your local SmartChats install.

For cloud, the server signs in before the protocol starts. It shares the CLI’s credentials file, ~/.smartchats-mcp/credentials.json, so one smartchats login covers both.

# Cloud
smartchats login                # one time
node dist/index.js --target=cloud
 
# Local
node dist/index.js --target=local

In local mode the server connects to SurrealDB at ws://localhost:8000/rpc (namespace smartchats, database main) and calls the local server at http://localhost:3000/local-api for embeddings. Override these with the --local-url, --local-ns, --local-db, --local-user and --local-password flags, or the matching SMARTCHATS_MCP_LOCAL_* variables (SMARTCHATS_MCP_LOCAL_SERVER_URL for the local server). Run node dist/index.js --help for the full list.

Add it to Claude Desktop

Build the server

cd packages/smartchats-mcp
npm run build

Add it to Claude Desktop’s config

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "smartchats": {
      "command": "node",
      "args": [
        "/absolute/path/to/smartchats/packages/smartchats-mcp/dist/index.js",
        "--target=cloud"
      ]
    }
  }
}

Replace the path with the path to your checkout. Use --target=local to point Claude at your local install instead of your cloud account.

Restart Claude Desktop. If you have not run smartchats login, the server starts a one-time browser sign-in. The URL appears in Claude Desktop’s MCP server logs. After that the cached refresh token renews the short-lived ID token on its own.

Use it

Ask Claude something like:

“Check my SmartChats logs from the last week and summarize what I’ve been thinking about.”

Claude calls get_recent_logs or search_logs, gets your data, and summarizes it.

Tools

The server registers 33 tools. Write tools stamp the event-time fields (ts, local_date, local_tz) for you. Tools that store text with an embedding (logs, entities, relations) embed it on insert, so callers never pass vectors.

Logs

Tool	What it does	Writes
`search_logs`	Substring search across logs, with an optional category filter	No
`semantic_search_logs`	Vector search across logs by meaning	No
`get_recent_logs`	Most recent logs, optionally by category	No
`get_log_categories`	Every category with its log count	No
`insert_log`	Add a log entry. `event_time_override` backfills an earlier date	Yes
`update_log`	Patch a log. Re-embeds when `content` changes	Yes
`delete_log`	Delete a log by id and return the deleted row	Yes
`prepare_log_category`	Register a category before it has any entries	Yes

Metrics

Tool	What it does	Writes
`get_metrics`	Metric values, filtered by name, category or date range	No
`get_metrics_summary`	Every tracked metric with units, counts, min/max and its latest value	No
`insert_metric`	Record a metric value. `source` defaults to `mcp`	Yes
`update_metric`	Patch `value`, `category`, `note` or `source_text`	Yes
`delete_metric`	Delete a metric entry by id	Yes
`prepare_metric`	Register a metric before it has any values	Yes

Todos

Tool	What it does	Writes
`get_todos`	Todos, active by default or filtered by status	No
`insert_todo`	Add a todo with status `active`	Yes
`record_todo_completion`	Record a completion (for recurring todos). Leaves the status alone	Yes
`set_todo_status`	Set status to active, completed, cancelled or deferred	Yes
`reschedule_todo`	Change the due date, the recurrence rule, or both	Yes
`edit_todo`	Edit title, description, priority, category, due date, recurrence or metric link	Yes
`delete_todo`	Delete a todo. Does not delete its completions	Yes
`delete_todo_completions`	Delete every completion record of a todo	Yes

Knowledge graph

Tool	What it does	Writes
`query_knowledge_graph`	Find entities and relations by name	No
`semantic_search_entities`	Vector search across entity names	No
`semantic_search_relations`	Vector search across relation triples	No
`insert_kg_entity`	Add an entity. Re-inserting a name creates a duplicate	Yes
`insert_kg_relation`	Add a directed relation between two existing entities	Yes
`delete_kg_entity`	Delete an entity by name. Does not delete its relations	Yes
`delete_kg_relation`	Delete a relation by its composite name	Yes
`delete_kg_relations_touching`	Delete every relation that touches an entity	Yes

Queries and data movement

Tool	What it does	Writes
`run_query`	Raw SurrealQL, scoped to you. SELECT statements only	No
`export_user_data`	Write the active target’s data to a JSON bundle on disk	No (writes a local file)
`import_user_data`	Upsert a JSON bundle into a SurrealDB instance, by id	Yes

run_query rejects anything other than a read. To change data, use the write tools above.

export_user_data and import_user_data call the same operations.exportBundle and operations.importBundle as smartchats data export and smartchats data import. import_user_data accepts per-call overrides (target_url, target_namespace, target_database, target_user, target_password) and dry_run, so a server started with --target=cloud can import a bundle into a local install.

Semantic search needs an embedding endpoint. On the cloud target it uses your account. On the local target it calls the local server’s /local-api/embeddings/embed, so the local server must be running with an OpenAI key. The write tools that embed need the same.

Example calls

You ask: “Find logs about my morning routine.”

Claude calls:

{
  "tool": "search_logs",
  "args": { "query": "morning routine", "limit": 10 }
}

The server returns matching logs:

[
  { "id": "logs:abc", "category": "wellness", "content": "Morning routine: ...", "ts": "2026-04-30T13:00:00Z", "local_date": "2026-04-30", "local_tz": "America/Chicago" }
]

You ask: “What do I have related to project alpha?”

Claude calls:

{
  "tool": "query_knowledge_graph",
  "args": { "query": "project alpha", "limit": 20 }
}

The server returns matching entities and relations. If the name is not exact, semantic_search_entities finds close matches.

You ask: “How many logs do I have per category?”

Claude calls:

{
  "tool": "run_query",
  "args": {
    "query": "SELECT category, count() AS n FROM logs GROUP BY category"
  }
}

The server returns the counts. An UPDATE, DELETE or CREATE in the query is rejected.

Authentication

Cloud target: the server acts as you. Every read and write is scoped to your account, and the cloud enforces isolation between users.

Local target: a local install has one user. The server connects to your local SurrealDB directly with the root credentials.

How it fits

The MCP server is one more consumer of the shared data layer:

        ┌─────────────────────────────────────────┐
        │      Operations + query builders        │   shared
        │   smartchats-database/src/{operations,  │
        │                            queries}/    │
        └─────────────────────────────────────────┘
            ▲                  ▲                ▲
            │                  │                │
       smartchats         smartchats       smartchats-mcp
         web app             CLI                ▲
                                          stdio JSON-RPC
                                                ▲
                                     Claude Desktop, Claude Code, ...

A new query builder in smartchats-database/src/queries/ becomes an MCP tool with about ten lines in tools.ts. See Architecture for the full picture.

smartchats-mcp-bridge

smartchats-mcp-bridge is a different MCP server. smartchats-mcp gives a model your data. The bridge lets a coding agent (Claude Code, Codex, Gemini CLI, any MCP client) talk with you live through the SmartChats app, by text or voice. This is called patch-through.

The agent starts the bridge as a stdio subprocess. The bridge opens a WebSocket to the SmartChats relay with your cloud sign-in, and the relay delivers messages between the agent and your browser.

coding agent ──stdio MCP──► smartchats-mcp-bridge ──WSS──► relay ──► SmartChats app

It registers these tools:

Tool	What it does
`send_message_to_user`	Send you a message. Does not wait for a reply
`wait_for_message`	Block until you or a peer agent sends a message, or the timeout fires
`poll_messages`	Non-blocking read of retained messages since a timestamp
`ask_user`	Send a question and wait for your reply, in one call
`respond_and_wait`	Send a reply and wait for your next message. The tool to loop on in a conversation
`list_peers`	List your other connected agents
`send_message_to_peer`	Send a message to another of your agents

{
  "mcpServers": {
    "smartchats-patch-through": {
      "command": "node",
      "args": ["/absolute/path/to/smartchats/packages/smartchats-mcp-bridge/dist/index.js"],
      "env": { "SMARTCHATS_AGENT_LABEL": "claude-code @ my-laptop" }
    }
  }
}

SMARTCHATS_RELAY overrides the relay endpoint and SMARTCHATS_AGENT_MODEL adds a model hint to the agent list. The bridge needs a cloud sign-in (smartchats login).

On a machine running smartchats-hub, point agents at the hub instead. The hub holds one relay connection and one token for every agent, and keeps a durable inbox per agent. It exposes the same tool names. The bridge is the fallback for machines without a hub. See Hub and Relay.

Troubleshooting

⚠️

“Authentication failed” at startup: run smartchats login first. The MCP server and the CLI share one credentials file.

⚠️

Local target times out: your local install isn’t running. Start it with smartchats start, then check smartchats status.

Logs go to stderr. The server writes protocol messages to stdout and readable logs to stderr. To capture both while debugging, run node dist/index.js 2>&1 | tee mcp.log.

MCP Server

Install and run

Targets

Add it to Claude Desktop

Build the server

Add it to Claude Desktop’s config

Sign in once (cloud only)

Use it

Tools

Logs

Metrics

Todos

Knowledge graph

Queries and data movement

Example calls

Authentication

How it fits

smartchats-mcp-bridge

Troubleshooting

See also