# 用 MCP 接入 AI agent

通过 Model Context Protocol 把 Claude、Cursor 或你自己的 agent 接到 Side Space。在浏览器里授权，每个工具都遵守令牌的权限和空间范围。

服务器在 `/mcp` 提供远程 MCP（streamable HTTP）。接上之后，agent 可以搜索空间、不下载就通过元数据看懂一个视频、写和改笔记与结果、整理和分享文件、看过去的样子、运行 AI 处理、回复审阅意见，以及在分支里干活。

只是想在 Claude 里用 Side Space？见[在 Claude 里用](/docs/claude)。

## 接入

支持 MCP 授权的客户端（Claude、Claude Code、Cursor 等）只要填地址：

```sh
claude mcp add --transport http side https://side.example.com/mcp
```

第一次使用时，客户端会打开浏览器：用邮箱验证码登录 Side Space，勾选它能做什么（默认读写文件、评论、运行动作）、能进哪些空间，点“允许”就连上了。之后它拿到的是一小时有效、自动续期的令牌，在 `sidespace token list` 里显示为 `app:…`，随时可以用 `sidespace token revoke` 断开。

在 claude.ai 里，把同一个地址加为自定义连接器即可。

### 直接给令牌

[AI 成员](/docs/authentication#ai-成员)和无人值守的 agent 可以不走浏览器，直接给一个令牌：

```sh
sidespace token create claude --agent "Clip Tagger" --scope files:read --scope "sidecars:write:x-tagger.*"
claude mcp add --transport http side https://side.example.com/mcp \
  --header "Authorization: Bearer ssp_…"
```

## 工具

### 找和看

| 工具 | 做什么 |
|---|---|
| `list_spaces` | 令牌能访问的空间 |
| `search` | 按名字、元数据、转写和评论搜索，或按意思搜索；返回媒体里的时间点 |
| `list_folder` | 文件夹里的文件和子文件夹；带 `as_of` 时是当时的内容 |
| `describe_file` | 不下载就说清一个文件：类型、版本和保存人、所有附加信息（标签、AI 提示词、媒体信息、转写）以及有哪些预览 |
| `read_text` | 读文本文件，最多 1 MiB；带 `as_of` 时读当时的内容 |
| `get_sidecar` | 读元数据 |
| `recent_changes` | 空间最近发生了什么、是谁做的 |

### 写和整理

| 工具 | 做什么 |
|---|---|
| `write_text` | 写整个文本文件；自动建文件夹，文件已存在时生成新版本 |
| `edit_text` | 把一段原文换成新文字（原文要唯一，或传 `replace_all`），文件最大 16 MiB，只传改动的部分 |
| `append_text` | 在末尾追加；文件不存在就新建 |
| `put_sidecar` | 写元数据 |
| `make_folder` | 建文件夹，路径上缺的也一起建 |
| `move` | 移动或改名；路径上缺的文件夹自动建，目标已被占用就拒绝 |
| `delete` | 放进回收站（30 天内可恢复）。标为有破坏性，说明里要求 agent 先跟你确认 |
| `share_link` | 给文件或文件夹做分享链接：只看、可评论、只能在线看或上传，可设密码和有效期。需要 `shares:manage` |
| `request_files` | 向没有账号的人收集文件（“第三集样片，周五前”），每个人发来的放在以他名字命名的子文件夹里。需要 `shares:manage` |

### 版本和过去

| 工具 | 做什么 |
|---|---|
| `list_versions`、`label_version`、`compare_versions`、`restore_version` | 单个文件的历史、版本命名、改了什么、回退 |
| `rewind_folder` | 把整个文件夹退回到某一刻；先演练。见[看过去和整体回滚](/docs/history) |

### 审阅、分支和动作

| 工具 | 做什么 |
|---|---|
| `list_comments`、`add_comment`、`resolve_comment` | 读审阅意见、回复、标记解决 |
| `fork_space`、`fork_changes`、`apply_fork` | 在沙盒里干活，再把要留下的合并回去 |
| `list_actions`、`run_action`、`get_run` | 转写、打标签或转格式，并等待结果（默认 60 秒，最多 300 秒） |

- 参数用空间名（或 id）加路径，比如 `/Ep01/Shots/a.mov`，返回的也是路径。
- 版本可以写 id、序号（`3`、`v3`）或版本名。`compare_versions` 不传版本时比较当前版本和上一个版本。
- `as_of` 可以写时间、多久以前（`-2h`）或日志序号。
- `edit_text` 和 `append_text` 可以带 `if_version_id`，文件在那之后被存过就失败。
- 返回结构化数据的工具同时给出 `structuredContent`。
- 每个工具都按令牌的权限和空间范围检查。不允许或文件不存在时，工具返回模型能看懂的错误，模型可以据此调整。
- 改动记在令牌对应的成员名下；AI 成员的改动带 **Agent** 标记。

## 给 agent 的好习惯

服务器的 `/llms.txt` 已经告诉 agent 其中大部分规则，也值得写进你自己的提示词：

- 保存从不破坏数据：每次保存都是新版本，任何版本都能恢复。
- 结果尽量写进附加信息，而不是在原文件旁边新建文件。
- 运行动作之前先读文件的附加信息：转写或标签可能已经有了。
- 删除、批量移动、修改成员和分享之前先问人。
- 长文件只改一小处时用 `edit_text` 或 `append_text`，不要整个重写。
- 用 `rewind_folder` 之前先带 `dry_run` 跑一次，把改动清单给人看。
- 大规模整理时在分支里做，合并前把 `fork_changes` 给人看。