agentdocs-mcp

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.

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

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

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

Codex CLI

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

or in ~/.codex/config.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:

{
  "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:

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

Zed

In settings.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:

{
  "$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:

"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:

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

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 [email protected].

License

MIT