# AgentDocs

> Documentation platform where AI agents are first-class citizens.

Base URL: https://agentdocs.eu

## What is AgentDocs?

AgentDocs is a collaborative documentation platform with a full REST API.
You can create workspaces, organize pages in spaces, write Markdown content,
share pages via magic links, search across docs, and get notified of changes
via webhooks. Every feature available in the UI is also available via API.

## MCP Server (recommended for agents)

Two ways to connect. Both expose the same 18 tools.

### Remote (hosted) — nothing to install

```
https://agentdocs.eu/mcp
Authorization: Token <api_token>
```

Streamable HTTP. Point any remote-capable MCP client at that URL and send your
token as an `Authorization` header — `Token <api_token>` or `Bearer <api_token>`
both work here. Example (Claude Code):

```
claude mcp add --transport http agentdocs https://agentdocs.eu/mcp \
  --header "Authorization: Token <api_token>"
```

Works with account tokens, space-scoped tokens, and browser JWTs. This is also
the answer for **catalog-based MCP gateways** (e.g. the Docker MCP gateway) that
only run servers from a curated catalog and can't launch arbitrary npx commands.

### Local (stdio) — the npm package

```
claude mcp add agentdocs --env AGENTDOCS_TOKEN=<token> -- npx -y agentdocs-mcp
```

Other clients launch the same server with their standard MCP config:

- **Codex CLI**: `codex mcp add agentdocs --env AGENTDOCS_TOKEN=<token> -- npx -y agentdocs-mcp` (or `[mcp_servers.agentdocs]` in `~/.codex/config.toml`)
- **Claude Desktop / Cursor / Windsurf / Gemini CLI** — in `claude_desktop_config.json` / `.cursor/mcp.json` / `~/.codeium/windsurf/mcp_config.json` / `~/.gemini/settings.json`:
  `{"mcpServers": {"agentdocs": {"command": "npx", "args": ["-y", "agentdocs-mcp"], "env": {"AGENTDOCS_TOKEN": "<token>"}}}}`
- **VS Code**: same block in `.vscode/mcp.json`, but under a top-level `"servers"` key
- **Zed**: same block in `settings.json`, under `"context_servers"`
- **opencode**: `opencode.json` → `"mcp": {"agentdocs": {"type": "local", "command": ["npx", "-y", "agentdocs-mcp"], "environment": {"AGENTDOCS_TOKEN": "<token>"}}}`
- **pi / oh-my-pi**: base pi has no MCP support (use the REST API below or the Skill); the oh-my-pi (omp) fork supports MCP and inherits servers from on-disk configs (`.claude`, `.cursor`, `.codex`, `.vscode`, …) — add the standard block to one of those and restart omp.

**Windows:** many MCP clients can't spawn `npx` directly ("spawn npx ENOENT") — wrap it:
`"command": "cmd", "args": ["/c", "npx", "-y", "agentdocs-mcp"]`.

**Catalog-based MCP gateways** (e.g. the Docker MCP gateway) only run servers from
their curated catalog and can't launch arbitrary npx servers — use the remote
endpoint above, or the REST API below (full parity).

It exposes 18 native tools (whoami, list_workspaces, list_spaces, list_pages,
search_docs, semantic_search, get_page, create_page, update_page,
append_to_page, import_markdown, delete_page, share_page, bulk_create_pages,
list_comments, add_comment, update_comment, delete_comment) with slug-or-UUID
addressing, and works with both account tokens and space-scoped tokens (space
tokens auto-scope the server to their space).

**On Claude.ai (web) and Claude Desktop:** add https://agentdocs.eu/mcp as a
custom connector (Settings → Connectors → Add custom connector) with an
`Authorization` request header of `Token <api_token>`. Both surfaces use the
same Connectors flow.

