Skip to main content
Glama
Sign In
@amplerun/mcp

@amplerun/mcp

Official
by ample-run
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

@amplerun/mcp

An MCP server that lets AI agents find and rent GPUs on AmpleRun: browse templates and offers, price a rental, rent within a budget you set, check its state and access, and stop it. It runs locally over stdio and wraps the TypeScript SDK, @amplerun/sdk.

Read-only by default. Nothing can be rented or stopped until you start the server with AMPLERUN_MCP_ALLOW_SPEND=1.

No install needed: the same tools are hosted at https://amplerun.com/api/mcp (Streamable HTTP, Authorization: Bearer ark_...). There, a key with the renter scope can rent and stop on its own and any other key is read-only; AMPLERUN_MCP_ALLOW_SPEND applies only to this local server. See https://amplerun.com/docs/agents.

Configure

Variable

Required

Meaning

AMPLERUN_API_KEY

For account tools

An API key with the renter scope, from Account → Security. list_templates and search_offers work without it.

AMPLERUN_MCP_ALLOW_SPEND

No

1 enables create_rental, stop_rental and a paying top_up. Any other value, or unset, keeps the server read-only.

AMPLERUN_MCP_WALLET_KEY_FILE

No

File holding a Base wallet's private key (0x…). With AMPLERUN_MCP_ALLOW_SPEND=1, top_up pays USDC from it with x402. Without spend allowed the key is never read.

AMPLERUN_MCP_MAX_TOPUP_MICRO

No

Cap per top-up payment, in micro-USDC.

AMPLERUN_BASE_URL

No

API origin. Defaults to https://amplerun.com.

AMPLERUN_AGENT_WALLET_KEY

No

A 0x-prefixed EVM private key. register_agent_account signs its challenge with it, so the agent opens its own account with no email, and the server then uses the key it was issued. The private key never leaves this process and is never printed.

top_up without a wallet returns the x402 payment requirements for your own wallet to sign. See the agents guide. Use a dedicated wallet holding only what the agent may spend.

The key is sent only as the Authorization header to the API. The server never writes it to its output, logs or error messages. It does live in your client's config file: use a renter-scoped key with an expiry, and revoke it at Account → Security when you are done.

Claude Code

# Read-only: browse and price
claude mcp add amplerun -e AMPLERUN_API_KEY=ark_... -- npx -y @amplerun/mcp

# Allow renting and stopping
claude mcp add amplerun -e AMPLERUN_API_KEY=ark_... -e AMPLERUN_MCP_ALLOW_SPEND=1 -- npx -y @amplerun/mcp

For a shared .mcp.json, add -s project and pass -e 'AMPLERUN_API_KEY=${AMPLERUN_API_KEY}' in single quotes: the file then stores a reference, and each person exports their own key.

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) and restart Claude Desktop:

{
  "mcpServers": {
    "amplerun": {
      "command": "npx",
      "args": ["-y", "@amplerun/mcp"],
      "env": { "AMPLERUN_API_KEY": "ark_..." }
    }
  }
}

Add "AMPLERUN_MCP_ALLOW_SPEND": "1" to env to allow renting.

Other MCP clients

Any client that launches stdio servers works. Command npx, arguments -y @amplerun/mcp, plus the environment above. Node.js 20 or later is required. Pin a version (@amplerun/mcp@0.1.0) where reproducibility matters.

Related MCP server: terahood-agent

Tools

Tool

Kind

What it does

list_templates

read

Published templates (pinned images such as PyTorch or an inference server), with minimum VRAM and GPU count. Filter by kind or by the VRAM you have.

search_offers

read

Machines you can rent now, cheapest first. Filters: GPU model, minimum VRAM, maximum hourly price, region, GPU count, template fit.

get_quote

read

A free, non-binding 60-second quote for a template on an offer, with the fee split. Nothing is reserved.

create_rental

write

Quotes and reserves in one step. Requires an explicit budget_micro; returns the rental_id.

get_rental

read

State, charge so far and, once running, access details (endpoints, SSH command, per-rental endpoint key for model templates).

list_rentals

read

Your rentals with state and charge, to find a rental_id again.

stop_rental

write

Stops a rental and its metering. Stopping again is harmless.

get_balance

read

USDC and USDT balances: spendable, held, pending, disputed, withdrawable, 30-day spend.

top_up

read, or write with a wallet

Adds USDC with x402. Without a wallet it returns the payment requirements; with AMPLERUN_MCP_WALLET_KEY_FILE and spending allowed it pays them. The credit lands after Base finality.

host_this_machine

read

How to list this machine's GPU so its owner earns: the installer command, steps and earnings links. Runs nothing; the owner must approve. The installer answers at amplerun.com/host (Linux with an NVIDIA GPU, rented whole, for now).

get_agent_account_challenge

write

Step 1 of an agent opening its own account: an EIP-4361 message for its wallet to sign.

