Agents (MCP)
Run orl from an agent, as commands or as MCP tools, with cost caps, JSON errors and no prompts. Add it to Claude and choose which tools to expose.
orl mcp serve exposes the OpenRelay API as Model Context
Protocol tools over stdio, so an agent can
deploy VMs, read usage, and manage resources by calling tools instead of
shelling out. It uses the key and org you are already logged in with, so the
agent inherits your access with no extra credentials.
Add it to Claude
Register orl as an MCP server in one command:
claude mcp add openrelay -- orl mcp serveClaude Code (and other MCP clients like Claude Desktop) can now call OpenRelay
tools directly. Log in first with orl auth login,
or export OPENRELAY_API_KEY: from orl 0.7.0 the key alone is enough, since
the server reads the org from it.
orl init --agent (0.7.0) does the setup for a project: it registers the server in
.mcp.json (or .cursor/mcp.json with --mcp cursor), adds an orl section to
AGENTS.md, and writes .env.example with OPENRELAY_API_KEY and the
OpenAI-compatible base URL. It never writes a key.
The agent journey
From orl 0.7.0 the default tools cover a batch job end to end. As commands:
orl models --batch-only --json # what can run as a batch, and its price
orl estimate --input-file requests.jsonl --json # the most it can cost, before it runs
orl batches create --input-file requests.jsonl --max-cost 5 --idempotency-key job-1 --json
orl batches wait <batch-id> --timeout 9m --json # exit 9: still running, run it again
orl batches results <batch-id> --out results.jsonl --errors-out errors.jsonl --json| Tool | What it does |
|---|---|
models | Callable models with APIs, batch eligibility and online prices |
estimate | The cost bound of a JSONL file (local path or file id) or a token count |
batches_create | Upload a local JSONL (input_file) and create the batch; idempotency_key makes a retry return it |
batches_wait | Wait up to timeout (default 60s, at most 10m); WAIT_TIMEOUT means call it again |
batches_results | Download the output and error files and return their paths, counts and the batch's cost |
chat | One chat completion, with usage and the server's cost for it; set max_tokens |
doctor | Check the key, both hosts and the balance |
Spending is capped
Tools that spend (chat, batches_create) are refused when their cost bound is
over the server's per-call cap: $1 unless you start the server with
--max-cost (or set ORL_MAX_COST_USD). A call can lower the cap with
max_cost_usd, never raise it, and a job whose cost cannot be bounded (a
request without max_tokens, an unpriced model) is refused rather than guessed.
claude mcp add openrelay -- orl mcp serve --max-cost 25On the command line the same cap is --max-cost on orl chat and
orl batches create, or ORL_MAX_COST_USD for every job.
Reference for the agent
orl help --llm prints a compact markdown reference to put in an agent's
context (--all for every command and flag), and orl schema <command> prints
JSON Schemas for a command's flags and output.
Choose what to expose
By default orl mcp serve exposes a curated core set of tools: the journey
above plus account, catalog, usage and VM tools. Widen or narrow it:
orl mcp serve --toolset vms,snapshots # core set plus these groups
orl mcp serve --all # every tool
orl mcp serve --all --read-only # every read (GET) tool, nothing that writes| Flag | Effect |
|---|---|
--toolset <group> | Add a tool group (repeatable or comma separated); group names are the command groups from orl --help |
--all | Expose every available tool |
--read-only | Expose only read tools |
--max-cost <usd> | Per-call cap on tools that spend (default $1; 0.7.0) |
Keep the toolset small
Many MCP clients degrade above roughly 50 tools. Prefer --toolset over --all
so the agent sees a focused, relevant set. Use --read-only when you want an
agent that can inspect but never change anything.
How access works
The agent acts as you: the tools run against the organization your key is
bound to, with that key's scopes. Tools that delete or replace something
(terminating a VM, overwriting a results file) are marked destructive so a client
can gate them; tools that spend are capped per call instead (see above). To give an agent a
narrower footprint, log in with a key that has fewer scopes, or serve
--read-only. To cap what the agent spends on inference, give it a key with a
budget:
orl api-keys create --name agent --budget-usd 25 --budget-period daily. The
budget covers inference and batches, not compute, and is checked against an
estimate of each request's cost, so a request or a batch can pass it before
the key is refused. For a hard limit on everything the
agent spends, give it its own organization with a fixed prepaid balance and
auto-recharge off.