> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiwifs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP (Model Context Protocol)

> Connect Claude Code, Claude Desktop, Cursor, and other MCP clients to KiwiFS over stdio or Streamable HTTP, with 78 tools.

KiwiFS ships a built-in MCP server. Agents get the same operations as the REST API and web UI — read, write, search, query, restructure — as typed tools, and every write goes through the same pipeline (git commit, index update, live events).

## Choose a mode

The MCP server runs with one of two backends and one of two transports.

| | stdio (default) | Streamable HTTP |
| - | - | - |
| **In-process** (`--root`) | `kiwifs mcp --root ~/knowledge` | `kiwifs mcp --root ~/knowledge --http` |
| **Proxy** (`--remote`) | `kiwifs mcp --remote http://localhost:3333` | `kiwifs mcp --remote http://localhost:3333 --http` |
| **Built into the server** | — | `kiwifs serve` exposes `/mcp` on its own port |

* **In-process** opens the directory directly. Use it for a single local agent.
* **Proxy** talks to a running KiwiFS server over REST, so the agent shares the server's index, live events, and auth. Use it when the web UI or other agents work on the same knowledge base.
* **`kiwifs serve`** always mounts Streamable HTTP MCP at `/mcp` on the main port, next to the REST API. No extra process or flag is needed.

```bash Terminal theme={null}
# In-process over stdio
kiwifs mcp --root ~/knowledge

# Proxy to a running server, with an API key
kiwifs mcp --remote https://kiwi.example.com --api-key $KIWI_API_KEY

# Proxy to a non-default space
kiwifs mcp --remote https://kiwi.example.com --api-key $KIWI_API_KEY --space docs

# Standalone Streamable HTTP on port 8181 (endpoint /mcp, health check /health)
kiwifs mcp --root ~/knowledge --http --port 8181
```

