# 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 19 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 19 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, upload_image) 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), Claude Desktop and Claude mobile:** add
https://agentdocs.eu/mcp as a custom connector (Settings → Connectors → Add
custom connector). **No headers, no OAuth fields, no token pasting** — leave
Advanced settings empty. AgentDocs implements OAuth 2.1 with dynamic client
registration: Claude discovers it automatically, your browser opens an
AgentDocs consent page, you sign in and approve, and you're connected. The
grant is scoped to your documents (never account, billing or credential
management) and can be revoked any time at Settings → Connected apps on
agentdocs.eu.

**Connector troubleshooting:** a connector added *before* AgentDocs supported
OAuth may show "Connection issue" or "server isn't responding" — remove it and
add it fresh (stale connectors keep their old credential state). The very
first connect can time out once while the database wakes from idle; retry.
OAuth grants are revoked automatically on password change — reconnect after.

Sending an `Authorization` request header (`Token <api_token>`) still works
too, if your account has Anthropic's request-header beta and you prefer a
fixed credential.

**The Skill** at https://agentdocs.eu/agentdocs-skill.md (Skills → Upload
Skill) remains available as a connector-free alternative that drives the same
REST API.

- 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

Four 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.
4. **OAuth 2.1 access token** (for MCP connectors like Claude.ai): `Authorization: Bearer <access_token>` — issued by the built-in authorization server after user consent (RFC 8414 discovery at `/.well-known/oauth-authorization-server`; PKCE S256; dynamic client registration restricted to Claude redirect origins). Scoped to the **documents surface only**: workspaces, spaces, pages, comments, share links, templates and search — never account, credential, member, webhook, billing or admin management. Within that surface it still cannot delete or restore a workspace or space, permanently purge anything, invite members, or read workspace stats/activity; refusals come back as `403 oauth_token_not_allowed`. Reading and writing pages, and moving a page to trash, work normally. Metered like agent tokens.

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. Rotation and account deletion require a signed-in browser session (`403 session_required` for API/space/OAuth credentials), so a leaked token cannot rotate itself or erase the account.

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.

## Where to write reports (agents in a repository)

Read **`.agentdocs.json` at the repo root** before writing anything:
`{"workspace": "<slug>", "space": "<slug>", "reports": {"parent": null, "title_format": "YYYY-MM-DD — Title"}}`.
It is the project's pointer — never pick a destination by name similarity. If
it is missing, ask the user which space the project reports to, then create the
file. Title reports `YYYY-MM-DD — Title` so they sort by name everywhere.

## 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