Use BatchRouter from an MCP client
Install the BatchRouter MCP server so an AI agent in Claude, Cursor or any MCP client can browse models, price a batch, run it and collect the results.
The BatchRouter MCP server, @batchrouter/mcp, exposes the public API as tools. An AI agent can browse the model catalog, price a batch, submit one and collect the results — without you writing any HTTP code.
The server runs locally over stdio and needs Node 20 or newer. You also need a BatchRouter API key: see Create an API key.
Configure your client
Edit claude_desktop_config.json (Settings → Developer → Edit Config):
{
"mcpServers": {
"batchrouter": {
"command": "npx",
"args": ["-y", "@batchrouter/mcp"],
"env": { "BATCHROUTER_API_KEY": "br_live_your_key_here" }
}
}
}Quit and restart the app. BatchRouter's tools appear in the tools menu.
Any other MCP client works the same way: run npx -y @batchrouter/mcp as a stdio server with BATCHROUTER_API_KEY in its environment.
Configuration
| Variable | Required | Default | What it does |
|---|---|---|---|
BATCHROUTER_API_KEY | yes | — | Your API key. The server exits with a clear message if it is missing. |
BATCHROUTER_BASE_URL | no | https://api.batchrouter.com | Point at a different API base URL. |
BATCHROUTER_TIMEOUT_MS | no | 30000 | Per-request timeout, so a stalled call never hangs the agent. |
BATCHROUTER_ENABLE_WRITES | no | off | Add the tools that change things. See Write tools. |
The key is read once at startup, never logged, and redacted from any error the model sees.
Tools
Read-only by default. Out of the box the server can look at things and price things, and that is all — it cannot create a batch, cancel one, or spend a cent.
| Group | Tools |
|---|---|
| Catalog | list_models, get_model, list_workflow_products, get_workflow_product |
| Providers & pricing | list_providers, get_provider, get_fee_schedule, health |
| Quotes | quote_model, quote_workflow — free, and reserve no credit |
| Batches | list_batches, get_batch, list_batch_items, get_batch_results, get_batch_artifact_url, get_batch_billing_receipt, list_batch_webhooks |
| Usage | list_usage |
| Following a run | wait_for_batch |
Every name is prefixed batchrouter_, so the tools compose safely alongside other MCP servers. Some API replies are very large, so the server leaves out any nested field over 4 kB and says which. Pass response_format: "raw" when you need the complete, untrimmed API payload.
Account settings and API keys are not available as tools: manage those in the dashboard.
Use a read-only key
A key with the read_only role can list, look up and quote, but cannot spend. It covers everything the default install does.
Write tools
To let the agent submit and manage batches, add BATCHROUTER_ENABLE_WRITES:
"env": {
"BATCHROUTER_API_KEY": "br_live_your_key_here",
"BATCHROUTER_ENABLE_WRITES": "1"
}This adds run_batch, create_batch, cancel_batch, retry_batch, upload_file, create_run, quickstart and agent_register.
Write tools can spend your balance
A client with write tools enabled can spend your account balance. Use a separate key for the MCP server so you can revoke it without disturbing anything else, and confirm before approving cancel_batch, the one tool marked destructive. Every tool that costs money says so in its description.
The golden path
Ask for the work, and the agent handles the sequence:
"Price running these 500 support tickets through a cheap model, then run it if it's under $5."
That is quote_model to price it, run_batch to quote and submit in one step, wait_for_batch to follow it, and get_batch_results once it completes. run_batch always quotes before it submits and reports the price it committed to, so the number you are shown is the number that was reserved. See Quotes & pricing for how a quote is built.
Retrying safely
Tools that spend money carry an idempotency key. When you don't pass one, the server derives it from the request, so an identical retry is safe by default. If a call fails or times out, retry with the same key — it is in the previous reply, on success and on failure. A different key submits a second batch and charges again. See Idempotency & retries.
Following a long batch
Batches are asynchronous, and results exist only once the state is completed. Use wait_for_batch, which returns the current state plus a safe next-poll delay; don't poll in a tight loop. For a large batch, prefer get_batch_artifact_url — a signed link to the full JSONL — over pulling every result through the conversation. See Poll & retrieve results.
Troubleshooting
"BATCHROUTER_API_KEY is not set" — the env block is missing, or the client did not pass it through. Check that the config file you edited is the one your client actually reads.
Tools do not appear — fully restart the client after editing its config. In Claude Desktop, check Settings → Developer for the server's status.
401 on every call — the key is wrong, expired or revoked. Retrying will not help; replace it.
"insufficient credit" — top up in the dashboard. Quotes are free, so you can price work before funding it. See Credits & billing.
A tool you expected is missing — write tools need BATCHROUTER_ENABLE_WRITES.