Amplerun MCP

@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

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.

Tools

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