# 连接 MCP 服务器

> 在 Cherry Studio、Trae、Qwen Code、Kimi Code CLI 和 Cursor 中接入 Vidmoat 的 MCP 服务器：支持 OAuth 的客户端直接登录，其他客户端把 API 密钥放进请求头。

Vidmoat 的 MCP 服务器让你的 AI 智能体直接剪视频：查看素材、编辑时间线、检查渲染出来的画面，最后导出。它和 REST API 用的是同一套引擎和同一个账号。

| | |
| --- | --- |
| 地址 | `https://api.vidmoat.com/api/mcp` |
| 传输方式 | Streamable HTTP：JSON-RPC 2.0，通过 `POST` 收发。不提供服务器推送流，`GET` 返回 `405`，客户端会自动改用 `POST`。 |
| 协议版本 | `2025-06-18`、`2025-03-26`、`2024-11-05` |
| 认证 | OAuth 登录，或请求头 `Authorization: Bearer <API 密钥>` |

## 选择认证方式

- **OAuth 登录。** 客户端第一次请求会收到 `401`，响应头 `WWW-Authenticate` 指向授权服务器的元数据（RFC 9728）。支持远程 OAuth 的客户端会自动注册、打开浏览器，让你登录 Vidmoat 并授权。任何套餐都能这样连接，也不用管理密钥。授权页需要登录，在中国大陆可能需要 VPN，见[网络说明](https://developer.vidmoat.com/developer/docs/zh-cn/network#sign-in)。
- **API 密钥（请求头）。** 每个请求都带 `Authorization: Bearer vmk_...`。适合不支持远程 OAuth 的客户端，也更适合中国大陆：只在创建密钥时登录一次，之后连接只访问 `api.vidmoat.com`。头的名字必须是 `Authorization`，值是 `Bearer`、一个空格，再加完整密钥；不接受查询参数或其他头。可用的密钥：开发者应用的测试密钥（任何套餐）、正式密钥和个人 API 密钥（这两种需要 Studio 套餐）。

不管用哪种方式，套餐功能、项目归属和积分价格都和在编辑器里完全一样。MCP 请求按账号限速：每分钟 60 次，超过返回 `429` 和 `Retry-After`。

## 测试密钥与 MCP

测试密钥可以连接 MCP，但 MCP **不会**像 REST API 那样返回示例结果。工具会以你的账号身份真实运行：编辑会改动真实项目，生成类工具按标价扣积分（每个生成工具都会写明价格），导出占用导出额度。请把这把密钥当成账号密码一样保管，并在智能体的提示里写明预算，例如「生成付费素材前先告诉我价格」。

> **提示：把密钥放在环境变量里。** 下面的示例为了直观，把密钥直接写在配置文件里。能用环境变量的客户端（Cursor、Qwen Code 命令行、mcp-remote）请优先用环境变量，并且不要把含密钥的配置文件提交到代码仓库。

## Cherry Studio

在 Cherry Studio 的设置里打开 MCP 服务器页面，添加一个服务器。可以手动填写（类型选 `streamableHttp`），也可以导入 JSON。导入时 `url` 和 `baseUrl` 两种字段名都可以，Cherry Studio 内部统一存成 `baseUrl`。

### OAuth 登录

只填地址，**不要**加 `Authorization` 请求头。Cherry Studio 只有在没有这个请求头时才走 OAuth：启用服务器后，它会在本机开一个回调端口并打开浏览器，你登录 Vidmoat 并同意授权即可。

```json
{
  "mcpServers": {
    "vidmoat": {
      "type": "streamableHttp",
      "url": "https://api.vidmoat.com/api/mcp"
    }
  }
}
```

### API 密钥

```json
{
  "mcpServers": {
    "vidmoat": {
      "type": "streamableHttp",
      "url": "https://api.vidmoat.com/api/mcp",
      "headers": {
        "Authorization": "Bearer vmk_test_你的密钥"
      }
    }
  }
}
```

依据：Cherry Studio 源代码中的 [JSON 导入示例](https://github.com/CherryHQ/cherry-studio/blob/main/src/renderer/pages/settings/McpSettings/AddMcpServerModal.tsx)和 [OAuth 连接逻辑](https://github.com/CherryHQ/cherry-studio/blob/main/src/main/ai/mcp/connections/ExternalMcpConnection.ts)（main 分支）。官方文档站这次我们没能访问到，所以格式核对自源代码，界面上的菜单名称可能随版本略有不同。

## Trae

在 Trae 中打开「设置 → MCP」，点「添加 → 手动添加」，粘贴下面的配置后点「确认」。只想在某个项目里用：在「设置 → MCP」中打开「项目级 MCP」，然后在项目根目录新建 `.trae/mcp.json`，写入同样的内容。Trae 国际版的英文界面对应 Settings → MCP → Add → Add Manually。

### API 密钥

远程服务器只需要 `url` 和可选的 `headers`，不用写 `type`。

```json .trae/mcp.json
{
  "mcpServers": {
    "vidmoat": {
      "url": "https://api.vidmoat.com/api/mcp",
      "headers": {
        "Authorization": "Bearer vmk_test_你的密钥"
      }
    }
  }
}
```

### OAuth

Trae 的文档只介绍了用请求头传递认证信息，没有提到远程服务器的 OAuth，所以我们推荐上面的密钥方式。确实需要 OAuth 时，可以把 Vidmoat 当作本地（stdio）服务器，通过 `mcp-remote` 桥接：它会自己打开浏览器完成登录（见下文[本地桥接](#stdio-bridge)）。这种做法是根据 mcp-remote 的文档推断的，我们没有在 Trae 里实际验证过。

```json
{
  "mcpServers": {
    "vidmoat": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.vidmoat.com/api/mcp"
      ]
    }
  }
}
```

依据：[Trae 官方文档《添加 MCP Server》](https://docs.trae.cn/ide/add-mcp-servers)。

## Qwen Code

Qwen Code 里远程 Streamable HTTP 服务器用 `httpUrl` 字段；`url` 字段表示旧的 SSE 传输，不要用。配置写在 `~/.qwen/settings.json`（对所有项目生效）或项目里的 `.qwen/settings.json`。添加后重启 Qwen Code，用 `qwen mcp list` 或会话里的 `/mcp` 查看状态。

### OAuth 登录

只添加地址。第一次连接时 Qwen Code 收到 `401`，会自动发现授权服务器、动态注册客户端并打开浏览器，回调地址是 `http://localhost:7777/oauth/callback`。在会话里用 `/mcp` 管理登录状态。这需要本机有浏览器；在没有浏览器的远程服务器上，请改用 API 密钥。

```bash
qwen mcp add --scope user --transport http vidmoat https://api.vidmoat.com/api/mcp
```

### API 密钥

用命令添加时，shell 会把 `$VIDMOAT_KEY` 展开成密钥本身再写进 `settings.json`。也可以直接编辑配置文件。

```bash 终端
qwen mcp add --scope user --transport http vidmoat https://api.vidmoat.com/api/mcp \
  --header "Authorization: Bearer $VIDMOAT_KEY"
```

```json ~/.qwen/settings.json
{
  "mcpServers": {
    "vidmoat": {
      "httpUrl": "https://api.vidmoat.com/api/mcp",
      "headers": {
        "Authorization": "Bearer vmk_test_你的密钥"
      }
    }
  }
}
```

依据：[Qwen Code 文档《通过 MCP 连接工具》](https://qwenlm.github.io/qwen-code-docs/zh/users/features/mcp/)和[MCP 服务器参考（OAuth 一节）](https://qwenlm.github.io/qwen-code-docs/en/developers/tools/mcp-server/)。

## Kimi Code CLI

月之暗面的命令行编程工具，命令是 `kimi`。配置写在 `~/.kimi-code/mcp.json`（对所有项目生效）或项目里的 `.kimi-code/mcp.json`（同名条目覆盖用户级配置）。有 `url` 而没有 `transport` 字段的条目就是 HTTP 服务器。也可以在会话里输入 `/mcp-config` 交互式添加，用 `/mcp` 查看连接状态。

### OAuth 登录

只写地址，然后在会话里运行 `/mcp-config login vidmoat`，在浏览器中完成授权。

```json ~/.kimi-code/mcp.json
{
  "mcpServers": {
    "vidmoat": {
      "url": "https://api.vidmoat.com/api/mcp"
    }
  }
}
```

### API 密钥

`headers` 里的内容会附加到每个请求上。

```json ~/.kimi-code/mcp.json
{
  "mcpServers": {
    "vidmoat": {
      "url": "https://api.vidmoat.com/api/mcp",
      "headers": {
        "Authorization": "Bearer vmk_test_你的密钥"
      }
    }
  }
}
```

### 旧版 Kimi CLI

还在用旧版 `kimi-cli`（配置在 `~/.kimi/mcp.json`）的话，用命令添加：

```bash API 密钥
kimi mcp add --transport http vidmoat https://api.vidmoat.com/api/mcp \
  --header "Authorization: Bearer $VIDMOAT_KEY"
kimi mcp test vidmoat
```

```bash OAuth
kimi mcp add --transport http --auth oauth vidmoat https://api.vidmoat.com/api/mcp
kimi mcp auth vidmoat
```

依据：[Kimi Code CLI 文档《MCP》](https://www.kimi.com/code/docs/en/kimi-code-cli/customization/mcp.html)；旧版见 [Kimi CLI 文档](https://moonshotai.github.io/kimi-cli/en/customization/mcp.html)。

## Cursor

配置写在 `~/.cursor/mcp.json`（对所有项目生效）或项目里的 `.cursor/mcp.json`。

### OAuth 登录

只写地址。Cursor 会提示你登录，用授权码加 PKCE 完成 OAuth；桌面版的回调地址是 `http://localhost:8787/callback`。

```json ~/.cursor/mcp.json
{
  "mcpServers": {
    "vidmoat": {
      "url": "https://api.vidmoat.com/api/mcp"
    }
  }
}
```

### API 密钥

`${env:VIDMOAT_KEY}` 会被替换成环境变量的值，密钥就不必写进文件。这个变量要在启动 Cursor 的环境里设置好。

```json ~/.cursor/mcp.json
{
  "mcpServers": {
    "vidmoat": {
      "url": "https://api.vidmoat.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:VIDMOAT_KEY}"
      }
    }
  }
}
```

依据：[Cursor 文档《Model Context Protocol》](https://cursor.com/docs/context/mcp)。

## 只支持本地（stdio）服务器的客户端

上面五个客户端都能直接连接远程 HTTP 服务器。如果你的客户端只能启动本地进程，用 [mcp-remote](https://github.com/geelen/mcp-remote) 做桥接：它在本机以 stdio 方式运行，再把请求转发到 Vidmoat。

- 带 `--header` 时用 API 密钥。冒号两边不要加空格：有些客户端启动 `npx` 时不会转义参数里的空格，所以带空格的值放在 `env` 里，由客户端把 `${AUTH_HEADER}` 替换进去。
- 不带 `--header` 时，mcp-remote 自己走 OAuth：打开浏览器登录，令牌保存在 `~/.mcp-auth`。
- 需要本机安装 Node.js。在中国大陆，npm 下载慢时可以先切换到国内镜像。

```json mcp.json：API 密钥
{
  "mcpServers": {
    "vidmoat": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.vidmoat.com/api/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer vmk_test_你的密钥"
      }
    }
  }
}
```

```bash npm 镜像
npm config set registry https://registry.npmmirror.com
```

## 验证连接

不经过任何客户端，直接用 curl 列出工具。返回一个 `tools` 数组就说明地址和密钥都没问题：

```bash
curl --fail-with-body -sS https://api.vidmoat.com/api/mcp \
  -H "Authorization: Bearer $VIDMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

工具会经常增加，请让客户端调用 `tools/list` 获取最新的名称和参数，不要照抄旧示例。`search_agent_capabilities` 可以用自然语言查找能力，`edit_project` 的 `previewAt` 参数（最多三个时间点）会把渲染出来的帧一起返回，让智能体在同一轮里看到自己改了什么。完整工具列表见英文版 [MCP tools](https://developer.vidmoat.com/developer/docs/mcp/tools)。

## 常见问题

| 现象 | 原因与处理 |
| --- | --- |
| `401` | 没带密钥、密钥写错或已撤销。确认请求头是 `Authorization: Bearer ` 加完整密钥。 |
| `429` | 超过每分钟 60 次的限制。按 `Retry-After` 等待后重试。 |
| `403 access_suspended` | 账号受限，响应里写明了原因、期限和申诉方式。 |
| 工具列表里缺少某些工具 | 你的套餐不包含对应功能，或你的密钥或授权缺少对应权限；工具描述里会写明。 |
| OAuth 浏览器打不开登录页 | 在中国大陆可能需要 VPN，或改用 API 密钥。见[网络说明](https://developer.vidmoat.com/developer/docs/zh-cn/network#sign-in)。 |

## 我们核实了什么

上面每个客户端的配置格式都核对自它自己的官方文档或源代码（2026 年 11 月）。我们没有在每个客户端里逐一实际连接测试；客户端更新后格式可能变化，如果和你的版本对不上，记住只需要两样东西：地址 `https://api.vidmoat.com/api/mcp`，和 `Authorization` 请求头。

| 客户端 | 远程 HTTP | 请求头 | OAuth | 依据 |
| --- | --- | --- | --- | --- |
| Cherry Studio | 支持（`streamableHttp`） | 支持 | 支持，没有 `Authorization` 头时自动启用 | 源代码 |
| Trae | 支持（`url`） | 支持 | 文档未提及；可经 mcp-remote 使用（推断） | 官方文档 |
| Qwen Code | 支持（`httpUrl`） | 支持 | 支持，收到 `401` 时自动发现 | 官方文档 |
| Kimi Code CLI | 支持（`url`） | 支持 | 支持，`/mcp-config login` | 官方文档 |
| Cursor | 支持（`url`） | 支持 | 支持 | 官方文档 |

- [快速开始](https://developer.vidmoat.com/developer/docs/zh-cn/quickstart)：免费测试密钥和第一个请求。
- [网络说明](https://developer.vidmoat.com/developer/docs/zh-cn/network)：在中国大陆访问和登录。
- [MCP server（英文）](https://developer.vidmoat.com/developer/docs/mcp)：Claude、ChatGPT、Claude Code 的接入方式和使用建议。
- [MCP tools（英文）](https://developer.vidmoat.com/developer/docs/mcp/tools)：每个工具和它的参数。

---

来源：https://developer.vidmoat.com/developer/docs/zh-cn/mcp
上一页：[快速开始](https://developer.vidmoat.com/developer/docs/zh-cn/quickstart.md)
下一页：[网络与访问说明](https://developer.vidmoat.com/developer/docs/zh-cn/network.md)
全部文档：https://developer.vidmoat.com/llms-full.txt
