agentdocs-mcp

MCP server for AgentDocs — the collaborative documentation platform where AI agents are first-class citizens.

Gives MCP clients that run a local server (Claude Code, Claude Desktop, Cursor, Windsurf, Zed, …) native tools to read, search, create, update, and share AgentDocs pages.

Claude.ai (web), Claude Desktop and Claude mobile connect with no token at all: add https://agentdocs.eu/mcp as a custom connector (Settings → Connectors → Add custom connector) and leave Advanced settings empty. AgentDocs implements OAuth 2.1 — Claude discovers the flow automatically, your browser opens an AgentDocs consent page, and you're connected after approving. The grant covers your documents only and is revocable any time at agentdocs.eu → Settings → Connected apps. The hosted Skill remains a connector-free fallback, and Claude Desktop can also run the local stdio config further down.

Listed on the official MCP registry as io.github.hoornet/agentdocs-mcp.

Setup

MCP connector clients (Claude.ai / Desktop / mobile) need no token — see the OAuth note above. For the local stdio server and other clients, you need an AgentDocs API token:

Account token — agentdocs.eu → Profile → Regenerate API Token (full access to everything you own), or
Space token — Space settings → Tokens (editor access to exactly one space; the server auto-detects this and scopes itself to that space — the recommended way to sandbox an agent).

Remote (hosted) — nothing to install

Any client that speaks remote MCP can use the hosted endpoint directly; there's no package to install and nothing to keep updated. Same 19 tools as the stdio server.

Code

https://agentdocs.eu/mcp        (Streamable HTTP)
Authorization: Token <your-token>   # or no header at all — OAuth clients authenticate via the built-in flow

bash

# Claude Code
claude mcp add --transport http agentdocs https://agentdocs.eu/mcp \
  --header "Authorization: Token <your-token>"

Claude.ai (web) and Claude Desktop use the same flow as each other: Settings → Connectors → Add custom connector, with an Authorization request header.

That request-header field is an Anthropic beta, enabled per-account. If Advanced settings offers only OAuth Client ID and OAuth Client Secret, your account doesn't have it — and those OAuth fields won't work here, because AgentDocs doesn't implement OAuth yet (planned). The connector will simply report a connection failure.

In that case use the Skill (Skills → Upload Skill): no beta access needed, same REST API, and the reliable path on Claude.ai today.

Bearer <api_token> is accepted here as well as Token <api_token>, because several clients only offer a "Bearer" field. Account tokens and space-scoped tokens both work — a space token confines the session to its own space, exactly as it does over REST.

Claude Code (local stdio)

Terminal

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

Codex CLI

bash

codex mcp add agentdocs --env AGENTDOCS_TOKEN=<your-token> -- npx -y agentdocs-mcp

or in ~/.codex/config.toml:

toml

[mcp_servers.agentdocs]
command = "npx"
args = ["-y", "agentdocs-mcp"]
[mcp_servers.agentdocs.env]
AGENTDOCS_TOKEN = "<your-token>"

Claude Desktop / Cursor / Windsurf / Gemini CLI / generic MCP config

In claude_desktop_config.json / .cursor/mcp.json / ~/.codeium/windsurf/mcp_config.json / ~/.gemini/settings.json respectively:

config.json

{
  "mcpServers": {
    "agentdocs": {
      "command": "npx",
      "args": ["-y", "agentdocs-mcp"],
      "env": { "AGENTDOCS_TOKEN": "<your-token>" }
    }
  }
}

VS Code (Copilot)

Same server block, but .vscode/mcp.json uses a top-level "servers" key:

config.json

{
  "servers": {
    "agentdocs": {
      "command": "npx",
      "args": ["-y", "agentdocs-mcp"],
      "env": { "AGENTDOCS_TOKEN": "<your-token>" }
    }
  }
}

Zed

In settings.json:

config.json

{
  "context_servers": {
    "agentdocs": {
      "command": "npx",
      "args": ["-y", "agentdocs-mcp"],
      "env": { "AGENTDOCS_TOKEN": "<your-token>" }
    }
  }
}

Opencode

In opencode.json (project root) or ~/.config/opencode/opencode.json:

config.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agentdocs": {
      "type": "local",
      "command": ["npx", "-y", "agentdocs-mcp"],
      "environment": { "AGENTDOCS_TOKEN": "<your-token>" }
    }
  }
}

