> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 連接指南

> 透過 MCP 將 AI Agent 連接到 ToAPIs，呼叫 200+ 模型生成圖片與影片。

透過 MCP 將 ToAPIs 連接到你常用的 Agent。以瀏覽器登入授權，不必複製 API Key；Agent 會幫你挑選模型、讀取參數、提交任務並取回結果。

> [!NOTE]
>
> 請依帳號與餘額所屬站點選擇位址。下方範例使用國際站；toapis.cn 帳號請將 `https://api.toapis.com/mcp` 替換為 `https://api.toapis.cn/mcp`，並使用 toapis.cn 控制台。兩站帳號與餘額不互通。

| 站點 | MCP endpoint |
| - | - |
| 國際站 | `https://api.toapis.com/mcp` |
| 中國大陸站 | `https://api.toapis.cn/mcp` |

## 連接前準備

用戶端須支援遠端 MCP 的 Streamable HTTP 傳輸。ToAPIs skills 可協助選擇模型與撰寫提示詞，屬於選用安裝；`npx skills add` 指令需要 Node.js，略過 skills 安裝仍可使用 MCP。

瀏覽器授權時，登入對應的 ToAPIs 站點，核對用戶端名稱，選擇 API Key 或新建有額度限制的專用 Key，再點選允許。使用標頭驗證時，先在 [API 權杖](https://toapis.com/dashboard/tokens) 頁面建立專用 Key，在本機替換 `<API_KEY>`。請勿將真實金鑰傳到對話或提交至版本庫。

## 選擇你的用戶端，幾步完成連接

> [accordion] Claude Code
>
> ### Claude Code
>
> 在終端機執行下列指令。第一條安裝選用 skills，第二條新增 MCP 服務。接著在 `/mcp` 中授權，並以 `claude mcp list` 檢查連線。
>
> ```bash theme={null}
> npx skills add toapis/skills -g --agent claude-code -y
> claude mcp add --transport http --scope user toapis https://api.toapis.com/mcp --header "X-Locale: zh-TW"
> ```
>
> ### 在 /mcp 中授權
>
> 在 Claude Code 中輸入 /mcp，選擇 toapis，依提示在瀏覽器登入並允許。清單中沒有 toapis 時，請先重新啟動 Claude Code。

> [accordion] Claude
>
> ### 手動新增
>
> 開啟 設定 > 連接器，新增自訂連接器。名稱填 ToAPIs，URL 填下方位址，OAuth Client ID 與 Secret 留空。
>
> ```text theme={null}
> https://api.toapis.com/mcp
> ```
>
> ### 連接並授權
>
> 點 Add，再點 Connect，在 ToAPIs 授權頁登入，選擇 Key 並允許。
>
> Claude 從 Anthropic 的伺服器存取 ToAPIs，請勿選擇設定了 IP 白名單的 Key。免費版只能新增 1 個自訂連接器。

> [accordion] Codex
>
> ### Codex
>
> 在終端機執行下列指令。第一條安裝選用 skills。新增服務時可能自動開啟瀏覽器授權，完成後再繼續。若 `codex mcp list` 顯示 `Not logged in`，執行 `codex mcp login toapis`，完成授權後重新檢查。設定完成後開啟新對話。
>
> ```bash theme={null}
> npx skills add toapis/skills -g --agent codex -y
> codex mcp add toapis --url https://api.toapis.com/mcp
> codex mcp list
> ```
>
> ### 在瀏覽器中授權
>
> Codex 會開啟 ToAPIs 授權頁：登入後核對用戶端名稱，選擇一個 Key 或新建一個設好額度上限的專用 Key，然後點「允許」。桌面版也可以在 設定 > MCP servers 中點 toapis 旁的 Authenticate。
>
> Codex CLI 與桌面版共用一份設定，設定一次兩邊都能使用。
>
> [Codex MCP](https://developers.openai.com/codex/mcp/)

> [accordion] Cursor
>
> ### 新增 ToAPIs
>
> 將下列設定合併到 `~/.cursor/mcp.json`，再於 MCP 設定中連接。
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "toapis": {
>       "url": "https://api.toapis.com/mcp",
>       "headers": {
>         "X-Locale": "zh-TW"
>       }
>     }
>   }
> }
> ```
>
> 選用 skills 安裝指令：
>
> ```bash theme={null}
> npx skills add toapis/skills -g --agent cursor -y
> ```
>
> ### 登入授權
>
> 在 Cursor 的 MCP 設定中，點 toapis 旁的 Connect，在瀏覽器登入 ToAPIs，選擇 Key 並允許。

> [accordion] Devin
>
> ### 新增 ToAPIs
>
> Devin Desktop 與 Devin CLI 共用一份設定。在終端機執行下方指令，或請 Devin 幫你執行：
>
> ```bash theme={null}
> devin mcp add -s user toapis https://api.toapis.com/mcp
> devin mcp login toapis
> ```
>
> ### 在瀏覽器中授權
>
> devin mcp login toapis 會開啟瀏覽器：登入 ToAPIs，選擇 Key 並允許。不執行這條指令時，Devin 第一次使用 toapis 也會提示登入。

> [accordion] Antigravity
>
> ### 新增到 MCP 設定
>
> Antigravity App、IDE 與 CLI 共用 `~/.gemini/config/mcp_config.json`。將下方設定合併進去並儲存，然後在 CLI 輸入 /mcp 或在設定中重新載入。
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "toapis": {
>       "serverUrl": "https://api.toapis.com/mcp",
>       "headers": {
>         "X-Locale": "zh-TW"
>       }
>     }
>   }
> }
> ```
>
> 將 `toapis` 項目合併到既有設定中，保留其他服務。
>
> ### 授權並貼上授權碼
>
> 按 Cmd + ,（Windows 為 Ctrl + ,）開啟 Antigravity 設定，進入 Customizations，點 toapis 旁的 Authenticate。在瀏覽器登入 ToAPIs 並允許後，頁面會顯示授權碼，將它貼回設定面板並點 Submit。

