Tools over MCP
Connect
https://api.spiral.ai/mcp as an MCP server. Your agent searches the catalog, checks a price and
runs any tool, with no tool code of your own.Models on the same key
Point your framework’s model client at Spiral’s LLM APIs (Anthropic Messages and
OpenAI formats). Claude, GPT, Gemini and the rest, on the same balance.
Set up
Create a key under API keys in the console and store it on your server asSPIRAL_API_KEY. Give it a spend cap: see keys below. Every example on this page uses that
one key and nothing else.
Pick your framework
Each example is a complete program. It asks the agent for an image; the agent looks the tool up on Spiral, runs it and answers with the image’s link.- Claude Agent SDK
- OpenAI Agents SDK
- Vercel AI SDK
- LangChain
- REST
The SDK runs Claude Code’s agent loop. Point it at Spiral for the model and add Spiral as an MCP server.
allowedTools keeps the agent to Spiral’s tools, without file or shell access.https://api.spiral.ai/mcp and the header Authorization: Bearer <key>. The MCP tools page
lists every tool and its arguments.
Run it in production
Keys and your customers
Your agent’s key stays on your server: never ship it in a browser or app bundle, and never hand it to your customers.- One key per agent or deployment, each with its own spend cap and rate limits, created under API keys. A cap is reserved before a run starts, so a runaway loop stops at the cap instead of spending your balance.
- One key per large customer when you want a hard cap for that customer, or want to revoke one customer’s access without touching the rest.
- Name the customer on every run with
end_user_id(REST, and the MCPruntool) or theX-Spiral-End-User-Idheader (LLM APIs).GET /v1/runs?end_user_id=…then lists that customer’s runs and their cost, to bill them from.
Long runs: webhooks or polling
Search, scraping and LLM calls answer in seconds. Images take seconds to a minute; video and long audio can take minutes.- Over MCP, the
runtool waits up to 60 seconds and returns the finished run; a run still going comes back with its id, and the agent callsget_rununtil it ends. - Over REST, add
webhook.urltoPOST /v1/runsand Spiral posts the finished run to your server, signed: see webhooks. Without a webhook, long-pollGET /v1/runs/{id}?wait_seconds=30.
Cost and balance
Every run holds its estimated price before it starts and is charged the measured usage when it ends; the run’scost
shows both.
estimate_cost(MCP) orPOST /v1/estimate(REST) gives a run’s price before starting it, so your agent can ask your customer before an expensive video.- A run your balance or the key’s cap cannot cover is refused before any work, with
402 INSUFFICIENT_BALANCEor a spend-cap error: nothing is charged. - A model call holds the most it can cost, its whole output cap included, until it ends. Agent loops send large output caps, so many agents running at once can hold far more than they are charged. Keep headroom in the balance, or lower the output cap where your framework sets one.
- Turn on auto top-up and balance alerts under Billing, so your agent never stops for lack of credit. See pricing.
Retries without double charges
Send anIdempotency-Key on every POST /v1/runs: a UUID you create for the intent and store with your task. A retry
with the same key returns the first run, never a second run or charge. The MCP run tool sends one for you, and the LLM
APIs take the same header. See idempotency.
Tool errors carry the same codes as the REST API, with retryable saying whether a retry can succeed: see
errors.
Next
MCP tools
Every tool your agent can call, with its arguments.
LLM APIs
The models on your key, in Anthropic and OpenAI formats.
Webhooks
Get finished runs pushed to your server, signed.
Pricing
Holds, charges, spend caps and your own prices.