# Connect an agent to Arrakis

Arrakis exposes eight compute tools through MCP. Connect your client to `$ARRAKIS_URL/mcp` with your own bearer token; `$ARRAKIS_URL` is the origin of your Arrakis deployment, with no trailing slash. The console is at [/console/](/console/).

## Create a bounded credential

In the console's API & agents page, create a token with `read` and `rent` scopes, a spend cap, a maximum rental duration and an expiry. Copy the token once and keep it in your client's secret storage. Do not commit it to a repository. A caller creating another token needs `manage`; a child can never gain scopes or exceed its parent's remaining spend cap or maximum rental duration.

## Claude Code

Replace the placeholder token before running this command:

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

## Cursor

Add an entry to your MCP configuration. This is a configuration shape, not an executed connection; substitute your actual origin and token. Cursor does not expand `$ARRAKIS_URL` in this JSON.

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

## Other clients

Use MCP streamable HTTP at `$ARRAKIS_URL/mcp` with `Authorization: Bearer <your-token>`. The endpoint uses stateless JSON responses, not SSE or persistent server sessions. Use a client that supports this transport.

For a local stdio connection, use an installed Arrakis CLI:

```sh
export ARRAKIS_BASE_URL="$ARRAKIS_URL"
# Set ARRAKIS_TOKEN through your secret manager.
arrakis mcp
```

The local command requires `ARRAKIS_TOKEN`. The remote endpoint does not require a local CLI installation.

## Tools

| Tool | Arguments | Cost or change |
|---|---|---|
| `search_gpus` | Optional `gpu_type`, `min_gpus`, `max_price_per_gpu_hour`, `country`; `limit` defaults to 10 | Reads available machines, cheapest first. Does not rent. |
| `get_market_summary` | None | Reads live aggregate prices and availability. No charge. |
| `get_balance` | None | Reads your prepaid balance. No charge. |
| `rent_gpu` | `node_id`, `name`, `termination_hours`; optional `gpu_count`, `template_id`, `ssh_key_id`, `idempotency_key` | Creates a billable rental. Returns the instance, state, SSH command and idempotency key. Generates a key if absent. |
| `list_instances` | None | Reads your instances. No new rental. |
| `get_instance` | `instance_id` | Reads one of your instances. No new rental. |
| `terminate_instance` | `instance_id` | Removes the machine; save your results first. |
| `schedule_removal` | `instance_id`, `at` | Sets the machine's removal time. Use an ISO 8601 timestamp. |

## Safety boundaries

- MCP calls use your token against the same API as the console. Scopes, tenant isolation, expiry and spend caps still apply. API failures are tool errors containing the API's `detail`.
- Capped tokens must set `termination_hours`. A rental reserves its worst-case cost: machine price per hour multiplied by the rental duration. Committed spend cannot exceed the token's cap; a rejected rental returns 402. Committed spend is not a live balance that resets when a machine stops.
- A token's maximum rental duration is enforced independently of its spend cap.
- Reuse the same `idempotency_key` when retrying a rental. If the initial response is lost, a new key is a new request; supply a stable key before the first call when automatic retries matter.
- A deposit request is pending, not spendable money. Only operator confirmation credits the balance.
- Token secrets are shown once, stored hashed and revocable. Never give an agent the operator credential or your bootstrap secret.
- Independent hosts run the machines. Keep regulated data off them and copy results to storage you control.

Example prompt (not an executed rental):

> Rent the cheapest H100 under $2 per hour for 3 hours, run `python eval.py`, copy results back, then shut it down.

The price in this prompt is a search ceiling, not a market quote. SSH and running the command require your agent's own terminal tools; the MCP tools above manage compute.

See [agent walkthrough](/docs/agent-walkthrough.md), [security](/docs/security.md), [API reference](/docs), [OpenAPI](/openapi.json) and [/llms.txt](/llms.txt).