> ## 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"
> ```
>
> ### 在 /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"
>       }
>     }
>   }
> }
> ```
>
> 可选 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"
>       }
>     }
>   }
> }
> ```
>
> 将 `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"
>       }
>     }
>   }
> }
> ```
>
> ### 打开连接器
>
> 连接器默认是关闭的：在连接器列表里打开 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"
> ```
>
> ### 在浏览器中授权
>
> 运行 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"
> ```

> [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"
>       }
>     }
>   }
> }
> ```
>
> ### 安装 Skill（推荐）
>
> 让 Agent 更会挑模型、写提示词（需要 Node.js，不装也不影响使用 MCP）：
>
> ```bash theme={null}
> npx skills add toapis/skills -g --agent trae-cn -y
> ```

> [accordion] WorkBuddy
>
> ### 添加自定义连接器
>
> 在 WorkBuddy 左侧栏打开“专家·技能·连接器”，选择“连接器”页签，点右上角“自定义连接器”，在弹窗中点“添加 MCP”，再粘贴下面的配置并保存。
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "toapis": {
>       "type": "http",
>       "url": "https://api.toapis.com/mcp"
>     }
>   }
> }
> ```
>
> ### 连接并授权
>
> 点击“信任”，然后在浏览器打开的 ToAPIs 授权页登录，选择 Key 并允许；登录完成后回到 WorkBuddy 点击“连接”。

> [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"
>       }
>     }
>   }
> }
> ```

## 确认连接成功

新开一个对话，发送下面这句话。能看到余额就说明已经连好（查询免费）。如果提示需要登录、鉴权失败或找不到 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.