Kilawatt

Kilawatt Cloud MCP Server

Model Context Protocol (MCP) server for requesting GPU compute capacity from Kilawatt Cloud, with account-based and x402 payment options.

This server calls the real Kilawatt gateways. Every response is an actual HTTP result from the Kilawatt public API or the x402 endpoint. There are no fabricated responses.

Table of contents

• Works with
• Endpoint
• Installation
• Configuration
• Use with Claude Desktop / Cursor
• Running the Server
• Available Tools
• Error Handling
• Links
• License

Works with

• goose (step-by-step guide: docs/GOOSE_TUTORIAL.md)
• Claude Desktop
• Cursor
• LangChain and LangGraph (example)
• CrewAI (example)
• SkyPilot (example)
• Node.js client (example)
• MCP Python SDK (example)

All examples are quote-only. See examples/README.md.

Client setup steps are in docs/clients.md.

Endpoint

The default endpoint is Kilawatt Cloud's gateway: https://www.kilawattcloud.dev/api/public/v1. Change it with the KILAWATT_BASE_URL environment variable.

Installation

Install and run via npx:

npx -y kilawatt-mcp-server

Configuration

Set your Kilawatt API key to use deploy_gpu_node. It is not required to start the server or use the x402 tools:

export KILAWATT_API_KEY=kw_live_YOUR_KEY_HERE

The API key must start with kw_live_. API keys are issued through your Kilawatt Cloud account. Contact [email protected] for assistance if you don't have access to generate keys yet.

Use with Claude Desktop / Cursor

Add this configuration to your MCP client settings:

{
  "mcpServers": {
    "kilawatt": {
      "command": "npx",
      "args": ["-y", "kilawatt-mcp-server"],
      "env": {
        "KILAWATT_API_KEY": "kw_live_YOUR_KEY_HERE"
      }
    }
  }
}

Replace kw_live_YOUR_KEY_HERE with your Kilawatt API key when using deploy_gpu_node. For x402-only use, omit KILAWATT_API_KEY.

Using goose? See GOOSE.md.

Running the Server

Start the MCP server:

npm start

Or directly:

node index.js

The server listens on stdio for MCP requests from your agent.

Available Tools

The server exposes four tools: deploy_gpu_node, x402_quote, x402_run_job and x402_job_status.

deploy_gpu_node

Provision real GPU compute on Kilawatt Cloud. This starts an actual machine and charges the caller's Kilawatt wallet. Set dry_run: true to check pricing and routing without provisioning or charging. Requires KILAWATT_API_KEY.

{
  "name": "deploy_gpu_node",
  "arguments": { "card_count": 2, "duration_seconds": 1800, "dry_run": true }
}

x402_quote

Get the current price and Base USDC payment details for a GPU job without paying.

The published input schema states a maximum of 16 for card_count. The tighter per-GPU limits above are enforced in code when the call is made.

x402_run_job

Quote and pay for one GPU job in Base USDC. Takes the same parameters as x402_quote, plus:

x402_job_status

Get the status of a job created through x402, using the API key saved locally by x402_run_job.

Differences between deploy_gpu_node and the x402 tools

• gpu_type is free text (up to 64 characters) in deploy_gpu_node but a fixed list in the x402 tools.
• card_count allows up to 64 in deploy_gpu_node but at most 16 (less for some GPUs) in the x402 tools.
• duration_seconds allows 1 to 86400 in deploy_gpu_node but 60 to 86400 in the x402 tools.
• deploy_gpu_node defaults routing_policy to lowest_cost; the x402 tools send no routing policy unless you set one.

Tool results are formatted from the real HTTP response returned by the Kilawatt gateway.

x402 settings

The x402 tools let you request capacity with Base USDC without a Kilawatt account or API key. Spend caps are enforced locally.

The server must be able to read the following environment variables when you use x402 payments:

The returned API key is stored at ~/.config/kilawatt/x402-api-key with restrictive file permissions. It is never shown in tool output. Existing deploy_gpu_node still requires KILAWATT_API_KEY.

Use a separate small wallet for x402, and keep its private key out of prompts and shared configuration. The payer does not need ETH; the facilitator submits the transaction.

For x402 users: Check that your Base wallet has enough USDC and that your spend caps allow the amount.

Error Handling

All errors are descriptive and indicate whether anything was provisioned or charged. Common scenarios:

• 400 Bad Request: Invalid arguments (e.g., card_count > 64). Fix and retry.
• 401 Unauthorized: API key missing, malformed, or revoked. Issue a new key in your Kilawatt account or contact [email protected].
• 402 Payment Required: the payment was not accepted. Check your balance and spend caps, then retry.
• 429 Rate Limited: Concurrency or rate limit hit. Retry after a delay.
• 503 No Capacity: No nodes available matching your criteria. Try a different gpu_type or smaller card_count.
• Timeout: Gateway did not respond within 60 seconds. No compute was provisioned; retry if needed.

Links

• npm Package: https://www.npmjs.com/package/kilawatt-mcp-server
• GitHub Repository: https://github.com/KilaWattCloud/kilawatt-mcp-server
• Kilawatt Cloud: https://kilawattcloud.dev
• Model Context Protocol: https://modelcontextprotocol.io

License

MIT