Connect through MCP

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:

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:

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.

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 before configuring either as an autonomous payment route.

For retry recovery and the quote/reserve distinction, see rental lifecycle.