agentdocs-mcp

agentdocs-mcp

AgentDocs 的 MCP 服务——一个协作文档平台，AI Agent 在其中是核心参与者。

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

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

已收录在官方 MCP 注册表中，名称为 io.github.hoornet/agentdocs-mcp。

设置

MCP 连接器客户端（Claude.ai / Desktop / 移动版）无需令牌——请参阅上方的 OAuth 说明。对于本地 stdio 服务和其他客户端，你需要一个 AgentDocs API 令牌：

• 账户令牌——agentdocs.eu → Profile → Regenerate API Token（可完整访问你拥有的所有内容），或者
• 空间令牌——Space settings → Tokens（仅对一个空间有编辑权限；服务会自动检测并将自身范围限定在该空间——这是隔离 Agent 的推荐方式）。

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

任何支持远程 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 的 Beta 功能，需按账户启用。如果 Advanced settings 中只有 OAuth Client ID 和 OAuth Client Secret，说明你的账户尚未启用该功能——而且这些 OAuth 字段在此处不起作用，因为 AgentDocs 尚未实现 OAuth（计划中）。连接器只会报告连接失败。

遇到这种情况，请使用 Skill（Skills → Upload Skill）： 无需 Beta 权限，使用相同的 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_config.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 网关）只会运行其精选目录中的服务，无法启动任意 npx 服务—— agentdocs-mcp 尚未列入其中。请改用托管的远程端点： https://agentdocs.eu/mcp（Streamable HTTP，包含相同的 19 个工具，无需安装）——请参阅上文的远程（托管，无需安装）。如果此方法不可行， REST API 也具备完整的同等功能。

配置

环境变量	默认值	用途
AGENTDOCS_TOKEN	~/.config/agentdocs/token 的内容	API 令牌（账号级或空间级）
AGENTDOCS_URL	https://agentdocs.eu	覆盖 API 基础 URL。高级选项——仅在有人提供了不同端点时设置

更新

上面的设置命令未固定版本（npx -y agentdocs-mcp），因此始终会解析到最新发布版本。若要获取新版本，只需重启 MCP 客户端——客户端只会在重启时重新启动服务进程。 服务启动时会在 stderr 中打印版本号：agentdocs-mcp vX.Y.Z: connected …。

如果 npx 提供的是过时的缓存副本，请强制刷新：

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

工具

工具	说明
whoami	识别用户和凭据范围
list_workspaces	列出可访问的工作区 ¹
list_spaces	列出工作区中的空间 ¹
list_pages	列出空间的页面树（不含内容）
search_docs	在工作区中进行全文（关键词）搜索 ¹
semantic_search	按语义相关性排序的自然语言搜索——Pro 工作区 ¹
get_page	读取页面（完整 Markdown + 版本）；可选 include_comments / include_children / include_images（将嵌入图片作为可查看的图片块返回）
create_page	创建 Markdown 页面（可嵌套）
update_page	更新标题/内容，可选乐观版本检查
append_to_page	追加 Markdown——适合日志和会话报告
import_markdown	导入 Markdown 文件夹；路径会成为页面层级。幂等——重新导入时会按源路径复用（不会产生重复项）；通过 parent_page 锚点 + overwrite_existing 重新同步
delete_page	删除页面（级联删除子页面）
bulk_create_pages	通过明确的结构以原子方式创建最多 500 个页面
share_page	创建公开魔法链接（网页 + 原始 Markdown URL）
list_comments	列出页面的串联评论（ID、作者、父级）
add_comment	发布评论/串联回复（支持 @提及）
update_comment	编辑评论或将其讨论串标记为已解决（作者/管理员）
delete_comment	删除评论（作者/管理员）
upload_image	将 PNG/JPEG/GIF/WebP 附加到空间，并获取用于嵌入的 Markdown——可通过 path ²、source_url 或 base64 data 提供图片

¹ 使用空间级令牌运行时会隐藏。

² path 会读取此服务运行所在机器上的文件，因此仅适用于 stdio 服务。托管的 agentdocs.eu/mcp 端点会拒绝此参数——在该端点上，“机器”是 AgentDocs 的生产服务，若遵从调用方提供的路径，将造成任意文件读取。请在此处使用 source_url 或 data。

页面、空间和工作区均可通过 UUID 或易读的 slug 路径寻址——get_page 接受 "my-workspace/my-space/my-page"，create_page 接受 "my-workspace/my-space" 等。（Slug 路径需要账号令牌。）

备注

• 每次更新页面都会在服务端创建一个版本；可以在 AgentDocs UI 中恢复旧版本。
• 托管实例在空闲后收到第一个请求时，可能需要约 15 秒才会响应（数据库冷启动）——服务会通过 35 秒超时和一次重试来应对此情况。
• 免费套餐的 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。请将漏洞私下报告至 [email protected]。

许可证

MIT