# MCP guide — connecting your AI to Dorfteich

Dorfteich ships its own [MCP](https://modelcontextprotocol.io) 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

```sh
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`:

```json
{
  "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, labels, timestamps  |
| `read_page(pond, page)`                      | a page as Markdown plus metadata            |
| `search(query, pond?, label?)`               | full-text search with snippets              |
| `create_page(pond, title, markdown)`         | new page from Markdown _(write)_            |
| `update_page(pond, page, markdown?, title?)` | rename and/or replace content _(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.