`--root` and `--remote` are mutually exclusive, and exactly one is required. `--space` only applies with `--remote`. `--port` (default `8181`) requires `--http`. See [`kiwifs mcp`](https://docs.kiwifs.com/cli/commands#mcp) for every flag.

### Authentication

* **Proxy mode** sends `--api-key` to the server as `Authorization: Bearer <key>`.
* **HTTP transport** requires `Authorization: Bearer <key>` when the knowledge base's `.kiwi/config.toml` sets `[auth] type = "apikey"`. The key is `[auth] api_key`. Without API-key auth, the HTTP endpoint is open.

> [!WARNING]
>
> Put remote HTTP MCP behind TLS, and enable API-key auth before exposing it beyond localhost. MCP tools can write, delete, and restructure pages.

## Connect a client

> [tab] Claude Code
>
> ```bash Terminal theme={null}
> # Local, in-process
> claude mcp add kiwifs -- kiwifs mcp --root /path/to/knowledge
>
> # Running KiwiFS server, over HTTP
> claude mcp add --transport http kiwifs http://localhost:3333/mcp \
>   --header "Authorization: Bearer $KIWI_API_KEY"
> ```
>
> To share the setup with your team, commit a `.mcp.json` at the project root with the same `mcpServers` block shown in the Cursor tab.

> [tab] Claude Desktop
>
> Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`).
>
> ```json claude_desktop_config.json theme={null}
> {
>   "mcpServers": {
>     "kiwifs": {
>       "command": "kiwifs",
>       "args": ["mcp", "--root", "/path/to/knowledge"]
>     }
>   }
> }
> ```
>
> Use an absolute path to the `kiwifs` binary if Claude Desktop cannot find it on `PATH`.

> [tab] Cursor
>
> Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global).
>
> ```json .cursor/mcp.json theme={null}
> {
>   "mcpServers": {
>     "kiwifs": {
>       "command": "kiwifs",
>       "args": ["mcp", "--remote", "http://localhost:3333", "--api-key", "kiwi_sk_..."]
>     }
>   }
> }
> ```

> [tab] Windsurf
>
> Add to `~/.codeium/windsurf/mcp_config.json`.
>
> ```json mcp_config.json theme={null}
> {
>   "mcpServers": {
>     "kiwifs": {
>       "command": "kiwifs",
>       "args": ["mcp", "--root", "/path/to/knowledge"]
>     }
>   }
> }
> ```

> [tab] Any HTTP client
>
> Point the client at the Streamable HTTP endpoint and pass the API key as a bearer token.
>
> ```json mcp.json theme={null}
> {
>   "mcpServers": {
>     "kiwifs": {
>       "url": "http://localhost:3333/mcp",
>       "headers": { "Authorization": "Bearer kiwi_sk_..." }
>     }
>   }
> }
> ```

> [!TIP]
>
> For KiwiFS Cloud workspaces, `kiwifs connect <workspace>` prints or writes this config for you. See [KiwiFS Cloud](https://docs.kiwifs.com/guides/cloud.md).

## First calls

A good session starts with `kiwi_context`. It returns the schema, agent playbook, index, and rules in one call. From there:

1. Find pages with `kiwi_brief` (one token-budgeted context pack) or `kiwi_search_hybrid`.
2. Skim with `kiwi_peek` before paying for a full `kiwi_read`.
3. Write with `kiwi_write`, passing `if_match` (the ETag from `kiwi_read`) so you never overwrite someone else's edit.
4. Verify with `kiwi_lint`.

Write tools accept an optional `actor` (default `mcp-agent`) that is recorded in the git commit.

## Tool reference

The server registers **78 tools**. Every name is invoked exactly as listed. Parameters marked with `*` are required.

> [accordion] Files: read, write, and history (13)
>
> | Tool | Purpose | Key parameters |
> | - | - | - |
> | `kiwi_read` | Read a page, optionally resolving wiki links. | `path`\*, `resolve_links`, `metadata_only`, `if_not_etag` |
> | `kiwi_write` | Create or overwrite a page as one git commit. | `path`*, `content`*, `if_match`, `provenance`, `actor` |
> | `kiwi_append` | Append to a page atomically, with no read-modify-write race. | `path`*, `content`*, `separator` |
> | `kiwi_bulk_write` | Write several pages in one atomic commit. A stale `if_match` fails the whole batch. | `files`\* (`path`, `content`, `if_match`), `provenance` |
> | `kiwi_patch_frontmatter` | Set or remove frontmatter keys without resending the body. `null` removes a key. Keys you set are owned by you. | `path`*, `fields`*, `if_match`, `force` |
> | `kiwi_delete` | Delete a page. History stays in git. | `path`\* |
> | `kiwi_rename` | Move one page and respell every link to it. The destination must not exist. | `from`*, `to`*, `update_links` (default `true`) |
> | `kiwi_tree` | List files and folders with sizes. | `path`, `depth`, `include_permalinks` |
> | `kiwi_peek` | Title, frontmatter, first paragraph, links, backlinks, and outline in about 200 tokens. | `path`\* |
> | `kiwi_section` | Read one heading section by name (fuzzy) or 0-based index. | `path`\*, `heading`, `index` |
> | `kiwi_versions` | Git history for a page. | `path`\* |
> | `kiwi_changes` | Changes since a checkpoint. Store `last_seq` and pass it back as `since`. | `since`, `limit` |
> | `kiwi_view_refresh` | Regenerate a computed view page (`kiwi-view: true`). | `path`\* |

> [accordion] Search and retrieval (6)
>
> | Tool | Purpose | Key parameters |
> | - | - | - |
> | `kiwi_search` | BM25 full-text search with snippets. | `query`\*, `limit`, `offset`, `path_prefix`, `scope`, `recency_weight` |
> | `kiwi_search_semantic` | Vector similarity search. Requires a vector index. | `query`\*, `limit`, `threshold`, `scope` |
> | `kiwi_search_hybrid` | BM25 and vector results fused by Reciprocal Rank Fusion. Falls back to keyword-only without a vector index. | `query`\*, `limit`, `path_prefix` |
> | `kiwi_brief` | Assemble everything relevant to a question into one token-budgeted pack. Never summarizes; lists what did not fit. | `query`\*, `budget_tokens`, `max_pages`, `path_prefix` |
> | `kiwi_similar` | Pages structurally similar to a case, using a frontmatter similarity profile. | `path` or `vector`, `profile`, `k` |
> | `kiwi_eval` | Score retrieval quality (Hit Rate, MRR, Precision\@K, nDCG\@K) for FTS and semantic search. | `set` or `queries`, `exclude_prefix`, `top_k` |

> [accordion] Context and structured queries (4)
>
> | Tool | Purpose | Key parameters |
> | - | - | - |
> | `kiwi_context` | Schema, playbook, index, and rules in one call. Call it first. | — |
> | `kiwi_query` | Run a [DQL](https://docs.kiwifs.com/concepts/dql.md) query (`TABLE`, `LIST`, `COUNT`, `DISTINCT`). | `query`\*, `format` (`table`, `list`, `json`), `limit` |
> | `kiwi_query_meta` | Filter pages by frontmatter with `$.field=value` filters. | `filters`, `or`, `paths`, `sort`, `order`, `limit`, `offset` |
> | `kiwi_aggregate` | Group by a frontmatter field and compute `count`, `avg`, `sum`, `min`, `max`. | `group_by`\*, `calculate`, `where`, `path_prefix` |

> [accordion] Links and graph (8)
>
> | Tool | Purpose | Key parameters |
> | - | - | - |
> | `kiwi_backlinks` | Pages that link to a page. | `path`\* |
> | `kiwi_suggestions` | Semantically similar pages that are not linked yet. | `path`\*, `limit` |
> | `kiwi_embeddings` | Chunk texts and embedding vectors for a page. | `path`\* |
> | `kiwi_graph_analytics` | PageRank, components, orphans, hubs, topic clusters, and bridge pages. | `limit` (default 20) |
> | `kiwi_graph_centrality` | PageRank and betweenness for every page, with in and out degree. | `limit` |
> | `kiwi_graph_communities` | Louvain communities of topically related pages. | — |
> | `kiwi_graph_path` | Shortest wiki-link path between two pages. | `from`*, `to`* |
> | `kiwi_graph_walk` | One-hop neighborhood: outbound links, backlinks, siblings, hub score. | `path`\*, `include_siblings` |

> [accordion] Restructuring (4)
>
> Move, merge, split, retag, and edit many pages in one reviewed commit without breaking links. See [Restructuring](https://docs.kiwifs.com/concepts/refactor.md).
>
> | Tool | Purpose | Key parameters |
> | - | - | - |
> | `kiwi_refactor_plan` | Preview a manifest. Nothing is written. Returns the digest, errors, counts, and a page of moves and link edits. | `manifest`\*, `detail` (`summary`, `full`, `diff`), `offset`, `limit` (default 25, max 200) |
> | `kiwi_refactor_apply` | Apply a reviewed plan as one commit. If anything changed, nothing is written and the fresh plan comes back. | `manifest`*, `digest`*, `now` |
> | `kiwi_refactor_script` | Compute a manifest with a read-only Starlark program, then plan it. | `script`\* |
> | `kiwi_refactor_revert` | Undo a commit as a new commit. Previews without `digest`; refuses if later edits would be lost. | `commit`\*, `digest` |

> [accordion] Analytics, health, and activity (5)
>
> | Tool | Purpose | Key parameters |
> | - | - | - |
> | `kiwi_analytics` | Totals, health (stale, orphans, broken links, empty, no frontmatter), link coverage, recent updates. | `scope`, `stale_threshold` |
> | `kiwi_health_check` | Diagnostics and quality score for one page. | `path`\* |
> | `kiwi_velocity` | Hot spots, cold spots, bursts, and authorship from git history. | `period` (default `30d`), `limit`, `path_prefix` |
> | `kiwi_timeline` | Recent activity across all files. | `limit` (default 50, max 500), `offset`, `actor`, `type`, `path_prefix` |
> | `kiwi_feed` | JSON feed of recently updated pages. | `limit` (default 20) |

> [accordion] Authoring helpers (3)
>
> | Tool | Purpose | Key parameters |
> | - | - | - |
> | `kiwi_lint` | Check a page or raw content for structural issues: tables, fences, frontmatter, headings, Mermaid, and widget fence schemas. | `path` or `content` |
> | `kiwi_widget_reference` | List the [widget fences](https://docs.kiwifs.com/concepts/widgets.md) a page can draw, or describe one in full. Call it before writing a fence. | `name`, `examples` |
> | `kiwi_quiz` | Format a Kiwi Quiz callout, or check quizzes in markdown. Kinds: `single`, `multi`, `boolean`, `order`, `match`, `short`. | `kind`, `prompt`, `options`, `answer`, `items`, `pairs`, `content`, `path` |

> [accordion] Import, capture, and export (6)
>
> | Tool | Purpose | Key parameters |
> | - | - | - |
> | `kiwi_import` | Import records from a database, file, Notion, or Airtable; each record becomes a page. | `from`\*, `dsn`, `file`, `table`, `query`, `prefix`, `limit`, `dry_run` |
> | `kiwi_ingest` | Convert a PDF, DOCX, PPTX, Excel, HTML, or EPUB document to markdown via MarkItDown. | `file`\*, `split_mode`, `prefix`, `extract_keywords`, `convert_crossrefs` |
> | `kiwi_clip` | Clip a web page as a markdown page. | `url`\*, `title`, `tags`, `folder` |
> | `kiwi_cite` | Create a literature note at `papers/{bibtex_key}.md` from a DOI or arXiv ID. | `identifier`, `doi`, `arxiv_id` |
> | `kiwi_export` | Export pages to JSONL, CSV, or Parquet. | `format`\*, `path`, `columns`, `include_content`, `include_embeddings`, `limit` |
> | `kiwi_export_document` | Render markdown to PDF, HTML, slides, or a static site. | `format`*, `path`*, `theme`, `bibliography`, `csl_style`, `slide_format` |

> [accordion] Tasks and claims (6)
>
> | Tool | Purpose | Key parameters |
> | - | - | - |
> | `kiwi_eligible` | Unclaimed, unblocked `todo` tasks ranked by priority. | `limit` (default 10), `path_prefix` |
> | `kiwi_task_create` | Create a task page (`workflow: tasks`, `state: backlog`) and optionally claim it. | `title`\*, `description`, `assignee`, `priority`, `blocked_by`, `labels`, `claim` |
> | `kiwi_task_progress` | Append a timestamped note under `## Progress`. | `path`*, `message`* |
> | `kiwi_claim` | Claim a page for exclusive work. Fails if another agent holds it. | `path`*, `actor`*, `lease_duration` (default `30m`) |
> | `kiwi_release` | Release a claim. | `path`*, `actor`* |
> | `kiwi_claims_list` | Active claims and when they expire. | — |

> [accordion] Workflows (5)
>
> | Tool | Purpose | Key parameters |
> | - | - | - |
> | `kiwi_workflow_list` | List workflow definitions. | — |
> | `kiwi_workflow_get` | Get one workflow's states and transitions. | `name`\* |
> | `kiwi_workflow_save` | Create or update a workflow after validating it. | `name`*, `states`*, `transitions`\* |
> | `kiwi_workflow_advance` | Move a page to a new state if the workflow allows the transition. | `path`*, `target_state`* |
> | `kiwi_workflow_board` | Kanban board: pages grouped by state. | `name`\* |

> [accordion] Draft spaces (7)
>
> | Tool | Purpose | Key parameters |
> | - | - | - |
> | `kiwi_draft_create` | Open an isolated draft. Returns a `draft_id`. | `actor` |
> | `kiwi_draft_list` | List active drafts. | — |
> | `kiwi_draft_write` | Write a file inside a draft. | `draft_id`*, `path`*, `content`\* |
> | `kiwi_draft_read` | Read a file from a draft. | `draft_id`*, `path`* |
> | `kiwi_draft_diff` | Unified diff of a draft against main. | `draft_id`\* |
> | `kiwi_draft_merge` | Fast-forward merge a draft into main. | `draft_id`\* |
> | `kiwi_draft_discard` | Delete a draft and its changes. | `draft_id`\* |

> [accordion] Saved views (5)
>
> | Tool | Purpose | Key parameters |
> | - | - | - |
> | `kiwi_views_list` | List saved view definitions. | — |
> | `kiwi_views_get` | Get one view definition. | `name`\* |
> | `kiwi_views_save` | Create or update a view's query, layout, columns, filters, sort, and grouping. | `name`*, `query`*, `layout`, `columns`, `group_by` |
> | `kiwi_views_delete` | Delete a view. | `name`\* |
> | `kiwi_views_execute` | Run a view's query and return rows. | `name`\*, `limit`, `offset` |

> [accordion] Canvas (3)
>
> | Tool | Purpose | Key parameters |
> | - | - | - |
> | `kiwi_canvas_list` | List `*.canvas.json` files. | — |
> | `kiwi_canvas_read` | Read a canvas's nodes and edges. | `path`\* |
> | `kiwi_canvas_write` | Write a canvas JSON object. | `path`*, `content`* |
>
> Canvas generate, patch, query, and auto-layout are REST-only. See [Canvas API](https://docs.kiwifs.com/api/canvas.md).

> [accordion] Memory (3)
>
> | Tool | Purpose | Key parameters |
> | - | - | - |
> | `kiwi_remember` | Save an episode to `episodes/{YYYY-MM-DD}/{episode_id}.md`. | `content`\*, `scope`, `episode_id`, `tags` |
> | `kiwi_forget` | Mark a memory as superseded without deleting it. | `path`\*, `reason` |
> | `kiwi_memory_report` | Episodic files and whether any page cites them under `merged-from`. | `episodes_prefix`, `limit`, `offset` |

## Resources

Read-only MCP resources:

| URI | Description |
| - | - |
| `kiwi://schema` | `SCHEMA.md` (or a generated schema) for the knowledge base. |
| `kiwi://file/{path}` | Markdown content for a relative path. |
| `kiwi://tree/{path}` | Directory listing rooted at `{path}`. |
| `kiwi://refactor/plans/{digest}` | A full restructuring plan built in this session, for reading without paging through tool results. |
| `kiwi://refactor/raw-moves` | Moves made outside KiwiFS that left links behind, and the `relinks` manifest that repairs them. |

## Related

> [card] [Restructuring](https://docs.kiwifs.com/concepts/refactor.md)
>
> Move and merge pages without breaking links.

> [card] [Agent interface](https://docs.kiwifs.com/concepts/agent-interface.md)
>
> How MCP fits next to REST and filesystem mounts.

> [card] [Agent playbook](https://docs.kiwifs.com/concepts/agent-playbook.md)
>
> What `kiwi_context` returns and how to steer agents.

> [card] [CLI: kiwifs mcp](https://docs.kiwifs.com/cli/commands.md#mcp)
>
> Every flag for the MCP server command.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.