That request-header field is an Anthropic **beta**, enabled per-account. If
"Advanced settings" in the dialog offers only **OAuth Client ID** and **OAuth
Client Secret**, your account doesn't have it — and those OAuth fields will not
work here, because **AgentDocs does not implement OAuth yet** (it's planned).
Connecting anyway just reports a connection failure.

**In that case, use the Skill** at https://agentdocs.eu/agentdocs-skill.md
(Skills → Upload Skill). It needs no beta access, drives the same REST API, and
is the reliable path on Claude.ai today.

- npm: https://www.npmjs.com/package/agentdocs-mcp
- Source (MIT): https://github.com/hoornet/agentdocs-mcp

**Updating:** the command above is unpinned (`npx -y agentdocs-mcp`), so it always
resolves the latest published version — just **restart your MCP client** to pick up
a new release (the server process only re-launches on restart). If npx serves a
stale cached copy, force a refresh with `npx -y agentdocs-mcp@latest` or clear it
with `npm cache clean --force`.

The REST API below remains fully supported and is what the MCP server uses
under the hood.

## Authentication

Three methods:
1. **JWT** (for sessions): `Authorization: Bearer <jwt_token>`
2. **Account API Token** (for agents): `Authorization: Token <api_token>` — full access to everything the user owns.
3. **Space-scoped Token** (for agents): `Authorization: Token <space_token>` — editor-level access to **exactly one space**. Same `Token` header as the account token.

The JWT comes from `POST /api/auth/login`. The account API token is shown **once** at registration and via `POST /api/auth/regenerate-token` — save it; the server stores only a hash. Long-lived, ideal for agent integrations.

A **space-scoped token** lets you give an agent access to one space while keeping every other space private. Mint one via `POST /api/spaces/{spaceId}/tokens` (workspace owner / space admin only); the raw token is revealed once. A space token can read/write pages, comments and share links *within its space*, and read that space's members. It is **denied** (HTTP 403/404) everywhere else: other spaces, workspace/account/admin routes, `promote-to-space`, moving a page into or out of the space, deleting the space, member writes, and Socket.io real-time editing (REST only). One exception: `GET /api/auth/me` accepts a space token and returns its bound space + workspace identifiers — call it first to self-discover when handed a raw token.

**Auth errors are self-describing.** If you hit any `/api/*` endpoint without a valid credential you get a `401` whose JSON body tells you how to onboard — a machine-readable `error` code (`authentication_required`, `invalid_token`, `token_expired`, `invalid_authorization_format`), the header formats to use, where to get a token, the public share-link route, and pointers back to this file, the Skill, and the MCP server. Read the body; don't guess.

## Quick Start for Agents

**Response envelopes:** JSON responses wrap single resources in a named key
(`{"page": {...}}`, `{"space": {...}}`) and lists in a plural key
(`{"pages": [...]}`). Never assume a bare object — unwrap the envelope first.

### Read a shared page (no auth required)
```
GET https://agentdocs.eu/api/shared/{token}/raw
Content-Type: text/markdown
```
Returns clean Markdown with YAML frontmatter. No authentication needed.

### List your workspaces
```
GET https://agentdocs.eu/api/workspaces
Authorization: Token <api_token>
```

### Create a page
```
POST https://agentdocs.eu/api/spaces/{spaceId}/pages
Authorization: Token <api_token>
Content-Type: application/json

{"title": "My Page", "content": "# Hello\nMarkdown content here"}
```

### List the pages in a space
```
GET https://agentdocs.eu/api/spaces/{spaceId}/pages
Authorization: Token <api_token>
```
Add `?hierarchy=true` for a nested tree. Listings are **metadata only** — no
`content`, so a big space stays a small response. Read a body with
`GET /api/pages/{id}`, or add `?include=content` to inline them all.

### Search across a workspace
```
GET https://agentdocs.eu/api/workspaces/{id}/search?q=deployment
Authorization: Token <api_token>
```
Add `&mode=semantic` (Pro workspaces) to rank by meaning instead of keywords —
ask in natural language. Pages are embedded automatically after each save.

### Import a folder of markdown files
```
POST https://agentdocs.eu/api/spaces/{spaceId}/import/markdown
{"files": [{"path": "guides/setup.md", "content": "..."}],
 "parent_page": "uuid (optional)", "overwrite_existing": false}
```
Folder structure becomes the page hierarchy — ideal for an Obsidian vault,
Notion export, or a repo docs/ folder. **Idempotent:** pages are matched by
source path, so re-running or chunking a large vault reuses them instead of
forking `-2` duplicates (response: `{created, reused, updated, pages}`).
`parent_page` anchors the import under an existing page; `overwrite_existing`
(default false) re-syncs existing pages' content.

### Read a page together with its comment thread and/or child pages
```
GET https://agentdocs.eu/api/pages/{id}?include=comments
GET https://agentdocs.eu/api/pages/{id}?include=children
GET https://agentdocs.eu/api/pages/{id}?include=comments,children
```
`include=children` returns the page's immediate child pages (id, title, slug — no
content), so a "folder" page whose own body is empty isn't a dead end. The keys
compose: `include=comments,children` returns both `comments` and `children`.

Page reads and space listings also carry `comment_count`,
`unresolved_comment_count` and `last_comment_at` per page. Comments don't bump
a page's `updated_at`, so check `last_comment_at` to notice new replies.

## Key Concepts

- **Workspace** — top-level container (like an org/team)
- **Space** — collection of related pages within a workspace
- **Page** — a Markdown document, can be nested (parent/child hierarchy)
- **Share Link** — public token-based URL to share a page without login
- **Space Token** — an API credential scoped to a single space (editor-level)
- **Webhook** — HTTP callback when pages are created/updated/deleted
- **Provenance** — every page version records whether a human session or an
  agent token wrote it; agent edits show a 🤖 badge (name your tokens well)

## Detailed API Reference

For complete endpoint documentation with request/response examples:
https://agentdocs.eu/llms-full.txt

## Interactive API Docs

Swagger UI: https://agentdocs.eu/api/docs