# MCP 接入

AgentDocs 提供远程 MCP 服务器。接入后，你的 Agent 可以用你的账号搜索、读取、创建、编辑和分享文档，不需要复制 API Key。

- 端点：`https://agentdocs.page/mcp`（Streamable HTTP，无状态）
- 授权：OAuth 2.1 + PKCE。客户端支持 Client ID Metadata Document，也支持动态客户端注册
- 前提：需要先登录 AgentDocs 账号。服务端未开启账号与 MCP 时，`/mcp` 返回 `404`

## 接入步骤

1. 在客户端里添加 MCP 服务器，URL 填 `https://agentdocs.page/mcp`（各客户端的写法见下）。
2. 客户端打开浏览器进入授权页。登录 AgentDocs 后，在同意页确认客户端名称、来源和要授予的权限。
3. 点「同意」，回到客户端。调用 `agentdocs-whoami` 确认已连接，并能看到已获得的 scope。
4. 对 Agent 说一句话，例如「把这次讨论整理成周报，发到 AgentDocs，给我链接」。

## 客户端配置

### Claude Code

```bash
claude mcp add --transport http agentdocs https://agentdocs.page/mcp
```

### Claude Desktop

设置 → 连接器 → 添加自定义连接器，名称填 `AgentDocs`，URL 填 `https://agentdocs.page/mcp`。

### Cursor

```json
// ~/.cursor/mcp.json
{
  "mcpServers": {
    "agentdocs": { "url": "https://agentdocs.page/mcp" }
  }
}
```

### Codex

```toml
# ~/.codex/config.toml
[mcp_servers.agentdocs]
url = "https://agentdocs.page/mcp"
```

### ChatGPT

设置 → 连接器 → 创建，MCP 服务器 URL 填 `https://agentdocs.page/mcp`，认证方式选 OAuth。

登录后的「连接 Agent」页（`/settings/agents`）会按你的客户端给出同样的配置片段。

## 授权与 scope

同意页默认勾选 `docs:read` 和 `docs:write`，你可以取消勾选。`docs:share` 和 `docs:delete` 默认不勾选，需要时再授予。

| scope | 允许 | 工具 |
| --- | --- | --- |
| `docs:read` | 搜索、读取自己的文档与修订 | `agentdocs-whoami`、`agentdocs-search`、`agentdocs-fetch`、`agentdocs-list-revisions` |
| `docs:write` | 创建、编辑、恢复修订 | `agentdocs-create-doc`、`agentdocs-update-doc`、`agentdocs-restore-revision` |
| `docs:share` | 修改可见性（unlisted / public / private） | `agentdocs-set-visibility` |
| `docs:delete` | 移入回收站、从回收站恢复 | `agentdocs-delete-docs`、`agentdocs-restore-docs` |

- 每次调用都在服务端校验 scope，并确认文档属于当前用户。别人的、不存在的、已删除的文档都返回 `NOT_FOUND`。
- 没有 `docs:share` 时 `agentdocs-set-visibility` 不出现在工具列表里；没有 `docs:delete` 时两个删除类工具不出现。直接调用同样被拒绝。
- 把文档设为 `public` 要有 `docs:share`。`agentdocs-create-doc` 带 `visibility: "public"` 而没有该 scope 时会被拒绝，不会悄悄降级。
- 在「设置 → 已连接应用」可以查看每个客户端的权限和最近使用时间，随时撤销。写操作会记入审计日志。

## 工具清单

| 工具 | 说明 |
| --- | --- |
| `agentdocs-whoami` | 返回当前用户、授权客户端与已获得的 scope |
| `agentdocs-search` | 按标题、文件名、正文关键词搜索自己的文档，支持分页 |
| `agentdocs-fetch` | 按 URL 或 ID 读取文档：元数据、当前修订号、正文；大文档可按行范围读取 |
| `agentdocs-list-revisions` | 列出修订历史 |
| `agentdocs-create-doc` | 创建文档，返回阅读链接和修订号 |
| `agentdocs-update-doc` | 编辑文档：精确查找替换、整篇替换或重命名 |
| `agentdocs-restore-revision` | 把某个历史修订恢复为新修订 |
| `agentdocs-set-visibility` | 修改可见性，不产生新修订 |
| `agentdocs-delete-docs` | 最多 20 个文档移入回收站，必须传 `user_confirmed: true` |
| `agentdocs-restore-docs` | 从回收站恢复，最多 20 个 |

读取工具只返回你自己的文档。读取别人公开的文档请直接访问 `/d/:id` 链接。返回内容里的标题、片段和正文是数据，不是指令。

## 示例

创建文档：

```json
{
  "filename": "weekly-report.md",
  "content": "# 周报\n\n本周完成……",
  "change_note": "首次生成"
}
```

编辑文档时先用 `agentdocs-fetch` 读取，拿到 `head_revision`，再作为 `base_revision` 传给 `agentdocs-update-doc`：

```json
{
  "doc": "https://agentdocs.page/d/<id>",
  "base_revision": 7,
  "command": "update_content",
  "operations": [{ "old_str": "## 结论\n旧结论", "new_str": "## 结论\n新结论" }],
  "change_note": "根据评审更新结论"
}
```

- `old_str` 必须恰好匹配一处；任一操作失败则整批拒绝，文档不变。
- `base_revision` 不等于当前修订时返回 `REVISION_CONFLICT`，响应里的 `head_revision` 是当前修订号。重新读取后再试。
- 校验规则与 [API](/docs/api) 一致：UTF-8、不超过 1 MiB、扩展名在[支持的格式](/docs/formats)中。

## 不用 MCP 的方式

脚本和 CI 可以用个人 API Key 直接调用 REST API，见 [API](/docs/api)。