agentdocs-mcp

面向 AgentDocs 的 MCP 服务器 —— 一个将 AI 智能体视为一等公民的协作文档平台。

为运行本地服务器的 MCP 客户端（Claude Code、Claude Desktop、Cursor、Windsurf、Zed 等）提供原生工具，用于读取、创建、更新和分享 AgentDocs 页面。

Claude.ai（网页版）、Claude Desktop 和 Claude 移动端连接时无需任何 token： 只需将 https://agentdocs.eu/mcp 添加为自定义连接器（Settings → Connectors → Add custom connector），并将 Advanced 设置留空。AgentDocs 实现了 OAuth 2.1 —— Claude 会自动发现该流程， 浏览器会打开 AgentDocs 的授权页面，然后您就连接成功了。授权仅覆盖您的文档，且可随时在 Settings → Connected apps 中撤销。托管的 Skill 仍可作为 无需连接器的后备方案，Claude Desktop 也可以运行下文中的本地 stdio 配置。

已列入官方 MCP 注册表，名称为 io.github.hoornet/agentdocs-mcp。

安装

MCP 连接器客户端（Claude.ai / Desktop / mobile）无需令牌 — 参见上方 OAuth 说明。 对于本地 stdio 服务器及其他客户端，您需要一个 AgentDocs API 令牌：

• 账户令牌 — agentdocs.eu → Profile → Regenerate API Token（完整访问您拥有的所有内容），或

• 空间令牌 — Space settings → Tokens（仅限对某一个空间的编辑权限；服务器会自动检测 该令牌并将其作用域限定在该空间 — 隔离代理的推荐方式）。

远程（托管式）— 无需安装

任何支持远程 MCP 的客户端都可以直接使用托管端点；无需安装任何软件包，也无需保持更新。 工具数量与 stdio 服务器相同，共 19 个。

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（网页版）和 Claude Desktop 的流程相同：Settings → Connectors → Add custom connector，并使用 Authorization 请求头。

该请求头字段是 Anthropic 的测试版功能，需按账户启用。如果 Advanced settings 只显示 OAuth Client ID 和 OAuth Client Secret，则说明您的账户没有该功能 —— 而且此处 OAuth 字段无法使用，因为 AgentDocs 尚未实现 OAuth（规划中）。连接器只会报告连接失败。

在这种情况下，请使用 Skill（Skills → Upload Skill）： 无需测试版访问权限，使用相同的 REST API，是在 Claude.ai 上目前最可靠的路径。

此处接受 Bearer <api_token>，也接受 Token <api_token>，因为许多客户端只提供 “Bearer”字段。账户令牌和空间作用域令牌均可使用 — 空间令牌会将会话限制在其所属空间内， 与 REST 上的行为完全一致。

Claude Code（本地 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

或在 ~/.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 / 通用 MCP 配置

分别位于 claude_desktop_config.json / .cursor/mcp.json / ~/.codeium/windsurf/mcp.json / ~/.gemini/settings.json：

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

VS Code (Copilot)

服务器配置块相同，但 .vscode/mcp.json 使用顶层 "servers" 键：

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

Zed

在 settings.json 中：

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

Opencode

在 opencode.json（项目根目录）或 ~/.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

基础版 pi 不支持 MCP —— 请使用 Skill 或纯 REST API。 oh-my-pi（omp）分支则支持 MCP，并会继承 磁盘上已有的配置（.claude、.cursor、.codex、.vscode 等）中的服务器 — 请将 标准的 mcpServers 配置块添加到其中任一配置（例如 .cursor/mcp.json），然后重启 omp。

Windows

许多 MCP 客户端在 Windows 上无法直接运行 npx（spawn npx ENOENT）。 请使用 cmd /c 包装命令：

"command": "cmd",
"args": ["/c", "npx", "-y", "agentdocs-mcp"]

基于目录的 MCP 网关（例如 Docker MCP gateway）只能运行其目录中的服务器， 无法启动任意的 npx 服务器 — agentdocs-mcp 尚未列入其中。请改用托管远程端点： https://agentdocs.eu/mcp（Streamable HTTP，同样 19 个工具，无需安装）， 参见上文 远程。若不可行，REST API 具有完全对等的功能。

环境变量

更新

上述安装命令未固定版本（npx -y agentdocs-mcp），因此始终会解析最新版本。 要获取新版本，只需重启 MCP 客户端 — 客户端仅在启动时重新启动服务器进程。 服务器在启动时会打印版本号（stderr）：agentdocs-mcp X.Y.Z: connected …。

如果 npx 缓存了旧版本，可强制刷新：

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

Related MCP server: context-book

工具

¹ 使用空间令牌时不可用（将被隐藏）。

² path 从运行该服务器的机器读取文件，因此仅适用于本地 stdio 服务器。托管的 https://agentdocs.eu/mcp 端点不支持 path — 在那里请使用 url 或 base64。

页面、空间和工作区可通过 UUID 或 人类可读的 slug 路径 寻址： my-workspace/my-space/my-page（slug 路径需要账户令牌）。

说明

• 托管实例在空闲后首次响应可能需要约 15 秒（数据库冷启动）——服务器会以 35 秒超时和一次重试来处理。

• 每次页面更新都会在服务端生成一个新版本；旧版本可在 AgentDocs UI 中恢复（或通过） 版本的 API 访问。

• 免费层 API 限制会以明确的错误消息（含升级链接）呈现。

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

安全

参见 SECURITY.md。请将漏洞私下报告至 contact@agentdocs.eu。

许可证

MIT