MCP

Wikai runs a Model Context Protocol (MCP) server so agents — the built-in chat sidebar, or an external tool like Claude Code in a terminal — can read and work with your wiki through a defined set of tools. External HTTP connections require Wikai’s bearer token (since 0.5.0), and the endpoint stays the same across restarts (since 0.6.0).

What it exposes

Thirty-two tools, in five groups. Since 0.6.0 the surface is deliberately small: one tool per job, with an argument choosing the variant, so a model reads a short catalog rather than forty-five near-duplicates.

Finding your way around

Tool	Does
`list_wikis`	The wikis under your wikis folder.
`list_pages`	Every page’s frontmatter in one wiki, with optional `tag` and `page_type` filters.
`get_page`	One page: `part: meta` (default), `body`, or `block` with a `block_id` to resolve a `#^id` reference.
`links`	A page’s links, `direction: out`, `in` or `both`.
`search`	`mode: concept` is the hybrid keyword-and-semantic search over page bodies, with the matching passage in each hit; `mode: text` is a literal or regex sweep with line numbers — the wiki’s grep.
`get_current_page`	Which page you have open in the app.
`read_wiki_file`	Any text file under the wiki — `log.md`, `index.md`, raw and ingested files.
`read_wiki_image`	An image stored in the wiki, with its alt text and captions.
`get_app_help`	Wikai’s own help, for an agent asked how something works in the app.

Writing pages

Tool	Does
`create_page`	A new page; the filename comes from the title, the folder from `parent_path`.
`edit_block`	One block: `op: replace`, `insert_after`, `insert_before` or `delete`. The block keeps its `^id`, so links and embeds pointing at it keep resolving.
`replace_in_page`	Replace one passage that occurs exactly once — for content with no block id, like a table or code block.
`update_page`	Rewrite a whole page body.
`update_frontmatter`	Change tags, summary, aliases and the rest without touching the body.
`move_page`	Move or rename a page, rewriting every link to it.
`link_text_in_page`	Turn a mention into a link, adding only the brackets around it.
`write_wiki_file`	Write a non-page file (`index.md`, research notes), `mode: replace` or `append`. Refuses `pages/`, `raw/` and `ingested/`, and never replaces `log.md`.
`list_pending_edits`	The agent’s edits waiting for your approval.

Comments — see Comments and highlights

Tool	Does
`list_comments_for`	Every comment on a page: the quoted words, the paragraph, the note, replies, and whether each could be placed.
`add_comment`	A comment on a paragraph’s words; a reply with `reply_to`; a highlight with an empty body.
`edit_comment`	Change a comment’s text or color.
`delete_comment`	Remove a comment with its replies, or a reply alone.

Research

Tool	Does
`list_work_docs`, `get_work_doc`	The wiki’s work documents.
`create_work_doc`	Start one. Offered to the sidebar agent only once you have said yes to a research proposal.
`update_work_doc`	Change one — the goal, the checklist, the log, the status — through an `op` argument.
`propose_research_mode`	Ask you whether a question deserves a work document.
`list_tasks`	Open follow-ups across the wiki.
`lint_wiki`	A lint pass.

The internet — only with internet search on

Tool	Does
`search_web`	A web search through the provider you configured.
`harvest_web_page`	Fetch a page into the wiki as a source summary, marked unapproved until you approve it. Addresses on your own machine or local network are refused.
`attach_image`	Save an image from a URL next to a page, ready to insert.

No filesystem tools. An agent reaches your wiki through these tools or not at all. That was always the intent; it is now enforced rather than merely documented, so an external agent can’t step around the agent_edit policy by opening the file directly. This holds for every agent the chat sidebar can run: Codex is started with its own file access off, and the API-and-local-model agents talk to this same server from inside Wikai rather than to a separate, smaller set of tools.

Every page write is gated by the page’s agent_edit policy: allow is applied, review is queued for your approval, deny is refused.

Which tools a local model gets

A small model with a short context window does worse with thirty-two tool descriptions than with five. For the llama.cpp and vLLM agents, Settings → Agents → Tool set picks the set: Reads (list_pages, get_page, links, search, get_current_page), Core (those plus create_page, edit_block, create_work_doc and update_work_doc — nine tools), or All. Auto, the default, chooses by the model’s context window: Reads under 16k, Core from 16k to 32k, All from 32k up, and Reads when the server reports no window at all. An Ollama server is asked for its model’s context length. See Settings.

Renamed in 0.6.0

If you wrote scripts or prompts against the old names, this is the map:

Was	Now
`search_by_tag`, `search_by_type`	`list_pages` with `tag` / `page_type`
`get_page_meta`, `get_page_body`, `read_block`	`get_page` with `part`
`outbound_links`, `inbound_links`	`links` with `direction`
`search_concepts`, `grep_pages`	`search` with `mode: concept` / `mode: text`
`set_work_doc_`, `append_` (nine tools)	`update_work_doc` with `op`
`update_block`, `insert_block_after`, `insert_block_before`, `delete_block`	`edit_block` with `op`

Connecting an external agent

The MCP server runs locally, bound to 127.0.0.1 (this machine only) at /mcp, and starts with the app. Every HTTP request requires a bearer token, even though the endpoint is local. Wikai handles authentication for its own chat agents automatically; there is no extra setup for the built-in sidebar.

For an external MCP client:

Open Settings → Agents → MCP server.

Click Copy client config (JSON). You get an mcpServers block with the endpoint and its Authorization: Bearer … header:

{
  "mcpServers": {
    "wikai": {
      "type": "http",
      "url": "http://127.0.0.1:27182/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Merge the wikai entry into your client’s MCP configuration, preserving any other servers. A client that doesn’t take this JSON shape needs the same URL and bearer token in its own format.
Reload the connection in your client, with Wikai running.

You do this once. The port and the token both stay the same across restarts.

Upgrading from 0.4.x: replace the old URL-only connection with the new configuration from Settings. A URL without the token returns 401 Unauthorized.

The port

On first launch Wikai takes the first free port from 27182 upward, writes it to config.toml, and uses it from then on. If that port is busy at a later launch, Wikai moves to the next free one, saves that, and tells you — a toast at launch and a notice in Settings naming both ports — so you update your client once rather than every session. The Preferred port field in Settings lets you choose a specific one; WIKAI_MCP_PORT in the environment overrides it for a single run without saving.

The token

The token is generated once, saved in config.toml, and kept. Settings offers Show, Copy token, and Generate new. Generate new replaces the token at once — no restart — and from that moment the old one is refused, so external clients configured with it stop working until you paste the new one. Wikai’s own chat agents switch on their next turn.

Treat the token and the copied configuration as secrets; don’t include them in public posts or bug reports. See config locations.

Browser requests are blocked

Requests carrying an Origin header return 403 Forbidden, even with a valid token. Browser pages are not supported MCP clients for this endpoint. Use a local MCP client; opening the URL in a browser is not a connection test. See troubleshooting.

Last updated 2026-10-07.