Agents and MCP

Give an agent a token it can't overspend, and connect it over MCP.

Give the agent its own token

On API & agents, create a token for the agent with only what it needs:

Scopes read and rent (not manage or billing).
A spend cap in dollars, a longest rental in hours, and an expiry.

The token is shown once. Keep it in the agent's secret store, never in a prompt or a repository. A capped token must set a shutdown time on every rental, and a rental that would pass its cap is refused.

Connect over MCP

The MCP endpoint is $ARRAKIS_URL/mcp, using the agent's token. It speaks MCP's streamable HTTP with plain JSON responses.

Claude Code:

Shell

claude mcp add --transport http arrakis $ARRAKIS_URL/mcp --header "Authorization: Bearer ark_..."

Cursor (mcp.json):

JSON

{
  "mcpServers": {
    "arrakis": {
      "url": "$ARRAKIS_URL/mcp",
      "headers": { "Authorization": "Bearer ark_..." }
    }
  }
}

Tools

Tool	What it does
`search_gpus`	Finds machines best first: what the GPU can do, its price and how reliable its host is. Names a pick and why. Filters: GPU type, minimum and maximum GPUs, memory, max price per GPU-hour, country.
`get_market_summary`	Live prices and availability by GPU family.
`get_balance`	What the balance can pay.
`rent_gpu`	Rents a machine; returns it with its SSH command. Boots `template_id`, or any public `image`. Billable.
`deploy_model`	Serves a Hugging Face model with vLLM, SGLang or llama.cpp on a machine sized for it; returns its endpoint and API key (Deploy a model). Billable.
`list_images`	The Arrakis images and your saved ones, for `template_id`.
`list_instances`	Your machines.
`get_instance`	One machine, refreshed, with any notice from its host.
`get_events`	What happened to your machines: ready, ended and why (evicted by its host or not), and their hosts' notices. Every tool result also carries the last day's alerts.
`terminate_instance`	Stops and removes a machine.
`schedule_removal`	Sets when a machine removes itself.
`get_partner_earnings`	Partners: your codes and link, the customers you brought, what you earned, and whether the partner program is open.
`join_partner_program`	Joins the partner program for the account, if its owner agrees (/partners).

Retries never rent twice

Give each intended rental a stable idempotency_key. Retrying with the same key returns the same machine instead of a second bill. Over MCP, a call without a key that repeats the same machine, name and hours within 10 minutes also returns the first machine.

A good first prompt

Reading this as an agent? This page as Markdown.