--- title: Shumai MCP 服务 description: 让 Claude Code、Cursor 或 Kiro 等外部 AI 智能体与 Shumai 项目协同工作。 --- Shumai 内置了 [模型上下文协议](https://modelcontextprotocol.io)(MCP)服务。任何兼容 MCP 协议的智能体均可接入该服务,代表用户浏览项目、查看图片、视频与文档、创建文件夹以及整理资产,且调用与 Shumai 原生内置智能体完全相同的工具集。 本页面介绍如何将 **外部智能体连接至 Shumai**。若需了解如何将 Shumai 自带智能体连接至其他外部工具,请参阅 [MCP 服务](/zh/using-shumai/mcp-servers)。 --- ## 连接客户端 MCP 服务采用 Streamable HTTP 传输协议,访问端点为: ``` https:///mcp ``` Shumai 支持 **OAuth 2.1**(推荐方式,提供无缝的浏览器授权体验)以及 **API Token**(适用于无头环境或不支持 OAuth 的客户端)。 请根据所使用的客户端选择相应配置指南: ### Claude Code [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 原生支持具备 OAuth 身份验证的远程 HTTP MCP 服务。运行以下命令即可将 Shumai 添加至 Claude Code 配置: ```bash claude mcp add shumai --transport http https:///mcp ``` 启动新对话时,Claude Code 会打开浏览器窗口供登录并授予 Shumai 账户访问权限,无需手动配置 API Token。 或者,可手动配置 `.claude/settings.json`: ```json { "mcpServers": { "shumai": { "type": "http", "url": "https:///mcp" } } } ``` 或通过 `mcp-remote` 桥接 stdio: ```bash claude mcp add shumai -- npx -y mcp-remote https:///mcp ``` ### Cursor 将 Shumai 添加至 Cursor 的 MCP 配置(`~/.cursor/mcp.json` 或项目级 `.cursor/mcp.json`): ```json { "mcpServers": { "shumai": { "url": "https:///mcp" } } } ``` 当 Cursor 连接到服务时,会在浏览器中提示完成 OAuth 登录并授权访问。 若改用 API Token 验证身份,请在请求标头中传递 `Authorization`: ```json { "mcpServers": { "shumai": { "url": "https:///mcp", "headers": { "Authorization": "Bearer " } } } } ``` ### Codex ```bash codex mcp add shumai --url https:///mcp codex mcp login shumai ``` ### VS Code ```bash code --add-mcp '{"name":"shumai","type":"http","url":"https:///mcp"}' ``` 在 VS Code 的 **MCP Servers** 列表中启动该服务,并根据提示登录 Shumai。 ### 其他客户端 **远程服务 (HTTP)** 若客户端原生支持远程 HTTP MCP 服务: ```json { "mcpServers": { "shumai": { "url": "https:///mcp" } } } ``` **本地桥接 (`mcp-remote` / stdio)** 对于仅支持本地 (stdio) MCP 服务的客户端,可使用 `mcp-remote` 连接 Shumai 的远程 HTTP 端点: ```json { "mcpServers": { "shumai": { "command": "npx", "args": ["-y", "mcp-remote", "https:///mcp"] } } } ``` --- ## 身份验证 Shumai 的 MCP 服务支持两种身份验证方式: ### OAuth 2.1(推荐) Shumai 实现了基于动态客户端注册(Dynamic Client Registration, [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591))与 OAuth 受保护资源元数据(OAuth Protected Resource Metadata, [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) / [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414))规范的 OAuth 2.1。 - **无缝登录**:受支持的 MCP 客户端可自动发现授权端点并在浏览器中完成 OAuth 握手。 - **访问控制**:外部智能体以调用方在 Shumai 中的既有权限执行操作。所有行为均归属于该用户账户,并在团队审计日志中标记为 `via: mcp`。 - **清除 OAuth 缓存**:若需要在 `mcp-remote` 或 Claude Code 等 CLI 工具中重新鉴权或清除已保存的凭据,请删除本地认证缓存: ```bash rm -rf ~/.mcp-auth ``` ### API Token API Token 适用于自动化 CI/CD 流水线、无头环境或不支持交互式 OAuth 的客户端。 1. 在 Shumai 中,打开 **团队设置** → **API Token**。 2. 输入名称(例如 `ci-agent` 或 `cursor-token`),然后点击 **生成**。 3. 在弹窗中复制 Token。该 Token 仅展示一次。 4. 在请求头中传递该 Token:`Authorization: Bearer `(或通过 `x-api-key` 请求头)。 API Token 拥有与用户本人完全相同的操作权限:智能体可执行该账户在 Shumai 中所能执行的任意操作。请像保管密码一样妥善保管 Token,建议为每个客户端单独生成独立 Token,若不再使用,请前往 **团队设置** → **API Token** 及时吊销。 --- ## 可用工具列表 | 工具 | 功能说明 | | ------------------------- | --------------------------------------------------------------------------------------- | | `list_projects` | 列出当前可访问的项目及其根目录文件夹。 | | `list_assets` | 分页列出指定文件夹内的文件与子文件夹。 | | `search_assets` | 按名称、语义含义(需启用 AI 搜索)或元数据搜索文件夹及其子文件夹。 | | `create_folder` | 创建文件夹。 | | `rename_asset` | 重命名文件或文件夹。 | | `move_assets` | 将文件或文件夹移动至另一个文件夹。 | | `copy_assets` | 将文件或文件夹复制至同团队下的另一个文件夹。 | | `delete_asset` | 将文件或文件夹移至项目废纸篓。此操作标记为破坏性操作,客户端可据此要求用户确认。 | | `read_asset` | 查看文件内容:图片、视频帧、PDF 页面、3D 模型视图或文本文件内容。 | | `get_asset_render` | 获取此前仍在渲染中的 `read_asset` 任务结果。 | | `download_asset` | 获取最多 50 个文件的下载链接:默认获取 Web 预览版本,指定 `proxy: false` 可获取原文件。 | | `get_folder_instructions` | 读取文件夹中面向 AI 智能体的指引文件(AGENTS.md)。 | | `create_file` | 发起向文件夹上传新文件的流程(详见 [上传文件](#上传文件))。 | | `create_version` | 发起为已有文件上传新版本的流程。 | | `complete_upload` | 完成由 `create_file` 或 `create_version` 发起的上传流程。 | | `list_comments` | 列出文件上的审阅评论及其回复。 | | `create_comment` | 在文件上添加评论(可指定时间码)或回复评论。 | | `resolve_comment` | 将评论标记为已解决或恢复为未解决。 | | `list_metadata_fields` | 列出项目的元数据字段(如状态、评分及自定义字段)及其候选值。 | | `update_asset_metadata` | 设置文件的元数据值。 | | `create_version_stack` | 将同目录下的多个文件打包为单个资产的版本堆栈。 | | `list_versions` | 按倒序列出版本堆栈中的所有版本。 | | `remove_version` | 将指定版本移出版本堆栈(保留原文件)。 | ### 读取文件 `read_asset` 会将图片附加至调用结果中,以便 AI 模型直接识别:每次调用最多支持 8 张图片,每张大小不超过 2 MB。超出部分的图片仅以链接形式列出。每条返回结果均包含指向各图片的访问链接,有效期约为 1 小时。若客户端无法直接渲染图片,可传入 `inlineImages: false` 仅获取链接。 渲染视频帧或 PDF 页面通常耗时较长。若渲染耗时超过约 20 秒,`read_asset` 将返回状态 `status: "pending"` 与对应的 `taskId`;随后模型可携带该 `taskId` 调用 `get_asset_render` 获取最终渲染结果。仅发起读取任务的用户本人可获取其渲染结果。 ### 上传文件 上传过程分为三个阶段,以确保大文件内容无需经由 AI 模型中转: 1. `create_file`(或 `create_version`)返回 `uploadUrl` 与 `uploadId`。 2. 智能体通过 HTTP `PUT` 请求将文件二进制数据上传至 `uploadUrl`,例如使用 `curl -T video.mp4 ""`。 3. 携带 `uploadId` 调用 `complete_upload` 完成文件创建并触发后续处理(如生成预览、媒体转码)。 上传 URL 与 ID 的有效期约为 1 小时,且仅允许发起者本人确认完成上传。若项目配置了**创建上下文 (Creation Context)** 元数据字段(例如生成该文件所使用的 Prompt 或模型),可在调用 `create_file` 或 `create_version` 时将其作为 `metadata` 传入;通过 `list_metadata_fields` 可查询当前支持的字段。 智能体必须能够直接访问上传 URL。若 Shumai 配置了本地存储,该 URL 指向 Shumai 服务器;若配置了 S3 存储,则直接指向 S3 端点。 每次调用均遵循用户的实际权限执行:例如拥有 **审阅者 (Reviewer)** 角色的成员可以列出资产,但无法创建或重命名资产。所有操作均记录在团队审计日志中并归属至该用户,来源标记为 MCP。 --- ## 故障排查 - **OAuth 授权已过期或失效**:清理客户端本地 OAuth 会话缓存(`rm -rf ~/.mcp-auth`),并重启 MCP 客户端重新完成鉴权。 - **401 Unauthorized**:API Token 或 OAuth 访问令牌缺失、过期、拼写错误或已被吊销。若使用 API Token,请前往 **团队设置** → **API Token** 重新生成,并更新客户端配置。 - **工具调用出现权限错误 (Permission errors)**:当前用户在对应团队或项目中的角色无权执行该操作。