# API key and custom MCP clients

## Choose authentication

For a custom client with OAuth support, add `https://i2v.ai/api/mcp` as a Streamable HTTP server and follow [OAuth discovery](/docs/mcp/oauth). For a script, backend, or token-based client, create an API key in [API key settings](/me?section=api-keys) and supply it from your secret store or `I2V_API_KEY`. Send the key only to the intended i2v.ai API host. The key's account limits and IP allowlist still apply.

## Verify the remote handshake

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

Check the returned `serverInfo` and negotiated `protocolVersion`. An MCP SDK handles initialization and JSON or server-sent event responses. After initialization, call `tools/list`, then `tools/call` with `name: list_models` and `arguments: {"mediaType":"image"}`. Continue with the response's `offset`, `limit`, and `total` when listing all results.

## Configure a client

Configure Codex to read the key from the environment that launches it.

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

For other clients, set `Authorization: Bearer YOUR_API_KEY` through their credential settings. Check that the client's actual source IP matches an allowlist if you use one. Hosted clients may connect from their own network.

## Query balances and usage over 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"
```

See [Account, access, and updates](/docs/mcp/account-and-access) for the reported amounts and authentication errors.