> [accordion] 豆包
>
> ### 新建一個專用 Key
>
> 這個用戶端只支援在請求標頭中填入 Key。在 ToAPIs 控制台新建一個 Key，建議設好額度上限，複製備用；下面設定中的 `<API_KEY>` 要換成這個 Key。
>
> [開啟 API 令牌](https://toapis.com/dashboard/tokens)
>
> ### 新建自訂外掛
>
> 開啟豆包電腦版，點左側「插件·技能·伙伴」，在「插件」頁面右上角點「+ 添加」，選擇「新建自定义插件」。伺服器名稱填 ToAPIs，傳輸類型選 HTTP，伺服器 URL 填下面的網址。
>
> ```text theme={null}
> https://api.toapis.com/mcp
> ```
>
> ### 填寫驗證並儲存
>
> 在「自定义 Headers」區域點「+ 添加」，請求標頭名稱填 Authorization，值填下面這行（把 `<API_KEY>` 換成你的 Key），然後點「保存」。
>
> ```text theme={null}
> Bearer <API_KEY>
> ```
>
> 請在豆包電腦版（Windows 或 macOS）中新增。企業帳號能否使用自訂外掛，以管理員的設定為準。

> [accordion] 千問辦公
>
> ### 新建一個專用 Key
>
> 這個用戶端只支援在請求標頭中填入 Key。在 ToAPIs 控制台新建一個 Key，建議設好額度上限，複製備用；下面設定中的 `<API_KEY>` 要換成這個 Key。
>
> [開啟 API 令牌](https://toapis.com/dashboard/tokens)
>
> ### 貼上 JSON 設定
>
> 在千問辦公左側開啟「扩展」→「连接器」，點右上角「+ 添加」→「粘贴 JSON 配置」，貼上下面的設定（把 `<API_KEY>` 換成你的 Key），然後點「导入」。
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "toapis": {
>       "type": "streamable-http",
>       "url": "https://api.toapis.com/mcp",
>       "headers": {
>         "Authorization": "Bearer <API_KEY>",
>         "X-Locale": "zh-TW"
>       }
>     }
>   }
> }
> ```
>
> ### 開啟連接器
>
> 連接器預設是關閉的：在連接器清單中開啟 toapis，然後新建一個對話任務才會生效，原本的對話中無法使用。

> [accordion] Qwen Code
>
> ### 在終端機執行
>
> 第一條安裝 ToAPIs Skill（需要 Node.js，不裝也不影響使用 MCP），第二條新增 ToAPIs MCP 服務：
>
> ```bash theme={null}
> npx skills add toapis/skills -g --agent qwen-code -y
> qwen mcp add --scope user --transport http toapis https://api.toapis.com/mcp --header "X-Locale: zh-TW"
> ```
>
> ### 在瀏覽器中授權
>
> 執行 qwen 啟動 Qwen Code，連接 ToAPIs 時會開啟瀏覽器授權頁：登入後選擇 Key 並允許。在 Qwen Code 中輸入 /mcp 可以查看 toapis 的連接與授權狀態。
>
> ### 無法使用瀏覽器授權？改用 API Key
>
> 在控制台「API 令牌」中新建一個 Key，把下面指令中的 `<API_KEY>` 換成這個 Key 後執行。
>
> ```bash theme={null}
> qwen mcp add --scope user --transport http toapis https://api.toapis.com/mcp --header "Authorization: Bearer <API_KEY>" --header "X-Locale: zh-TW"
> ```

> [accordion] Trae CN
>
> ### 新建一個專用 Key
>
> 這個用戶端只支援在請求標頭中填入 Key。在 ToAPIs 控制台新建一個 Key，建議設好額度上限，複製備用；下面設定中的 `<API_KEY>` 要換成這個 Key。
>
> [開啟 API 令牌](https://toapis.com/dashboard/tokens)
>
> ### 手動新增 MCP Server
>
> 在 Trae 中開啟「设置」>「MCP」，在「MCP Servers 管理」右上角點「添加」>「手动添加」，貼上下面的設定（把 `<API_KEY>` 換成你的 Key），然後點「确认」。
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "toapis": {
>       "url": "https://api.toapis.com/mcp",
>       "headers": {
>         "Authorization": "Bearer <API_KEY>",
>         "X-Locale": "zh-TW"
>       }
>     }
>   }
> }
> ```
>
> ### 安裝 Skill（推薦）
>
> 讓 Agent 更會挑模型、寫提示詞（需要 Node.js，不裝也不影響使用 MCP）：
>
> ```bash theme={null}
> npx skills add toapis/skills -g --agent trae-cn -y
> ```

