# API Key 与自定义 MCP 客户端

## 选择认证方式

自定义客户端支持 OAuth 时，将 `https://i2v.ai/api/mcp` 添加为 Streamable HTTP 服务，按 [OAuth 发现流程](/docs/mcp/oauth)授权。脚本、后端或令牌型客户端可在 [API Key 设置](/me?section=api-keys)创建密钥，通过密钥管理工具或 `I2V_API_KEY` 提供。仅把密钥发送到对应的 i2v.ai API 主机。账户额度和 IP 白名单仍然生效。

## 验证远程握手

```bash
curl -fsS https://i2v.ai/api/mcp \
  -H "Authorization: Bearer $I2V_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"i2v-check","version":"1.0.0"}}}'
```

查看响应的 `serverInfo` 和协商后的 `protocolVersion`。使用 MCP SDK 可自动处理握手、JSON 和服务端事件流。初始化后调用 `tools/list`，然后用 `tools/call` 调用 `list_models`，参数传 `{"mediaType":"image"}`。获取完整目录时，根据 `offset`、`limit` 和 `total` 翻页。

## 配置客户端

以下命令让 Codex 从启动时的环境变量读取密钥。

```bash
codex mcp add i2v --url https://i2v.ai/api/mcp --bearer-token-env-var I2V_API_KEY
```

其他客户端可在凭据设置中配置 `Authorization: Bearer YOUR_API_KEY`。启用了白名单时，要核对客户端实际请求的来源 IP，托管客户端的请求可能来自其自身网络。

## 用 REST 查余额和消耗

```bash
curl -fsS 'https://api.i2v.ai/api/v1/account' \
  -H "Authorization: Bearer $I2V_API_KEY"
curl -fsS 'https://api.i2v.ai/api/v1/account/usage?range=30d' \
  -H "Authorization: Bearer $I2V_API_KEY"
```

金额口径和认证故障见[账户、权限与更新](/docs/mcp/account-and-access)。