# MCP Server SeedRouter runs a remote [Model Context Protocol](https://modelcontextprotocol.io) server. An AI agent can use it to list image and video models, read their request schemas and prices, submit generation tasks and fetch the results, without you writing integration code. ```text https://api.seedrouter.ai/v1/mcp ``` * **Transport:** Streamable HTTP, stateless. The server supports protocol version `2026-07-28` and the earlier versions that start with an `initialize` handshake, back to `2024-11-05`. * **Authentication:** your SeedRouter API key as a Bearer token, `Authorization: Bearer YOUR_API_KEY`. Create one on the [API keys page](https://seedrouter.ai/apikeys); see [Authentication](https://seedrouter.ai/docs/api/authentication). * **Billing:** the same as the HTTP API. Every `submit_task` call is one request to the matching task endpoint and is charged in the same way. Clients that can only sign in with OAuth, with no field for a custom header, cannot connect yet. ## Connect a client The [API keys page](https://seedrouter.ai/apikeys) has a **Connect via MCP** button that fills in one of your keys for each client below. ### Claude Code ```bash claude mcp add --transport http seedrouter https://api.seedrouter.ai/v1/mcp \ --header "Authorization: Bearer YOUR_API_KEY" ``` ### Cursor Add to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a project: ```json { "mcpServers": { "seedrouter": { "url": "https://api.seedrouter.ai/v1/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` ### Codex CLI Codex reads the key from an environment variable: ```bash export SEEDROUTER_API_KEY=YOUR_API_KEY codex mcp add seedrouter --url https://api.seedrouter.ai/v1/mcp \ --bearer-token-env-var SEEDROUTER_API_KEY ``` Codex stores the variable name, not the key. Start Codex from a shell where `SEEDROUTER_API_KEY` is set, for example by exporting it in your shell profile. ### VS Code Add to `.vscode/mcp.json`: ```json { "servers": { "seedrouter": { "type": "http", "url": "https://api.seedrouter.ai/v1/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` Any other client that supports remote Streamable HTTP servers with a custom `Authorization` header is set up the same way. ## Tools | Tool | What it does | Charges your balance | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | `list_models` | Lists the model IDs `submit_task` accepts, each with its documentation link. Optional `endpoint`: `images` or `videos`. | No | | `get_model_schema` | Returns the JSON Schema of a model's request body. Rules that JSON Schema cannot express, such as conditional requirements and cross-field limits, are enforced by the API and described on the model's documentation page. | No | | `get_pricing` | Returns a model's current list prices in USD, from the same live rates billing uses, including any [model tiers](https://seedrouter.ai/docs/api/model-tiers). | No | | `submit_task` | Submits one task: `model` plus `input`, the request body described by `get_model_schema`. Returns a task ID. | **Yes**, for every call that creates a task | | `get_task` | Returns a task's status and output. Optional `wait_seconds` (0–50) waits on the server while the task is still running. | No | | `get_balance` | Returns the remaining balance, in USD, of the account that owns the key. | No | `submit_task` is not idempotent. Retrying a call creates and charges a second task, so check `get_task`, `get_balance` or your [task history](https://seedrouter.ai/tasks) before retrying a call whose result you did not receive. ## Typical flow 1. `list_models` with `endpoint: "images"`. 2. `get_model_schema` for the model you picked. 3. Optionally, `get_pricing` to see the rate first. 4. `submit_task` with `model` and an `input` that matches the schema. 5. `get_task` with `wait_seconds: 50`, repeated while `status` is `processing`, then read `output`. Seedance tasks report `queued` and `running` before `succeeded`. Generation is asynchronous, exactly as in the HTTP API: `submit_task` returns as soon as the task is accepted. `wait_seconds` saves the agent from polling in a loop, but a long video can still need several `get_task` calls. If a status check fails for a temporary reason during the wait, such as a rate limit or a server error, `get_task` returns the last `processing` result instead of the error; call it again. ## Rules carried over from the HTTP API * Reference images, videos and audio must be public `http(s)` URLs. Base64 input is rejected. * When the HTTP API answers, its response body is the tool result unchanged, with the same [error codes](https://seedrouter.ai/docs/api/errors). Errors raised before a request reaches it, such as an unknown model or invalid tool arguments, come back as a plain error message. A rejected key on the MCP endpoint itself is an HTTP `401`. * Failed tasks are not charged. * An account can have up to 50 image and video tasks in progress at once by default. Further submissions return HTTP `429` with code `30002` until running tasks finish; see [Use SeedRouter from AI agents](https://seedrouter.ai/docs/api/agents). * Model IDs and parameters are the ones in each model's documentation. A model appears in `list_models` once it is live on the API. * Text models are not offered over MCP. Call them on the [text endpoints](https://seedrouter.ai/docs/api/overview), or run a coding agent on them as described in [Coding agents on SeedRouter](https://seedrouter.ai/docs/api/coding-agents).