# i2v.ai MCP

通过 MCP，客户端可以选择 i2v.ai 模型、校验实际输入、预检美元报价、提交任务或查询账户。想直接复制配置，可以打开 [MCP 接入页](/mcp)。

## 选择客户端

| 客户端 | 接入指南 |
| --- | --- |
| Codex CLI 与 Codex IDE 扩展 | [Codex](/docs/mcp/codex-cli) |
| Claude Code | [Claude Code](/docs/mcp/claude-code) |
| Gemini CLI | [Gemini CLI](/docs/mcp/gemini-cli) |
| Claude Desktop 与 Claude 网页版 | [Claude 连接器](/docs/mcp/claude-desktop) |
| Cursor | [Cursor](/docs/mcp/cursor) |
| VS Code 与 GitHub Copilot | [VS Code 与 GitHub Copilot](/docs/mcp/vscode-copilot) |
| ChatGPT 网页版 | [ChatGPT](/docs/mcp/chatgpt) |
| 脚本和其他远程 MCP 客户端 | [API Key 与自定义客户端](/docs/mcp/api-key) |
| 可启动本地进程的客户端 | [本地 stdio](/docs/mcp/local-stdio) |
| 自己开发 OAuth 客户端 | [OAuth 集成](/docs/mcp/oauth) |

## 服务地址与权限

远程 MCP 地址为 `https://i2v.ai/api/mcp`，使用无状态 Streamable HTTP，通过 `POST` 调用。支持 OAuth 的客户端可在浏览器登录并授权。使用 API Key 时，在 MCP 请求中发送 `Authorization: Bearer YOUR_API_KEY`。REST 账户与生成接口使用 `https://api.i2v.ai`。

| OAuth 权限 | 可以执行的操作 |
| --- | --- |
| `mcp:read` | 查询模型、报价、余额、消耗和自己的任务，以及搜索文档。客户端未申请权限时默认只读。 |
| `mcp:write` | 上传素材和提交生成。需要客户端发起申请、你明确授权，并包含只读权限。 |

有效的 API Key 可以读写所属账户，同时受[密钥设置与 IP 限制](/docs/authentication)约束。撤销和排查步骤见[账户、权限与更新](/docs/mcp/account-and-access)。

## 验证只读连接

把下面的指令发给客户端即可验证连接。

> 请调用 i2v.ai 的 `list_models`，设置 `mediaType: image`，翻页直到取齐 `total` 条结果。请显示每个图片模型的名称和 ID，再用 `get_account` 显示当前连接的权限。请勿创建任务。

要查消费，调用 `get_usage`，例如 `range: 30d`。结果按 UTC 入账日期提供结算费用、用量退款、已核实历史净额和净消耗。可用余额与预留金额通过 `get_account` 查询。

## 工具参考

| 工具 | OAuth 权限 | 返回内容 |
| --- | --- | --- |
| `list_models` | 读 | 支持筛选和分页的公开目录 |
| `get_model_params` | 读 | 当前模型入参和素材限制 |
| `recommend_models` | 读 | 满足用途和约束的模型候选 |
| `prepare_generation` | 读 | 入参校验、归一设置、美元报价和模型版本 |
| `estimate_cost` | 读 | 为已有客户端保留的账户报价工具 |
| `create_task` | 写 | 提交后的任务 ID 和计费信息 |
| `get_task` | 读 | 自己任务的状态与产物地址 |
| `recover_submission` | 读 | 按原凭据找回提交回执 |
| `get_account` | 读 | 余额、预留、资金分类与权限 |
| `get_usage` | 读 | 整个账户的结算费用、退款和净消耗 |
| `search_docs` | 读 | 匹配的接入与模型文档 |
| `create_upload_url` | 写 | 用于直传的临时地址 |
| `complete_upload` | 写 | 上传对象的验证结果 |

本地 stdio 还提供公开价格查询，配置工作目录后可上传或下载本地文件。首单与恢复见[生成与恢复](/docs/mcp/workflow)，账户查询、撤销和版本检查见[账户、权限与更新](/docs/mcp/account-and-access)。