badgr-mcp

MCP server that lets coding agents provision GPU jobs and model endpoints — directly from Claude, Cursor, Copilot, or any MCP-compatible tool.

npx badgr-mcp

The problem it solves

Running a GPU workload normally means switching to a terminal, writing a CLI command, waiting, and copying an endpoint URL back into your editor. badgr-mcp removes all of that — your coding agent calls badgr_serve or badgr_run directly, gets the endpoint URL back, and keeps working without you leaving the editor.

Related MCP server: gpu-broker-mcp

Quick start

1. Get a Badgr API key at aibadgr.com

2. Add to your MCP config:

{
  "mcpServers": {
    "badgr": {
      "command": "npx",
      "args": ["badgr-mcp"],
      "env": {
        "BADGR_API_KEY": "your-api-key"
      }
    }
  }
}

3. Ask your agent to run a GPU job:

"Serve meta-llama/Llama-3.1-8B-Instruct on a GPU and give me the endpoint URL"

The agent calls badgr_serve, gets back the endpoint URL, and you can start using it immediately.

Available tools

badgr_serve — persistent OpenAI-compatible endpoint

Start a model endpoint that stays up until you stop it or the max runtime is reached.

badgr_serve(
  model: string,                    // HuggingFace model ID
  max_runtime_minutes: number,      // Auto-stop after N minutes (max: BADGR_MAX_RUNTIME, default 60)
  gpu?: string,                     // L40S | A100 | H100 | RTX_4090 (default: L40S)
  gpu_count?: number,               // 1–8 GPUs (default: 1)
  region?: string,                  // US | EU | AU (default: US)
  max_price_per_hour?: number,      // Hard $/hr cap
  name?: string                     // Optional label for the deployment
)

Returns: { deployment_id, endpoint_url, openai_base_url, cost_per_hour, max_runtime_minutes }

The openai_base_url is a fully OpenAI-compatible endpoint — drop it into any OpenAI SDK client.

badgr_run — one-off GPU job

Run a container command on a GPU. The job runs, completes, and is torn down automatically.

badgr_run(
  command: string[],               // Docker command, e.g. ["python", "train.py"]
  image?: string,                  // Docker image (default: python:3.11-slim)
  gpu?: string,                    // RTX_4090 | A100 | L40S | H100 (default: RTX_4090)
  gpu_count?: number,              // 1–8 GPUs (default: 1)
  region?: string,
  max_price_per_hour?: number,
  name?: string
)

Returns: { deployment_id, status, gpu_type, cost_per_hour, logs_url }

badgr_status — list active deployments

badgr_status()

Returns: list of active deployments with IDs, models, GPUs, status, and cost.

badgr_logs — fetch deployment logs

badgr_logs(deployment_id: string)

Returns: { lines: string[], log_text: string }

badgr_down — stop a deployment

badgr_down(deployment_id: string)

Terminates the deployment and stops billing immediately.

Returns: { status, message } — always call this when done.

Smithery tool names

The server also exposes tools used for registry listings (the first three are aliases or helpers for Run and Serve, the next three cover the AI API and Launch products):

Call badgr_down when a deployment is finished so billing stops.

Hosted HTTP mode

node src/server.js --http (or set PORT) serves the same tools at POST /mcp over streamable HTTP, with GET /health. Every request must carry Authorization: Bearer <Badgr API key>; the server uses that caller's key for Badgr calls, so a shared host never spends someone else's credits. The server never falls back to a BADGR_API_KEY env var in this mode, so an unauthenticated caller cannot spend the host's credits. Each request is stateless. Put TLS in front of it.

Publishing to Smithery

smithery.yaml and Dockerfile in this folder describe a stdio deployment. In Smithery, connect the GitHub repo and set the base directory to packages/badgr-mcp. Users supply badgrApiKey (plus optional price cap, runtime cap and base URL) as Smithery config, which maps to the environment variables below. Publishing on Smithery is a manual step done from a Smithery account. The smithery.yaml here describes the stdio deployment; whether Smithery's current flow wants that or the hosted HTTP mode above was not verified.

Environment variables

BADGR_MAX_PRICE and BADGR_MAX_RUNTIME are safety limits — the server enforces these regardless of what the agent requests.

Example agent workflow

Serve a model and use it:

Agent: badgr_serve("meta-llama/Llama-3.1-8B-Instruct", max_runtime_minutes=30)
← { deployment_id: "dep-abc123", openai_base_url: "https://dep-abc123.aibadgr.com/v1", cost_per_hour: 1.20 }

Agent: [uses openai_base_url to run inference]

Agent: badgr_down("dep-abc123")
← { status: "terminated", message: "Billing stopped" }

Run a fine-tuning job:

Agent: badgr_run(["python", "train.py"], gpu="A100", image="pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime")
← { deployment_id: "dep-xyz789", status: "running", logs_url: "..." }

Agent: badgr_logs("dep-xyz789")
← { log_text: "Epoch 1/10: loss=2.34..." }

Requirements

• Node.js 18+

• A Badgr API key — sign up at aibadgr.com

• An MCP-compatible coding agent (Claude, Cursor, Copilot, or any client that supports MCP)