{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/agentdocs-logo.png\" width=\"88\" alt=\"AgentDocs\" />\n</p>\n\n<h1 align=\"center\">agentdocs-mcp</h1>\n\nMCP server for [AgentDocs](https://agentdocs.eu) — the collaborative documentation\nplatform where AI agents are first-class citizens.\n\nGives MCP clients that run a local server (Claude Code, Claude Desktop, Cursor, Windsurf, Zed, …)\nnative tools to read, search, create, update, and share AgentDocs pages.\n\n> **Claude.ai (web), Claude Desktop and Claude mobile** connect with **no token at all**:\n> add `https://agentdocs.eu/mcp` as a custom connector (Settings → Connectors → Add custom\n> connector) and leave Advanced settings empty. AgentDocs implements **OAuth 2.1** — Claude\n> discovers the flow automatically, your browser opens an AgentDocs consent page, and you're\n> connected after approving. The grant covers your documents only and is revocable any time\n> at agentdocs.eu → Settings → Connected apps. The hosted\n> [Skill](https://agentdocs.eu/agentdocs-skill.md) remains a connector-free fallback, and\n> Claude Desktop can also run the local stdio config further down.\n\nListed on the official MCP registry as\n[`io.github.hoornet/agentdocs-mcp`](https://registry.modelcontextprotocol.io/v0/servers?search=agentdocs-mcp).\n\n\n## Setup\n\n**MCP connector clients (Claude.ai / Desktop / mobile) need no token** — see the OAuth note\nabove. For the local stdio server and other clients, you need an AgentDocs API token:\n\n- **Account token** — agentdocs.eu → Profile → Regenerate API Token (full access to everything you own), or\n- **Space token** — Space settings → Tokens (editor access to exactly one space; the\n  server auto-detects this and scopes itself to that space — the recommended way to\n  sandbox an agent).\n\n### Remote (hosted) — nothing to install\n\nAny client that speaks remote MCP can use the hosted endpoint directly; there's no package\nto install and nothing to keep updated. Same 19 tools as the stdio server.\n\n```\nhttps://agentdocs.eu/mcp        (Streamable HTTP)\nAuthorization: Token <your-token>   # or no header at all — OAuth clients authenticate via the built-in flow\n```\n\n```bash\n# Claude Code\nclaude mcp add --transport http agentdocs https://agentdocs.eu/mcp \\\n  --header \"Authorization: Token <your-token>\"\n```\n\n**Claude.ai (web) and Claude Desktop** use the same flow as each other: Settings → Connectors\n→ Add custom connector, with an `Authorization` request header.\n\nThat request-header field is an Anthropic beta, enabled per-account. If **Advanced settings**\noffers only *OAuth Client ID* and *OAuth Client Secret*, your account doesn't have it — and those\nOAuth fields won't work here, because **AgentDocs doesn't implement OAuth yet** (planned). The\nconnector will simply report a connection failure.\n\nIn that case use the [Skill](https://agentdocs.eu/agentdocs-skill.md) (Skills → Upload Skill):\nno beta access needed, same REST API, and the reliable path on Claude.ai today.\n\n`Bearer <api_token>` is accepted here as well as `Token <api_token>`, because several clients\nonly offer a \"Bearer\" field. Account tokens and space-scoped tokens both work — a space token\nconfines the session to its own space, exactly as it does over REST.\n\n### Claude Code (local stdio)\n\n```bash\nclaude mcp add agentdocs --env AGENTDOCS_TOKEN=<your-token> -- npx -y agentdocs-mcp\n```\n\n### Codex CLI\n\n```bash\ncodex mcp add agentdocs --env AGENTDOCS_TOKEN=<your-token> -- npx -y agentdocs-mcp\n```\n\nor in `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.agentdocs]\ncommand = \"npx\"\nargs = [\"-y\", \"agentdocs-mcp\"]\n[mcp_servers.agentdocs.env]\nAGENTDOCS_TOKEN = \"<your-token>\"\n```\n\n### Claude Desktop / Cursor / Windsurf / Gemini CLI / generic MCP config\n\nIn `claude_desktop_config.json` / `.cursor/mcp.json` /\n`~/.codeium/windsurf/mcp_config.json` / `~/.gemini/settings.json` respectively:\n\n```json\n{\n  \"mcpServers\": {\n    \"agentdocs\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"agentdocs-mcp\"],\n      \"env\": { \"AGENTDOCS_TOKEN\": \"<your-token>\" }\n    }\n  }\n}\n```\n\n### VS Code (Copilot)\n\nSame server block, but `.vscode/mcp.json` uses a top-level `\"servers\"` key:\n\n```json\n{\n  \"servers\": {\n    \"agentdocs\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"agentdocs-mcp\"],\n      \"env\": { \"AGENTDOCS_TOKEN\": \"<your-token>\" }\n    }\n  }\n}\n```\n\n### Zed\n\nIn `settings.json`:\n\n```json\n{\n  \"context_servers\": {\n    \"agentdocs\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"agentdocs-mcp\"],\n      \"env\": { \"AGENTDOCS_TOKEN\": \"<your-token>\" }\n    }\n  }\n}\n```\n\n### Opencode\n\nIn `opencode.json` (project root) or `~/.config/opencode/opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"mcp\": {\n    \"agentdocs\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"agentdocs-mcp\"],\n      \"environment\": { \"AGENTDOCS_TOKEN\": \"<your-token>\" }\n    }\n  }\n}\n```\n\n### pi / oh-my-pi\n\nBase [pi](https://pi.dev) ships without MCP support — use the\n[Skill](https://agentdocs.eu/agentdocs-skill.md) or the plain\n[REST API](https://agentdocs.eu/llms.txt) there. The\n[oh-my-pi](https://github.com/can1357/oh-my-pi) (omp) fork does support MCP and\ninherits servers from configs already on disk (`.claude`, `.cursor`, `.codex`,\n`.vscode`, …) — add the standard `mcpServers` block above to one of those (e.g.\n`.cursor/mcp.json`) and restart omp.\n\n### Windows\n\nMany MCP clients can't spawn `npx` directly on Windows (`spawn npx ENOENT`).\nWrap the command in `cmd /c`:\n\n```json\n\"command\": \"cmd\",\n\"args\": [\"/c\", \"npx\", \"-y\", \"agentdocs-mcp\"]\n```\n\n> **Catalog-based MCP gateways** (e.g. the Docker MCP gateway) only run servers\n> from their curated catalog and can't launch arbitrary npx servers —\n> agentdocs-mcp isn't listed there yet. Use the **hosted remote endpoint**\n> instead: `https://agentdocs.eu/mcp` (Streamable HTTP, same 19 tools, nothing\n> to install) — see [Remote](#remote-hosted--nothing-to-install) above. Failing\n> that, the [REST API](https://agentdocs.eu/llms.txt) has full parity.\n\n### Configuration\n\n| Env var | Default | Purpose |\n|---|---|---|\n| `AGENTDOCS_TOKEN` | contents of `~/.config/agentdocs/token` | API token (account or space-scoped) |\n| `AGENTDOCS_URL` | `https://agentdocs.eu` | Override the API base URL. Advanced — only set this if you've been given a different endpoint |\n\n### Updating\n\nThe setup commands above are unpinned (`npx -y agentdocs-mcp`), so they always\nresolve the latest published version. To pick up a new release, just **restart\nyour MCP client** — the client only re-launches the server process on restart.\nThe server prints its version on startup (stderr): `agentdocs-mcp vX.Y.Z: connected …`.\n\nIf npx serves a stale cached copy, force a refresh:\n\n```bash\nnpx -y agentdocs-mcp@latest    # or: npm cache clean --force\n```\n\n## Tools\n\n| Tool | Description |\n|---|---|\n| `whoami` | Identify the user and credential scope |\n| `list_workspaces` | List accessible workspaces ¹ |\n| `list_spaces` | List spaces in a workspace ¹ |\n| `list_pages` | Page tree of a space (without content) |\n| `search_docs` | Full-text (keyword) search across a workspace ¹ |\n| `semantic_search` | Natural-language search ranked by meaning — Pro workspaces ¹ |\n| `get_page` | Read a page (full Markdown + version); optional `include_comments` / `include_children` / `include_images` (returns embedded images as viewable image blocks) |\n| `create_page` | Create a Markdown page (nestable) |\n| `update_page` | Update title/content, with optional optimistic version check |\n| `append_to_page` | Append Markdown — ideal for logs and session reports |\n| `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 |\n| `delete_page` | Delete a page (cascades to children) |\n| `bulk_create_pages` | Create up to 500 pages atomically with explicit structure |\n| `share_page` | Create a public magic link (web + raw-Markdown URLs) |\n| `list_comments` | List a page's threaded comments (ids, authors, parents) |\n| `add_comment` | Post a comment / threaded reply (with `@mentions`) |\n| `update_comment` | Edit a comment or mark its thread resolved (author/admin) |\n| `delete_comment` | Delete a comment (author/admin) |\n| `upload_image` | Attach a PNG/JPEG/GIF/WebP to a space and get Markdown to embed it — from `path` ², `source_url`, or base64 `data` |\n\n¹ Hidden when running with a space-scoped token.\n\n² `path` reads a file from the machine this server runs on, so it works on the stdio\nserver only. The hosted `agentdocs.eu/mcp` endpoint refuses it — there, the \"machine\"\nis AgentDocs' production server, and honouring a caller-supplied path would be\narbitrary file read. Use `source_url` or `data` there.\n\nPages, spaces, and workspaces are addressable by UUID **or** human-readable slug\npath — `get_page` accepts `\"my-workspace/my-space/my-page\"`, `create_page` accepts\n`\"my-workspace/my-space\"`, etc. (Slug paths require an account token.)\n\n## Notes\n\n- Every page update creates a version on the server; old versions stay restorable\n  from the AgentDocs UI.\n- The hosted instance may take ~15 s to respond to the first request after being\n  idle (database cold start) — the server absorbs this with a 35 s timeout and one\n  retry.\n- Free-tier API limits surface as clear messages with an upgrade link.\n\n## Development\n\n```bash\nnpm install\nnpm run build\n\n# End-to-end smoke tests (hit a real AgentDocs instance with YOUR data):\nSMOKE_TESTBED_SPACE=\"workspace-slug/scratch-space-slug\" \\\nSMOKE_KNOWN_PAGE=\"workspace-slug/space-slug/page-slug\" \\\nnode test/smoke.mjs                       # account token: all tools\n\nAGENTDOCS_TOKEN=<space-token> node test/smoke-space-token.mjs   # space-token mode\n```\n\nThe testbed space is written to (pages created and deleted) — use a scratch space.\n\n## Security\n\nSee [SECURITY.md](SECURITY.md). Report vulnerabilities privately to contact@agentdocs.eu.\n\n## License\n\nMIT\n",
  "bytes": 9919,
  "sha": "a1e84e8fcdb26a9e0ac3a410bd293caad65defc3bf1920223466378d176d1c70",
  "repo_slug": "hoornet/agentdocs-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_hoornet_agentdocs_mcp_101be535/readme"
}