# 連線 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-tw/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 那樣回傳範例結果。工具會以你的帳號身分真實執行：編輯會改動真實專案，生成類工具依標價扣點數（每個生成工具都會標明價格），匯出占用匯出額度。請把這把金鑰當成帳號密碼一樣保管，並在給 AI 代理的提示裡寫明預算，例如「生成付費素材前先告訴我價格」。

> **提示：把金鑰放在環境變數裡。** 下面的範例為了直觀，把金鑰直接寫在設定檔裡。能使用環境變數的用戶端（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

Moonshot AI（月之暗面）的指令列程式設計工具，指令是 `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` 參數（最多三個時間點）會把算繪出來的影格一起回傳，讓 AI 代理在同一輪就看到自己改了什麼。完整工具清單請看英文版 [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-tw/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-tw/quickstart)：免費測試金鑰和第一個請求。
- [網路說明](https://developer.vidmoat.com/developer/docs/zh-tw/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-tw/mcp
上一頁：[快速開始](https://developer.vidmoat.com/developer/docs/zh-tw/quickstart.md)
下一頁：[網路與連線說明](https://developer.vidmoat.com/developer/docs/zh-tw/network.md)
全部文件：https://developer.vidmoat.com/llms-full.txt