> [accordion] WorkBuddy
>
> ### 新增自訂連接器
>
> 在 WorkBuddy 左側欄開啟「專家·技能·連接器」，選擇「連接器」分頁，點右上角「自訂連接器」，貼上下方設定並儲存。
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "toapis": {
>       "type": "http",
>       "url": "https://api.toapis.com/mcp"
>     }
>   }
> }
> ```
>
> ### 連接並授權
>
> 點 Trust 與 Connect，在開啟的 ToAPIs 授權頁登入，選擇 Key 並允許。

> [accordion] 其他用戶端
>
> ### 新增遠端 MCP 服務
>
> 在用戶端中新增一個遠端 MCP 服務（Streamable HTTP），位址填下方 URL，驗證方式選 OAuth，Client ID 與 Secret 留空。
>
> ```text theme={null}
> https://api.toapis.com/mcp
> ```
>
> ### 不支援瀏覽器登入？
>
> 部分用戶端只支援請求標頭驗證，或無法完成瀏覽器授權。可以在控制台建立專用 Key，以 Authorization: Bearer 標頭連接。
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "toapis": {
>       "url": "https://api.toapis.com/mcp",
>       "headers": {
>         "Authorization": "Bearer <API_KEY>",
>         "X-Locale": "zh-TW"
>       }
>     }
>   }
> }
> ```

## 確認連接成功

