# 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:

```sh
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, cheapest first. Filters: GPU type, minimum GPUs, max price per GPU-hour, country. |
| `get_market_summary` | What the GPU markets list, by GPU family, and whether Arrakis rents yet. |
| `get_balance` | What the balance can pay. |
| `rent_gpu` | Rents a machine; returns it with its SSH command. Billable. |
| `list_instances` | Your machines. |
| `get_instance` | One machine, refreshed. |
| `terminate_instance` | Stops and removes a machine. |
| `schedule_removal` | Sets when a machine removes itself. |

## 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.

## A good first prompt

> Rent an H100 for 3 hours, run python eval.py, copy the results back, then stop the machine.

More: [all docs](/docs.md) · [OpenAPI](/openapi.json) · [llms.txt](/llms.txt)