dorfteich/docs/manual/mcp-guide.md

MCP guide — connecting your AI to Dorfteich

Deutsche Fassung: docs/de/manual/mcp-guide.md

Dorfteich ships its own MCP endpoint at /api/mcp (Streamable HTTP). Any MCP-capable assistant — Claude Code, Claude Desktop via a bridge, and others — can search, read, and (if you allow it) write your wiki, with exactly your permissions. There is no extra server to run: the endpoint is part of the instance.

Switching it on

Like the REST API, MCP is off by default and has its own, independent switches:

1. Site admin: Admin → Settings → Public API → "Enable the built-in MCP endpoint".
2. Each pond that the assistant should see: pond settings → "Expose this pond to AI assistants (MCP)".

A pond without the opt-in is invisible to MCP clients — even to your own token.

Get a token

MCP uses the same personal access tokens as the REST API: create one under Settings → API tokens. Pick the scope deliberately:

• read — the assistant can list, read, and search, nothing else.
• read+write — it may also create/update pages, comment, and set labels.

Consider restricting the token to the specific pond(s) you want the assistant to work in.

Connect Claude Code

claude mcp add --transport http dorfteich https://wiki.example.com/api/mcp \
  --header "Authorization: Bearer dt_pat_..."

That's it — Claude Code lists the tools on the next start. Stdio-only clients bridge with mcp-remote:

{
  "mcpServers": {
    "dorfteich": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://wiki.example.com/api/mcp",
        "--header",
        "Authorization: Bearer dt_pat_..."
      ]
    }
  }
}

What the assistant can do

Tool	Does
list_ponds	the ponds this token can reach
list_pages(pond)	pages with slug, title, parent, labels
read_page(pond, page)	a page as Markdown plus metadata
search(query, pond?, label?)	full-text search with snippets
create_page(pond, title, markdown, parent?)	new page from Markdown (write)
update_page(pond, page, markdown?, title?, parent?)	rename, replace content, move (write)
add_comment(pond, page, text)	comment on a page (write)
list_labels(pond)	the pond's label tree
set_page_labels(pond, page, labelIds)	replace a page's labels (write)
export_pond(pond)	a download link for the Markdown-ZIP export

Content updates travel the same collaborative path as human edits: open editors converge live, and the previous state stays in the version history — an AI edit can always be reviewed and reverted like any other change.

Good to know

• Permissions are yours. The assistant sees precisely the pages your account may read; label-scoped rules, public/private, everything applies unchanged.
• Every write is audit-logged with the token attributed — the site admin's audit viewer shows what the assistant changed.
• Rate-limited per token; a runaway agent gets 429, not a melted instance.
• Stateless: each request stands alone; revoking the token under Settings → API tokens cuts the assistant off immediately.
• The endpoint speaks MCP over Streamable HTTP (POST). GET/SSE session resumption is not offered — clients fall back to plain request/response, which every current client supports.

A sensible first session

Ask your assistant to list_ponds, then search for something you know is there, read_page it, and — with a write token — draft a new page. Check the page's version history afterwards: you will find the assistant's edit as a normal, restorable version.