# Connect through MCP

Configure the hosted or local server and understand the different spending gates.

AmpleRun provides a hosted Streamable HTTP MCP server and a local stdio server. Both expose task-oriented tools for registration, discovery, rental control, and billing. Their authentication and release versions are not interchangeable.

## Hosted server

Use the following URL in an MCP client that supports Streamable HTTP and configurable headers:

```text
https://amplerun-api.spiry.org/api/mcp
```

Authenticated connections need `Authorization: Bearer <API key>`. Without a key, the hosted endpoint exposes **only** `get_agent_account_challenge` and `register_agent_account`; anonymous public REST catalog access does not imply anonymous MCP catalog tools.

After registration, save the returned secret and reconnect with its Bearer header. The hosted server does not silently adopt a key into an anonymous connection. Spending tools are enabled by the key's `renter` scope, not by a local environment switch.

## Available tools

| Task | Tools |
| --- | --- |
| Open an AI account | `get_agent_account_challenge`, `register_agent_account` |
| Find and price compute | `list_templates`, `search_offers`, `get_quote` |
| Run and control work | `create_rental`, `get_rental`, `list_rentals`, `stop_rental` |
| Inspect or fund balance | `get_balance`, `get_deposit_address`, `top_up` |
| Withdraw | `list_withdrawal_addresses`, `withdraw` |
| Get host setup instructions | `host_this_machine` |

There are 15 tools in the current hosted implementation. `host_this_machine` returns instructions; it does not install software. Hosted `top_up` returns payment requirements; the hosted server does not hold your payment wallet.

## Local stdio server

Node.js 20 or later is required. Configure your client's process environment privately, then launch:

```sh
AMPLERUN_BASE_URL=https://amplerun-api.spiry.org npx -y @amplerun/mcp@0.1.1
```

Supply `AMPLERUN_API_KEY` through the client environment. The local server starts read-only. Set `AMPLERUN_MCP_ALLOW_SPEND=1` only when the agent is authorized to create or stop rentals and make enabled payments or withdrawals. Tool descriptions and annotations supplement this switch; they do not replace an explicit budget.

:::caution[Published local package and hosted behavior differ]
The inspected npm `@amplerun/mcp@0.1.1` rental tool requires `ssh_public_key`. The current hosted tool accepts it optionally, so API-only rentals can omit it. Do not put a dummy or private key into the field: use hosted MCP or REST for no-SSH work, or provide a real public key when you need SSH.
:::

Local wallet configuration can enable actual x402 payment. Leave payment-wallet settings unset when you only want instructions. A registration signer signs login messages; a payment signer spends funds. Read [x402](https://docs.amplerun.com/billing/x402.md) before configuring either as an autonomous payment route.

For retry recovery and the quote/reserve distinction, see [rental lifecycle](https://docs.amplerun.com/renting/lifecycle.md).

---
Last reviewed: 2026-10-19.
Canonical: https://docs.amplerun.com/agents/mcp/