Jungle Grid MCP Server

Jungle Grid MCP lets MCP-aware agents estimate, submit, monitor, cancel, and retrieve artifacts from Jungle Grid workloads. It supports local stdio clients and hosted Streamable HTTP deployments that forward tool calls to the Jungle Grid API.

Use it for asynchronous AI workload execution, batch processing, training, fine-tuning, uploaded file or script backed jobs, lifecycle diagnostics, workload logs, and managed output artifacts.

Installation

Requirements:

• Node.js 18 or newer
• A Jungle Grid API key for local stdio, or an OAuth bearer token for hosted HTTP
• API scopes that match the tools you want to call

Run the local stdio server with npx:

JUNGLE_GRID_API_KEY=jg_placeholder npx -y @jungle-grid/mcp

Install globally if you prefer a stable executable:

npm install -g @jungle-grid/mcp
junglegrid-mcp

Configuration

Local stdio uses environment variables:

Hosted HTTP gateway deployments also support:

Never commit API keys, OAuth tokens, signed upload URLs, signed artifact URLs, or callback secrets.

Connection Modes

Local stdio

Local clients launch the package and communicate over stdio.

{
  "mcpServers": {
    "junglegrid": {
      "command": "npx",
      "args": ["-y", "@jungle-grid/mcp"],
      "env": {
        "JUNGLE_GRID_API_KEY": "jg_placeholder"
      }
    }
  }
}

Claude Desktop

Add the same mcpServers block to claude_desktop_config.json, then fully quit and reopen Claude Desktop.

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Cursor

For project config, avoid checked-in secrets. Put the key in the environment used to launch Cursor:

{
  "mcpServers": {
    "junglegrid": {
      "command": "npx",
      "args": ["-y", "@jungle-grid/mcp"]
    }
  }
}

For a local uncommitted Cursor config:

{
  "mcpServers": {
    "junglegrid": {
      "command": "npx",
      "args": ["-y", "@jungle-grid/mcp"],
      "env": {
        "JUNGLE_GRID_API_KEY": "jg_placeholder",
        "JUNGLEGRID_API_BASE": "https://api.junglegrid.dev"
      }
    }
  }
}

Hosted HTTP

The HTTP server exposes:

• GET /healthz
• GET /.well-known/oauth-protected-resource
• POST /mcp

Start it locally:

MCP_TRANSPORT=http PORT=3000 JUNGLEGRID_INTERNAL_SERVICE_TOKEN=service_token_placeholder npm start

Hosted MCP clients must send Authorization: Bearer <oauth_access_token> to POST /mcp. The server introspects tokens at /oauth/introspect on the configured API base and requires tool-specific scopes.

Minimal Working Example

Ask your MCP client to call the tools in this order:

{
  "tool": "estimate_job",
  "arguments": {
    "workload_type": "batch",
    "image": "python:3.11-slim",
    "command": ["python", "-c", "print('hello from Jungle Grid')"],
    "routing_mode": "balanced"
  }
}

If the estimate is acceptable, submit the job:

{
  "tool": "submit_job",
  "arguments": {
    "name": "mcp-hello",
    "workload_type": "batch",
    "image": "python:3.11-slim",
    "command": ["python", "-c", "print('hello from Jungle Grid')"],
    "expected_artifacts": ["/workspace/artifacts/output.txt"]
  }
}

Use the returned job_id with get_job, get_job_events, get_job_logs, list_artifacts, and get_artifact.

MCP Tools

The current tool registry exposes these exact tool names:

Accepted workload_type values are inference, training, fine_tuning, and batch. The MCP server forwards fine_tuning to the REST API as fine-tuning. Accepted routing_mode values are cost, speed, and balanced.

Tool Details

estimate_job

Returns classification, route status, capacity source, estimated cost range, availability, and screening details when returned by the API. An estimate is not a reservation and does not guarantee immediate startup.

Common errors: missing workload_type, invalid enum value, authentication failure, forbidden scope, invalid request, upstream API error.

{
  "workload_type": "inference",
  "model_size": 7,
  "image": "pytorch/pytorch:2.4.0-cuda12.1-cudnn9-runtime",
  "command": ["python", "infer.py"],
  "routing_mode": "balanced",
  "notes": "single model inference run"
}

submit_job

Creates an asynchronous job. model_size is an optional size in GB used to select suitable GPU capacity and is forwarded as REST model_size_gb. command is preferably an array of strings. env must be an object with string values and is forwarded as REST environment. input_files and script_files accept arrays of { "input_id": "..." }; string IDs are normalized for compatibility. The current REST implementation supports one uploaded script reference.

Expected response includes job_id, status, queued_at or submitted_at, routing fields, input/script details, and artifact contract fields when returned by the API.

Common errors: missing name, image, or workload_type; invalid workload type; command or args too long; invalid environment values; missing or incomplete input IDs; insufficient funds; unavailable capacity; maintenance; authentication or scope failures.

{
  "name": "transcribe-audio",
  "workload_type": "inference",
  "model_size": 7,
  "image": "python:3.11-slim",
  "command": ["python", "/workspace/scripts/transcribe.py", "/workspace/inputs/audio.ogg", "/workspace/artifacts/transcript.txt"],
  "script_files": [{ "input_id": "inp_script123" }],
  "input_files": [{ "input_id": "inp_audio123" }],
  "expected_artifacts": ["/workspace/artifacts/transcript.txt"],
  "routing_mode": "balanced",
  "metadata": {
    "request_id": "req_123"
  }
}

upload_job_input

Creates a signed upload slot. It does not upload file bytes by itself. Upload the bytes to upload.upload_url using upload.method, then complete the upload with upload.complete_url and the returned upload.token.

kind is an arbitrary string accepted by the API. Use input for normal input files and script for scripts by convention. Script uploads mount under /workspace/scripts/<filename>; input uploads mount under /workspace/inputs/<filename>.

Expected response:

{
  "upload": {
    "input_id": "inp_123",
    "filename": "transcribe.py",
    "method": "PUT",
    "upload_url": "https://signed-upload.example",
    "token": "upload_token",
    "expires_at": "2026-06-11T12:15:00Z",
    "complete_url": "https://api.junglegrid.dev/v1/job-inputs/inp_123/complete"
  }
}

Common errors: missing filename, invalid filename, file too large, upload storage unavailable, authentication or scope failure.

list_job_inputs

Returns uploaded inputs with input_id, filename, content_type, size_bytes, kind, status, ready, mount_path, and timestamps when available.

list_jobs

Returns jobs, limit, next_cursor, and has_more. limit is capped by the API. status is a free-form filter string passed to the API; do not assume the MCP schema restricts it to a fixed enum.

get_job

Returns the current job status and details. Status, execution phase, lifecycle events, runtime details, and workload logs are separate surfaces.