register_agent_account

write

Step 2: the signed message returns an agent-tagged account and an API key (shown once). No free credit. On the hosted server both work without a key, and they are the only tools served without one.

Read tools carry readOnlyHint; write tools carry destructiveHint, so clients that honour annotations can ask before each write. In an auto-approve mode the environment flag and the budget are the guards, so leave AMPLERUN_MCP_ALLOW_SPEND unset unless the agent may spend.

Money

  • Amounts are integer strings in micro-units of the asset: "1000000" is 1 USDC. They are passed through exactly as the API returns them, never converted to floats.

  • Offer prices are per hour for the whole machine, fee included. The platform fee is a flat 5%, shown on every quote and receipt, and it comes out of the charge rather than on top.

  • fee_split in get_quote and create_rental is the most a rental can cost (the smaller of the full-duration estimate and your budget) split with the ledger's formula: fee = floor(charge × platform_fee_bps / 10000), host share = charge − fee.

  • budget_micro is a hard cap. AmpleRun holds it from your balance and meters from verified readiness, so the final charge can be lower.

Retries

create_rental sends one Idempotency-Key for its quote and its reservation and returns it. Retrying with the same idempotency_key never creates a second rental. If the first attempt reserved, the retry is refused, usually because the machine is now taken and otherwise with IDEMPOTENCY_CONFLICT, and list_rentals shows the rental. If the first attempt failed or never reached AmpleRun, the retry reserves normally.

Why a local stdio server

The MCP deployment options are a hosted remote server, a bundled local server (MCPB), or a local stdio process. This package is the third, distributed through npm, because:

  • The key can spend money. An AmpleRun API key with the renter scope spends a prepaid balance. Running locally keeps it on your machine, sent only to the AmpleRun API. A hosted MCP server would have to receive and hold every user's key, a new custodial surface, until AmpleRun offers OAuth for third-party clients.

  • The spend switch belongs to the person who owns the balance. AMPLERUN_MCP_ALLOW_SPEND is a per-install setting. A shared remote server could only offer one policy for everyone.

  • No new service to run. The package ships alongside the SDKs; a remote server would need its own hosting and release path.

  • Who uses it. Agents in Claude Code and similar tools, on machines that already have Node.js.

Update 2026-09-26: the hosted Streamable HTTP server now exists (apps/web/server/mcp.ts), authenticated with the caller's own API key per request and holding no keys; the owner chose scope-gated spending there. Still open: OAuth for clients that only accept OAuth connectors, and an MCPB bundle for Claude Desktop users without Node.js.

Development

This repository mirrors the MCP server that AmpleRun ships as @amplerun/mcp. Issues and pull requests are welcome here.

npm install
npm test               # builds this package, then runs the tests
npm run typecheck
node dist/index.js     # speaks MCP on stdin/stdout; diagnostics on stderr

test/server.test.ts drives every tool through a real MCP client with the SDK stubbed. test/stdio.test.ts spawns the built server over stdio against a local HTTP stub of the API.

Built on @modelcontextprotocol/server 2.1.0 (the official TypeScript SDK, v2).

Available Tools

12 tools
create_rentalRent a GPU (spends balance)A
Destructive

Rent a GPU on AmpleRun: quotes the template on the offer and reserves the machine in one step, holding up to budget_micro from the account balance. budget_micro is required and is a hard cap: the rental is never charged more, and metering starts only once the machine is verified ready. Returns rental_id, state, the quote, fee_split and the idempotency_key used; retrying with the same idempotency_key never creates a second rental. get_rental reports state and access. Spends money. Write tool: refused unless the server was started with AMPLERUN_MCP_ALLOW_SPEND=1 (the default is read-only).

Inputs: offer_id (required), template (required), budget_micro (required), ssh_public_key (required), +3 more.

get_agent_account_challengeStart registering this agent's own AmpleRun accountA

Step 1 of 2. Returns an EIP-4361 (Sign-In with Ethereum) message for a wallet address this agent controls, valid five minutes, single use. Signing it accepts the AmpleRun Terms version it names. Sign the message exactly as returned with personal_sign (EIP-191), then call register_agent_account with message and signature. Never send a private key to any tool.

Inputs: address.

get_balanceGet account balanceA
Read-onlyIdempotent

Get the AmpleRun account's USDC and USDT balances as micro-unit strings: spendable (available for new rentals), held by live rentals, pending, disputed and withdrawable, plus the last 30 days' spend. Read-only; needs AMPLERUN_API_KEY.

Inputs: no named parameters.

get_quoteGet a rental quoteA
Read-only

Price a rental without committing: creates a free, non-binding AmpleRun quote (valid 60 seconds; nothing is reserved or charged) for a template on an offer, capped by budget_micro. Returns the quote exactly as the API sent it plus fee_split: the most the rental can cost and how that divides into the platform fee (platform_fee_bps) and the host's share. Needs AMPLERUN_API_KEY with the renter scope. create_rental quotes again when it reserves, so this step is optional.