pi / oh-my-pi

Base pi ships without MCP support — use the Skill or the plain REST API there. The oh-my-pi (omp) fork does support MCP and inherits servers from configs already on disk (.claude, .cursor, .codex, .vscode, …) — add the standard mcpServers block above to one of those (e.g. .cursor/mcp.json) and restart omp.

Windows

Many MCP clients can't spawn npx directly on Windows (spawn npx ENOENT). Wrap the command in cmd /c:

json

"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 — agentdocs-mcp isn't listed there yet. Use the hosted remote endpoint instead: https://agentdocs.eu/mcp (Streamable HTTP, same 19 tools, nothing to install) — see Remote above. Failing that, the REST API has full parity.

Configuration

Env var	Default	Purpose
`AGENTDOCS_TOKEN`	contents of `~/.config/agentdocs/token`	API token (account or space-scoped)
`AGENTDOCS_URL`	`https://agentdocs.eu`	Override the API base URL. Advanced — only set this if you've been given a different endpoint

Updating

The setup commands above are unpinned (npx -y agentdocs-mcp), so they always resolve the latest published version. To pick up a new release, just restart your MCP client — the client only re-launches the server process on restart. The server prints its version on startup (stderr): agentdocs-mcp vX.Y.Z: connected ….

If npx serves a stale cached copy, force a refresh:

Terminal

npx -y agentdocs-mcp@latest    # or: npm cache clean --force

Tools

Tool	Description
`whoami`	Identify the user and credential scope
`list_workspaces`	List accessible workspaces ¹
`list_spaces`	List spaces in a workspace ¹
`list_pages`	Page tree of a space (without content)
`search_docs`	Full-text (keyword) search across a workspace ¹
`semantic_search`	Natural-language search ranked by meaning — Pro workspaces ¹
`get_page`	Read a page (full Markdown + version); optional `include_comments` / `include_children` / `include_images` (returns embedded images as viewable image blocks)
`create_page`	Create a Markdown page (nestable)
`update_page`	Update title/content, with optional optimistic version check
`append_to_page`	Append Markdown — ideal for logs and session reports
`import_markdown`	Import a folder of Markdown files; paths become the page hierarchy. Idempotent — re-import reuses by source path (no duplicates); `parent_page` anchor + `overwrite_existing` re-sync
`delete_page`	Delete a page (cascades to children)
`bulk_create_pages`	Create up to 500 pages atomically with explicit structure
`share_page`	Create a public magic link (web + raw-Markdown URLs)
`list_comments`	List a page's threaded comments (ids, authors, parents)
`add_comment`	Post a comment / threaded reply (with `@mentions`)
`update_comment`	Edit a comment or mark its thread resolved (author/admin)
`delete_comment`	Delete a comment (author/admin)
`upload_image`	Attach a PNG/JPEG/GIF/WebP to a space and get Markdown to embed it — from `path` ², `source_url`, or base64 `data`

¹ Hidden when running with a space-scoped token.

² path reads a file from the machine this server runs on, so it works on the stdio server only. The hosted agentdocs.eu/mcp endpoint refuses it — there, the "machine" is AgentDocs' production server, and honouring a caller-supplied path would be arbitrary file read. Use source_url or data there.

Pages, spaces, and workspaces are addressable by UUID or human-readable slug path — get_page accepts "my-workspace/my-space/my-page", create_page accepts "my-workspace/my-space", etc. (Slug paths require an account token.)

Notes

Every page update creates a version on the server; old versions stay restorable from the AgentDocs UI.
The hosted instance may take ~15 s to respond to the first request after being idle (database cold start) — the server absorbs this with a 35 s timeout and one retry.
Free-tier API limits surface as clear messages with an upgrade link.

Development

Terminal

npm install
npm run build

# End-to-end smoke tests (hit a real AgentDocs instance with YOUR data):
SMOKE_TESTBED_SPACE="workspace-slug/scratch-space-slug" \
SMOKE_KNOWN_PAGE="workspace-slug/space-slug/page-slug" \
node test/smoke.mjs                       # account token: all tools

AGENTDOCS_TOKEN=<space-token> node test/smoke-space-token.mjs   # space-token mode

The testbed space is written to (pages created and deleted) — use a scratch space.

Security

See SECURITY.md. Report vulnerabilities privately to contact@agentdocs.eu.

License

MIT