Request access

Use Node Lodge from an AI agent (MCP)

Let Claude Code, Claude Desktop or your own agent find a GPU, launch a session under a hard spending cap, connect over SSH and stop it.

The Node Lodge MCP server lets an AI agent rent GPU machines for you. The agent lists offers, checks your balance, launches a session with a maximum cost, reads the SSH details and stops the session when the work is done. Every session is paid from your organization credit, and the agent can never spend more than the limits you set on its API key.

It works with any client that speaks the Model Context Protocol (MCP), including Claude Code and Claude Desktop.

Before you start

  • Node.js 22 or newer on the machine that runs the agent.
  • Credit on your organization. See Billing.
  • An SSH key pair. See SSH keys.

1. Create a key for the agent

  1. In the console, open Keys and choose Create key.
  2. Name it after the agent, for example claude-code.
  3. Pick the scopes workloads:read, workloads:write and billing:read.
  4. Set its Spending limits:
    • Per session: the most one session can cost.
    • Total: the most the key can ever spend.
    • Calendar month and Sessions at a time are optional.
  5. Copy the key. It is shown once.

Node Lodge enforces these limits on its servers, on the budget of each session: a session that would go past one is refused before anything is reserved or started. A running session counts for its whole budget, an ended one for what it was billed. You can lower or raise the limits later with Edit limits, after a fresh two-factor code. A lower limit applies to the next session.

2. Download the server

mkdir -p ~/.nodelodge && cd ~/.nodelodge
curl -fsSLO https://nodelodge.com/downloads/nodelodge-mcp.mjs
curl -fsSLO https://nodelodge.com/downloads/nodelodge-mcp.mjs.sha256
sha256sum -c nodelodge-mcp.mjs.sha256

On macOS, use shasum -a 256 -c nodelodge-mcp.mjs.sha256 for the last line. The file is one script, run with Node. Download it again to update.

3. Connect your client

Claude Code

claude mcp add nodelodge \
  --env NODELODGE_API_KEY=nl_live_... \
  -- node ~/.nodelodge/nodelodge-mcp.mjs

Run claude mcp list to check that nodelodge is connected, or type /mcp in a session.

Claude Desktop

Open Settings, then Developer, then Edit Config, and add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "nodelodge": {
      "command": "node",
      "args": ["/Users/you/.nodelodge/nodelodge-mcp.mjs"],
      "env": { "NODELODGE_API_KEY": "nl_live_..." }
    }
  }
}

Use the full path to the file: on Windows, for example C:\\Users\\you\\.nodelodge\\nodelodge-mcp.mjs. Restart Claude Desktop. The Node Lodge tools appear in the tools menu of a new chat.

Over HTTP

For clients that connect to a URL, start the server in HTTP mode on your own machine:

node ~/.nodelodge/nodelodge-mcp.mjs --http

It listens on http://127.0.0.1:3101/mcp and stores no key: each request sends its own key as a Bearer token. With Claude Code:

claude mcp add --transport http nodelodge http://127.0.0.1:3101/mcp \
  --header "Authorization: Bearer nl_live_..."

Set NODELODGE_MCP_PORT to use another port. The server answers only requests addressed to this machine.

Tools

Tool What it does
list_offers Lists Node Lodge Secure machines with GPU, VRAM, CPU, RAM, disk, hourly price in USD, country and city. Filters by GPU model, GPU count, VRAM and price.
get_balance Shows the credit available for a new session, what is held and what is owed.
list_environments Lists the environments launch_session accepts on Node Lodge Secure machines.
launch_session Starts a machine with a budget. max_cost_usd is required: it is reserved on your credit and the session never costs more.
get_session Shows status, cost so far, the launch step under way while the machine starts (launch_step) and, once the machine runs, the ssh command and how to open JupyterLab.
stop_session Stops a session: billing stops and the machine and its disk are deleted.
raise_session_budget Raises the budget of a running session to a new max_cost_usd, within the limits of the key.
list_sessions Lists live or ended sessions.

How max_cost_usd works

launch_session takes max_cost_usd, the most the session may cost. It is reserved on your credit at launch as the budget of the session. Billing follows the real time the machine runs, from the moment it is ready, and Budget Guard stops the session before the budget is spent: you are never billed past it. With duration_hours, the session also stops after that many hours.

The launch is refused, before anything is reserved or started, when max_cost_usd is above your available credit or above a limit of the key. A session stopped early is billed for the time it ran, and the rest of the budget is released. To keep a session running longer, raise_session_budget reserves more, under the same checks.

launch_session also needs the SSH public key to install on the machine and the public IPv4 address you will connect from (or a range up to /24). Only that address can reach the machine over SSH. The public key opens this session only: it is not saved on your account. environment_id is optional, jupyterlab by default, the environment data-center machines run.

JupyterLab

JupyterLab runs on the machine and listens on the machine only. Once the session runs, get_session gives connect.jupyter: an ssh_command that opens the same shell and forwards JupyterLab to port 8888 of your computer, the url to open while that connection stays open, and the token to type on the sign-in page. The token is a secret: keep it out of addresses and logs. connect.jupyter comes to the key that launched the session, with workloads:write.

Resources and prompts

Besides its tools, the server offers read-only resources that a client can attach to a conversation:

Resource Content
nodelodge://offers The machines bookable now, cheapest first
nodelodge://sessions Your live sessions
nodelodge://sessions/{session_id} One session, with its cost so far and SSH details

And two prompts, ready-made requests that set the steps and the rules:

  • launch_cheapest_gpu (model, max_cost_usd, optional min_vram_gb): estimates the VRAM the model needs and says it is an estimate, finds the cheapest machine with that much, checks your balance, asks you to confirm, then launches with your maximum and never raises it.
  • stop_all_sessions: lists your live sessions, warns that stopping deletes each machine and its disk, asks you to confirm, stops them and checks that none is left.

In Claude Desktop and Claude Code, resources appear in the attachment menu (@ in Claude Code) and prompts as slash commands, for example /mcp__nodelodge__stop_all_sessions in Claude Code.

Worked example

You ask Claude Code:

Find the cheapest GPU with at least 48 GB of VRAM, run my fine-tuning script on it within the budget I give you, and stop the machine when it is done. My public key is in ~/.ssh/id_ed25519.pub.

The agent then:

  1. Calls list_offers with min_vram_gb: 48 and picks the cheapest bookable offer, for example a 1× RTX A6000 in Montreal.

  2. Calls get_balance and checks that your available credit covers the budget.

  3. Asks you to confirm, then calls launch_session:

    {
  "offer_id": "3f0c8f5e-8c3a-4f39-9a8e-2d9b4c1e7a10",
  "max_cost_usd": 20,
  "ssh_public_key": "ssh-ed25519 AAAAC3... you@laptop",
  "allowed_cidr": "203.0.113.7"
}

    The max_cost_usd budget is reserved on your credit, and the machine starts provisioning.

  4. Calls get_session until connect is set, then runs ssh ubuntu@198.51.100.4, copies the script, runs it and copies the results back.

  5. Calls stop_session. The session is billed for the time it ran, and the rest of the budget is released.

If the agent had set max_cost_usd above the per-session limit of its key, Node Lodge would have refused the launch with API_KEY_LIMIT, and nothing would have been reserved or started.

Errors the agent may see

Code Meaning
CREDIT_INSUFFICIENT max_cost_usd is above your available credit. Add credit in Billing, or lower the maximum.
API_KEY_LIMIT The budget would go past a limit of the key. Lower max_cost_usd, raise the limit in Keys, or wait for a session to end.
MAX_COST_EXCEEDED The hours asked cost more than max_cost_usd. Shorten duration_hours or raise the maximum.
API_KEY_NOT_ALLOWED The key lacks a scope the tool needs. Create a key with the three scopes above.
OFFER_UNAVAILABLE The machine was taken in the meantime. Call list_offers again.

Good practice

  • Give each agent its own key with tight limits, so you can revoke one without touching the others.
  • Keep the key out of shared files and repositories. Claude Code stores it in your local configuration.
  • Ask the agent to confirm before it launches a session or raises max_cost_usd.
  • Every launch, budget raise and stop made with the key is listed in Activity, with the key that made it.

Last updated View as Markdown