Inputs: offer_id (required), template (required), budget_micro (required), duration_limit_s (required), +1 more.

get_rentalGet rental status and accessA
Read-onlyIdempotent

Get one AmpleRun rental by rental_id: state, cumulative charge (micro-units), rate and funded-through time. While it is RUNNING (verified ready), and read-only for a limited window after STOPPED, also returns access: endpoints, SSH host-key fingerprint, a ready-made command and, for model templates, the endpoint's per-rental API key. Read-only. list_rentals finds rental ids.

Inputs: rental_id (required).

host_this_machineEarn with this machine's GPUA
Read-onlyIdempotent

Explains how to add the GPU of the machine this agent runs on to AmpleRun, so its owner earns from rentals. Returns the one-line installer command, the steps and the earnings links. It runs nothing itself. The installer needs root, so ask the machine's owner before running it, and the owner must approve the machine from the approve_url it prints: nothing is listed without that approval.

Inputs: no named parameters.

list_rentalsList my rentalsA
Read-onlyIdempotent

List the account's AmpleRun rentals with state, charge so far (micro-units), rate and funded-through time. Ordered by id, not by time; page with next_cursor. Read-only. get_rental gives details and access for one rental.

Inputs: limit, cursor.

list_templatesList GPU templatesA
Read-onlyIdempotent

List published AmpleRun templates: pinned container images a rental runs, such as an inference server with fixed model weights or a PyTorch or Jupyter runtime. Returns each template's id, slug (template_id), name, kind, engine, minimum VRAM in bytes and minimum GPU count, plus next_cursor. Read-only; no API key needed. search_offers finds machines for a template.

Inputs: kind, limit, cursor, gpu_vram_gib.

register_agent_accountRegister this agent's own AmpleRun accountA

Step 2 of 2. Opens an AmpleRun account for this AI agent, tagged as agent-created, with its wallet as the verified payout wallet, and returns an API key (shown once; keep it secret). The same wallet again returns the same account and a new key. There is no free credit: renting needs a deposit first. Pass message and signature from get_agent_account_challenge. scopes defaults to ["renter"]; add "host" to host machines.

Inputs: agent (required), scopes, message, signature.

search_offersSearch GPU offersA
Read-onlyIdempotent

Search GPU machines that can be rented now on AmpleRun. gpu_model, gpu_count and max_rate_micro_per_hour filter on the server. min_vram_gib and region filter each fetched page here because the API has no such filters, so a page can return fewer than limit matches: scanned is how many offers were checked, and next_cursor continues. Prices are micro-units per hour for the whole machine, fee included; cheapest first. With template, each offer carries fit {fits, reason}. Read-only; no API key needed.

Inputs: limit, cursor, region, template, +4 more.

stop_rentalStop a rentalA
DestructiveIdempotent

Stop an AmpleRun rental: ends the workload and its metering. Files inside the machine stay reachable read-only only for a limited retrieval window. Stopping again is harmless. Returns rental_id and the new state (STOPPING or a later state). Write tool: refused unless the server was started with AMPLERUN_MCP_ALLOW_SPEND=1 (the default is read-only).

Inputs: rental_id (required), reason, idempotency_key.

top_upGet top-up payment instructionsA
Read-onlyIdempotent

Get what it takes to top up the AmpleRun USDC balance by amount_micro with x402: the payment requirements (network, USDC contract, treasury payTo, amount, EIP-712 domain). A wallet signs them as an EIP-3009 transferWithAuthorization and repeats POST /api/v1/billing/x402/top-up with the PAYMENT-SIGNATURE header (@amplerun/sdk does this with its x402 option). This server holds no wallet, so it pays nothing; an operator who configures AMPLERUN_MCP_WALLET_KEY_FILE and allows spending lets it pay.

Inputs: amount_micro (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.4/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools target distinct resources and actions, and the two-step account registration is clearly separated. Minor overlap exists between get_quote and create_rental because create_rental also quotes before reserving, though the descriptions explain when each is needed.

    Naming Consistency4/5

    The tool set consistently uses snake_case and generally follows a verb_noun pattern such as list_templates, create_rental, get_rental, and stop_rental. A few names deviate slightly, like get_agent_account_challenge and host_this_machine, but they remain readable and predictable enough.

    Tool Count5/5

    Twelve tools are well-scoped for a GPU rental marketplace that includes account setup, template and offer discovery, quoting, rental lifecycle, balance, top-up, and hosting. Each tool appears to earn its place without obvious redundancy or extreme thinness.

    Completeness4/5

    The surface covers the core renter lifecycle from account creation through renting, monitoring, stopping, and funding. A notable gap is the absence of a withdrawal or payout operation despite get_balance reporting withdrawable balances, and host management is only explained rather than fully exposed.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers