MCP Server

import { Tabs, TabItem } from ‘@astrojs/starlight/components’;

The Kiomon MCP server is a standard Model Context Protocol server that exposes your Kiomon brain to any MCP-capable client: Cursor, Claude Desktop, Windsurf, Cline/Roo, Zed, and more. Agents get a memory-native toolset — read, search, and write to your brain, with every write landing in your Review Inbox for approval.

Requirements

• A Kiomon API key (Settings → API Keys → Generate)
• An MCP-capable client
• Node 18+ (for npx)

Running the server

The server reads two inputs — the token and the API URL:

# Flags
npx -y @kiomon/mcp-server --token <your-kiomon-token> --url https://api.kiomon.com

# Or environment variables (recommended for client configs)
KIOMON_TOKEN=<your-kiomon-token> KIOMON_URL=https://api.kiomon.com npx -y @kiomon/mcp-server

KIOMON_URL defaults to http://localhost:8787 if omitted — handy when running your own deployment at that address.

Client quick configs

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

```json
{
  "mcpServers": {
    "kiomon": {
      "command": "npx",
      "args": ["-y", "@kiomon/mcp-server"],
      "env": {
        "KIOMON_TOKEN": "your-key",
        "KIOMON_URL": "https://api.kiomon.com"
      }
    }
  }
}
```

Restart Claude Desktop after editing.

</TabItem>
<TabItem label="Cursor">

Workspace file `.cursor/mcp.json` (or *Settings → Features → MCP*):

```json
{
  "mcpServers": {
    "kiomon": {
      "command": "npx",
      "args": ["-y", "@kiomon/mcp-server"],
      "env": {
        "KIOMON_TOKEN": "your-key",
        "KIOMON_URL": "https://api.kiomon.com"
      }
    }
  }
}
```

Trust the project when prompted, then confirm the Kiomon tools appear in the MCP list.

</TabItem>
<TabItem label="Windsurf">

File: `~/.codeium/windsurf/mcp_config.json`

```json
{
  "mcpServers": {
    "kiomon": {
      "command": "npx",
      "args": ["-y", "@kiomon/mcp-server"],
      "env": {
        "KIOMON_TOKEN": "your-key",
        "KIOMON_URL": "https://api.kiomon.com"
      }
    }
  }
}
```

</TabItem>
<TabItem label="Cline / Roo Code">

File: `cline_mcp_settings.json`

```json
{
  "mcpServers": {
    "kiomon": {
      "command": "npx",
      "args": ["-y", "@kiomon/mcp-server"],
      "env": {
        "KIOMON_TOKEN": "your-key",
        "KIOMON_URL": "https://api.kiomon.com"
      },
      "disabled": false,
      "autoApprove": [
        "search_memory",
        "get_memory",
        "get_workspace_context",
        "list_workspaces"
      ]
    }
  }
}
```

</TabItem>
<TabItem label="Generic / any MCP client">

Any MCP host that takes a stdio command + env:

```
command: npx -y @kiomon/mcp-server
env:
  KIOMON_TOKEN: <your-key>
  KIOMON_URL: https://api.kiomon.com
```

</TabItem>

The 8 tools

list_workspaces

Discover your workspaces (id, name, document count) and the workspace_id you need for everything else.

Param	Type	Required	Notes
—	—	—	No arguments

Agent guidance: call this first in any session to learn the workspace layout. If one workspace is dominant, cache its ID.

get_workspace_context

One-shot pre-flight orient: pinned memories, active Routines (procedural rules the user wants followed), topic-relevant Facts, and workspace stats.

Param	Type	Required	Notes
workspace_id	string	✅	From list_workspaces
topic	string	—	Surfaces the top facts about a topic

Agent guidance: call once up front before doing work in a workspace. It also reports pending Review Inbox items you may manage.

search_memory

Hybrid search (full-text + semantic) with clean snippets and friendly kind labels.

Param	Type	Required	Notes
query	string	✅	Keywords, phrases, or natural language
kind	string	—	Filter: semantic (Facts), procedural (Routines), episodic (Moments), reference (Files); comma-separated
workspace_id	string	—	Restrict search to a workspace
limit	number	—	Default 10, max 50

Agent guidance: use this FIRST before answering questions about topics the user may have saved.

get_memory

Fetch a memory or reference document in full — body, strength/decay stats, and 1-hop graph relations.

Param	Type	Required	Notes
id	string	✅	ID from search/results
include_relations	boolean	—	Include connected graph edges (default true)

Returns: kind (friendly label), source, created date, strength, confidence, pinned flag, tags, body, relations.

explore_memory_graph

Walk the knowledge graph from a starting memory; trace evidence trails.

Param	Type	Required	Notes
id	string	✅	Starting memory
relation	string	—	One of derived_from, supports, contradicts, related_to, precedes, follows, part_of
depth	number	—	1 or 2 hops (default 1)

reflect_session

Batch-commit learnings at the end of a session as pending drafts (1–25).

Param	Type	Required	Notes
workspace_id	string	✅	Target workspace
learnings[]	array	✅	Each: kind, title, body (+ optional excerpt, confidence, tags, source_refs, entities, claims, domain)

Each learning:

Field	Required	Notes
kind	✅	semantic (Teach it / a Fact), procedural (Automate it / a Routine), episodic (Log this / a Moment)
title	✅	Short title
body	✅	Full content
excerpt	—	Card subheading (the line under the title)
confidence	—	0–1
tags	—	Up to 20
source_refs	—	IDs of memories/docs derived from (wired as derived_from on approval)
entities	—	People/products/projects — skips Kiomon’s paid extraction when provided
claims	—	Verifiable facts — skips extraction when provided
domain	—	Topic label — skips extraction when provided

Why supply entities/claims/domain?

You, the agent, already understand the content you’re writing. Supplying these three fields makes memories immediately searchable and consolidatable (filters, graph, contradiction checks), and saves a paid AI extraction pass per memory. The receive-side schema maxes at 60 entities / 60 claims / 120-char domain.

draft_memory

Single-memory variant of reflect_session for one focused fact, rule, or event (same fields as a single learning + workspace_id).

manage_memory

Memory governance and feedback.

Param	Type	Required	Notes
id	string	✅	Target memory
action	string	✅	pin, unpin, archive, restore, forget, rate, approve, reject
value	number	only for rate	1 (useful) or -1 (not useful)

Actions:

• pin — exempt from decay, ranks top
• unpin — return to normal dynamics
• archive — soft-hide from retrieval (recoverable)
• restore — un-archive
• forget — permanent purge
• rate — ±1 feedback (requires value)
• approve — promote a pending Review Inbox draft to active memory
• reject — archive a pending draft

The review-inbox contract

Anything your agent writes via draft_memory / reflect_session becomes a pending_approval draft in the dashboard Review Inbox. Drafts are:

• Excluded from search_memory, listing, and RAG by default
• Never embedded into the vector index
• Promoted only by approve (dashboard or manage_memory)

Nothing you write becomes an active, retrievable memory until the user approves it. Design your agent loops around this: write drafts, tell the user what’s waiting for approval, and help them review.

Troubleshooting

Symptom	Fix
ERROR: No API token on start	Pass --token or set KIOMON_TOKEN
Tools don’t appear in client	Restart the client; confirm the server process is running ([Kiomon MCP] Connected)
401 on tool calls	Key revoked or wrong environment — regenerate in Settings → API Keys
Wrong workspace data	You passed no workspace_id or the wrong one — run list_workspaces first
Memory not found (404)	The memory may be archived or deleted — search again or check the Review Inbox

Testing the server

The package ships a built-in test client:

npm run build                                        # build first
npm run test:client -- --list                        # list tools & schemas
npm run test:client -- --tool search_memory --args '{"query":"fastapi"}'
npm run test:client -- --url http://localhost:8787 --token <key> --all