MCP Tool Reference
Twenty-two tools across six groups. Every call is automatically scoped to the project attached to your API key — you never pass an org or project ID.
Scope requirements below apply to API keys, and to OAuth connections, which
carry the permissions ticked on the consent screen. A key with an empty scope
list is unrestricted. Reading tools need wiki:read, and the two source
reads and the connector tools need source:read; wiki_guide, project_list and project_get
need no scope.
An organisation with task boards on also gets six board tools. They are described on Task boards.
| Group | Tools |
|---|---|
| Orientation | wiki_guide, wiki_getBrief |
| Pages | wiki_getPage, wiki_patchPage, wiki_updatePage, wiki_deletePage, wiki_listPages |
| Index | wiki_getIndex, wiki_updateIndex |
| Log | wiki_appendLog, wiki_getLog |
| Health | wiki_lint, wiki_rebuildGraph |
| Sources | wiki_listSources, wiki_getSource, source_upload, wiki_deleteSource, wiki_markSourceIngested |
| Projects | project_list, project_get, project_create, project_update |
Orientation
wiki_guide
Returns WitWiki's conventions, the read-before-write loop, and the tool list.
Call it once after connecting; each task then opens with wiki_getBrief.
Parameters: none.
Returns: guidance text.
wiki_getBrief
One call to orient on a task: the pages you should read, ranked by search,
recency, links and name, packed under a token budget. Each page comes with
its content and its version, so you can patch it without a second lookup.
Start here when you have a task; wiki_getIndex and wiki_getLog are for
the map.
| Parameter | Type | Required | Description |
|---|---|---|---|
task | string | yes | What you are about to do, in a sentence, e.g. "deploy the api safely" |
budget_tokens | integer | no | The most tokens to return; default 2000, at most 8000 |
Returns: task, budget_tokens, tokens, and pages, each with
path, title, version, tokens, score, age_days (how long since
the page last changed), author_kind (person or agent, whoever wrote it
last), content, and truncated when a long page was cut at a heading to fit
its share. It also names the project it read from, and carries a note on a
new wiki or when nothing matched the task.
After the pages, more names the other pages that matched but did not fit, most
relevant first, up to ten named in all with pages: each is a pointer with path, title, tokens
(what reading the whole page costs) and age_days, and no content. If the
pages above do not answer, read one with wiki_getPage. The pointers are not
counted in budget_tokens or tokens, which are for page content; more
is left out when there is nothing to name.
"more": [{"path": "about/deploy", "title": "Production Deploy", "tokens": 1840, "age_days": 6}]
Errors: an empty task is refused.
{"task": "deploy the api safely"}
Pages
wiki_getPage
Fetch a page by path.
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | yes | e.g. "concepts/llm-wiki" |
Returns: path, title, content, metadata, version, updated_at, created_at.
Errors: not found if the page does not exist. The refusal names up to three existing paths closest to the one asked for: the same name in another section, or a path a few characters away.
{"path": "architecture/auth"}
wiki_patchPage
Edit part of a page without resending it — the default way to change a page that exists. Anchors are verbatim, must match exactly once, and edits apply in order, all or nothing. Every response says how many tokens the patch saved against an overwrite.
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | yes | Page path |
base_version | string | yes | The version from the wiki_getPage you read |
ops | array | yes | replace_text {find, replace}, insert_after {find, content}, replace_section {heading, content}, append_to_section {heading, content} (adds to an existing section), create_section {heading, content} (a new section at the end) |
Returns: {applied, idempotent, version, previous_version, applied_ops, diff, tokens}. Scope: wiki:write.
Refusals (nothing written): VERSION_CONFLICT with the current version, who wrote since, and a diff; ANCHOR_NOT_FOUND with the nearest lines; AMBIGUOUS_ANCHOR with the matching line numbers; SECTION_EXISTS; INVALID_OP; BASE_VERSION_REQUIRED.
{
"path": "decisions/auth-approach",
"base_version": "3f9a1c0be2d4",
"ops": [{"op": "replace_text", "find": "15 min", "replace": "30 min"}]
}
wiki_updatePage
Create a page, or overwrite one entirely — use wiki_patchPage for anything
smaller than a rewrite. Parses [[wikilinks]] from the content and refreshes
the link graph in the same transaction.
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | yes | Page path |
title | string | yes | Human-readable title |
content | string | yes | Markdown body |
metadata | object | no | Free-form JSON |
expected_version | string | no | The version you read; a stale one is refused with VERSION_CONFLICT and a diff |
base_version | string | no | Another name for expected_version, as wiki_patchPage calls it; send one of the two |
Returns: the updated page, with its new version — plus a warning when it overwrote an existing page without expected_version. Scope: wiki:write.
{
"path": "decisions/auth-approach",
"title": "Auth Approach Decision",
"content": "# Auth Approach Decision\n\nShort-lived JWTs (15 min) with refresh tokens (7 days).\n\nSee also [[architecture/auth]].\n",
"metadata": {"status": "decided", "date": "2026-04-21"}
}
This overwrites the whole page. For anything smaller than a rewrite, use
wiki_patchPage above. Pass expected_version from the wiki_getPage you
read; a page that moved since is refused with VERSION_CONFLICT and a diff.
Without expected_version the write goes through and the result carries a
warning. path and title must both be non-empty.
wiki_deletePage
Delete a page and its outbound links. Links to it from other pages stay, and
wiki_lint reports them as dead links. Appends a log entry.
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | yes | Page path to delete |
Returns: a confirmation message. Scope: wiki:write.
Errors: not found if the page does not exist.
Prefer merging over deleting. After removing a heavily-linked page, run
wiki_rebuildGraph to prune stale edges, then wiki_lint to find what now
dangles.
Note that the REST equivalent, DELETE /api/pages/{path}, requires the admin
role — so the same credential can delete over MCP and be refused over REST. See
Concepts.
wiki_listPages
List, search, or filter pages.
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | no | Full-text search (PostgreSQL websearch_to_tsquery) |
prefix | string | no | Path prefix, e.g. "concepts/" |
limit | integer | no | Default 100, max 500 |
Returns: {pages: [...]} with path, title, version, tokens,
last_agent, updated_at, created_at.
With q, results are ranked by relevance. With prefix, they're filtered by
path and sorted by path. The two do not combine: when q is set, prefix is
ignored. With neither, you get the most recently updated pages, up to limit.
{"q": "authentication JWT refresh"}
{"prefix": "concepts/", "limit": 20}
Index
wiki_getIndex
Fetch the index page (always at path index).
Parameters: none.
Returns: the index page. Every project is seeded with one at creation, so this succeeds from the first call; not found means the index was explicitly deleted.
wiki_updateIndex
Create or replace the index.
| Parameter | Type | Required | Description |
|---|---|---|---|
content | string | yes | Full markdown content |
title | string | no | Defaults to "Index" |
Returns: the updated page. Scope: wiki:write.
Like wiki_updatePage, this replaces the entire page.
Log
wiki_appendLog
Append an entry to the chronological log.
| Parameter | Type | Required | Description |
|---|---|---|---|
summary | string | yes | One-line description |
kind | string | no | edit (default), ingest, query, or lint |
details | object | no | Arbitrary structured JSON |
Returns: the created entry. Scope: wiki:write.
{
"kind": "ingest",
"summary": "ingested RFC 9728 — OAuth protected resource metadata",
"details": {"source": "rfc9728.pdf", "pages_updated": ["architecture/oauth", "index"]}
}
wiki_getLog
Fetch recent log entries, newest first.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer | no | Default 100, max 500 |
Returns: {entries: [...]} with id, ts, kind, summary, details.
Health
wiki_lint
Find orphan pages (no inbound links) and dead wikilinks (targets that don't exist).
Parameters: none.
{
"orphans": ["path/to/orphan-page"],
"dead_links": [
{"source": "page/a", "target": "missing/page"}
]
}
Run it after a batch of edits, after renames, and whenever someone asks whether anything is broken. Aim for zero dead links; a handful of orphans is usually fine.
wiki_rebuildGraph
Re-parse every page and atomically rebuild the whole link graph.
Parameters: none.
Returns: {links_written: <int>, status: "ok"}. Scope: wiki:write.
wiki_updatePage keeps the graph current on its own, so this is for repair, not
routine use: after bulk renames, after deleting heavily-linked pages, or when
lint still reports dead links you believe you already fixed.
Sources
wiki_listSources
List uploaded sources for the project.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer | no | Accepted but not applied today: every source comes back, newest first |
Returns: {sources: [...]} with id, filename, content_type,
size_bytes, status, blob_key.
Anything with status other than ingested is outstanding work.
wiki_getSource
Fetch metadata for one source.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Source UUID |
Returns: the source record. Errors: if it does not exist or belongs to another project.
source_upload
Upload a file as a raw source.
| Parameter | Type | Required | Description |
|---|---|---|---|
filename | string | yes | Original filename |
content_type | string | yes | MIME type, e.g. "text/markdown" |
content | string | yes | Base64-encoded file content |
Returns: the created source record. Scope: source:write.
Standard and URL-safe base64 are both accepted. All three parameters must be non-empty. Because the payload travels inside a tool call, this suits documents rather than large binaries — the web uploader at /sources is the better path for anything sizeable.
wiki_deleteSource
Delete a source and its blob.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Source UUID |
Returns: {"deleted": "<id>"}. Scope: source:write.
Blob deletion is best-effort; the metadata record is removed either way.
wiki_markSourceIngested
Mark a source as ingested once its content is in the wiki.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Source UUID |
Returns: the source with status: "ingested". Scope: source:write.
Also appends an ingest-log event, which is what drives the live activity feed in the app. Nothing sets this flag for you: skip it and every future session will re-read the same document.
Projects
project_list
List all projects in the organisation. Parameters: none.
Returns: {projects: [...]} with id, org_id, slug, name,
created_at.
project_get
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Project UUID |
project_create
| Parameter | Type | Required | Description |
|---|---|---|---|
slug | string | yes | URL-safe identifier |
name | string | yes | Display name |
Scope: wiki:write.
{"slug": "research-2026", "name": "Research 2026"}
Creating a project does not move your key to it — keys stay bound to the project they were issued for.
project_update
Rename a project.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Project UUID |
name | string | yes | New display name |
Scope: wiki:write.
MCP resources
Read-only resources some clients can read directly, without a tool call:
| URI | Format | Contents |
|---|---|---|
wiki://index | text/markdown | The index page |
wiki://log | application/json | 100 most recent log entries |
wiki://page/{+path} | text/markdown | A page by path (slashes allowed) |
Example: wiki://page/concepts/llm-wiki