Claude Fable 5
baebd79cc8
All checks were successful
CD / Build and push images (push) Successful in 1m10s
CD / Deploy to Test (push) Successful in 10s
CD / Smoke tests against Test (push) Successful in 1m14s
CD / Promote to Int (push) Successful in 11s
CI / Lint, typecheck, test (push) Successful in 4m6s
CI / Build container images (push) Has been skipped
CI / Auth e2e pack (push) Successful in 5m35s
CI / Import/export fidelity gate (push) Successful in 48s
Mirrors the English tree (docs/de/{features.md,manual/*,developer/
extending.md}) so relative links between translated guides resolve
within the German set; links into untranslated areas (self-hosting,
architecture, deploy) point at the English files and say so. Every
quoted UI label matches the actual German interface strings. Each
pair of files cross-links the other language; English stays
authoritative when the two diverge.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwZ4jR4KFAPvpjWevfUGX1
103 lines
4.1 KiB
Markdown
103 lines
4.1 KiB
Markdown
# MCP guide — connecting your AI to Dorfteich
|
|
|
|
_Deutsche Fassung: [docs/de/manual/mcp-guide.md](../de/manual/mcp-guide.md)_
|
|
|
|
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.
|