開一個新對話，傳送下面這句話。能看到餘額就表示已經連好（查詢免費）。如果提示需要登入、驗證失敗或找不到 ToAPIs 工具，回到上面的步驟檢查設定。

```text theme={null}
我的 ToAPIs 還剩多少額度？今天花了多少？
```

## 連接後可以做什麼

用自然語言描述需求，Agent 會選擇模型，依文件準備參數，提交並追蹤任務。

### 生成圖片

文生圖、參考圖編輯，可指定比例與數量。

```text theme={null}
用 ToAPIs 生成一張 16:9 的海邊燈塔日出圖
```

### 生成影片

文生影片、圖生影片，預設推薦 Seedance。

```text theme={null}
把這張產品圖做成 5 秒的直式宣傳影片
```

### 使用本機素材

直接提供本機圖片路徑，Agent 上傳後作為參考圖使用。

```text theme={null}
參考 ./product.png，把產品放到白色背景上
```

Agent 會先讀取模型參數文件，以 `create_upload` 上傳本機參考素材，再用 `get_generation` 追蹤生成狀態。任務執行中請等待結果，避免重複提交。若提交回應遺失，重試時應沿用原本的 `client_request_id`，更換 ID 可能建立新的計費任務。狀態為 `unknown` 時，先到控制台任務列表核對。請儲存回傳的結果連結，用戶端也可以將結果下載到本機。

## 可用工具

| 工具 | 用途 |
| - | - |
| `list_models` | 列出目前 Key 可用的圖片與影片模型，包含價格與 `docs_available`。 |
| `get_model_docs` | 生成前讀取模型參數文件，請選擇 `docs_available: true` 的模型。 |
| `generate_image` | 生成圖片，依模型計費。 |
| `generate_video` | 生成影片，依模型計費。 |
| `get_generation` | 以 `client_request_id` 查詢 MCP 生成進度與結果。 |
| `get_task` | 以 `task_id` 查詢圖片或影片任務。 |
| `create_upload` | 為本機圖片、影片或音訊建立一次性上傳位址。 |
| `get_balance` | 查詢 Key 額度與帳戶餘額。 |
| `list_tasks` | 列出目前 Key 的近期任務。 |
| `get_usage` | 彙總目前 Key 指定期間的扣款，最多 31 天，不扣除退款。 |

## 常見問題

> [accordion] 需要 API Key 嗎？
>
> 不必手動複製。授權時在 ToAPIs 頁面選擇一個既有的 Key，或新建一個專用 Key，Agent 透過授權權杖使用它。只支援請求標頭驗證的用戶端可以改用 API Key 方式連接。

> [accordion] 怎麼計費？
>
> 與直接呼叫 API 相同，依模型價格從所選 Key 與帳戶額度中扣除。查詢模型、餘額與任務都免費，只有生成圖片與影片會扣費。

> [accordion] Codex 為什麼要切換到完全存取？
>
> 安裝 Skill 與新增 MCP 服務需要寫入你電腦上的 Codex 設定，預設權限模式不允許 Agent 修改工作區以外的檔案。只在設定這一次需要，完成後可以切回；也可以在終端機自行執行這幾條指令。

> [accordion] 怎麼中斷連接？
>
> 在控制台「已連線應用」中中斷連線：會撤銷授權，並停用為這個連接新建的專用 Key（仍被其他連接使用時除外）。在用戶端中刪除 toapis（例如 codex mcp remove toapis）只會刪除本機設定。

> [accordion] 國際站與國內站有什麼不同？
>
> 兩個站的帳號與額度彼此獨立。toapis.com 的帳號使用 api.toapis.com/mcp，toapis.cn 的帳號使用 api.toapis.cn/mcp；在另一個站登入會提示站點不符。

> [accordion] 還支援哪些用戶端？
>
> 大多數支援遠端 MCP 與 OAuth 的桌面或命令列用戶端，都可以依「其他用戶端」的方式連接；如果授權失敗，可以改用 API Key 連接。我們會陸續補充更多用戶端的步驟。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.