Jungle Grid MCP Server

01

Overview

The MCP server exposes Jungle Grid as an agent tool surface. It can estimate workloads without submitting them, create signed upload slots for files and scripts, submit asynchronous jobs, inspect status and lifecycle events, read persisted logs, list uploaded inputs, list output artifacts, create temporary artifact download information, and cancel non-terminal jobs.

• •Hosted clients authenticate with OAuth access tokens, not raw API keys.
• •The hosted server uses POST /mcp for MCP Streamable HTTP requests.
• •ChatGPT or another hosted app should be described as compatible only when that client can complete MCP OAuth discovery and connection.
• •Jungle Grid exposes an OpenAI Apps challenge endpoint when the hosted server is configured with OPENAI_APPS_CHALLENGE_TOKEN, but that token itself is operational configuration and not a user secret.

MCP endpoint: https://mcp.junglegrid.dev/mcp
Protected resource metadata: https://mcp.junglegrid.dev/.well-known/oauth-protected-resource
Authorization server metadata: https://api.junglegrid.dev/.well-known/oauth-authorization-server
OAuth issuer: https://api.junglegrid.dev
Supported scopes: jobs:estimate jobs:submit jobs:read logs:read

Client or Agent
  -> upload_job_input (optional)
  -> estimate_job
  -> submit_job
  -> get_job_events
  -> get_job
  -> get_job_logs
  -> list_artifacts
  -> get_artifact
  -> cancel_job when needed

GET /mcp without Authorization returns:
401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.junglegrid.dev/.well-known/oauth-protected-resource"

02

Configuration

Local MCP hosts run the npm package over stdio. Hosted deployments run Streamable HTTP and introspect OAuth access tokens. In local mode, the server reads JUNGLE_GRID_API_KEY and forwards requests to the Jungle Grid API base.

• •Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).
• •Cursor: .cursor/mcp.json in your project root, or the global MCP settings in Cursor preferences.
• •Windsurf and MCP Inspector can use the same stdio command and environment block.
• •JUNGLEGRID_API_BASE is the preferred API base override and defaults to https://api.junglegrid.dev.
• •JUNGLE_GRID_API_URL is a supported legacy alias.
• •Restart your AI host after editing the config file.

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

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

{
  "mcpServers": {
    "junglegrid": {
      "command": "npx",
      "args": ["-y", "@jungle-grid/mcp"],
      "env": {
        "JUNGLE_GRID_API_KEY": "jg_placeholder",
        "JUNGLE_GRID_API_URL": "https://your-orchestrator.example.com"
      }
    }
  }
}

03

Tool Reference

These names match the current MCP tool registry. Read-only tools declare readOnlyHint=true. submit_job can start compute and spend credits. cancel_job is destructive because it can stop active work.

• •estimate_job requires jobs:estimate, jobs:read, or jobs:write on the upstream API route.
• •submit_job and upload_job_input require jobs:submit or jobs:write.
• •list_jobs, list_job_inputs, get_job, get_job_events, list_artifacts, and get_artifact require jobs:read or compatible write scope.
• •get_job_logs requires logs:read, jobs:read, or jobs:write.
• •The status filter for list_jobs is passed as a string; it is not a fixed MCP enum.
• •get_artifact returns temporary download information. Treat returned URLs as secrets.

Required: workload_type
Optional: model_size, image, command, args, routing_mode, template, notes
Accepted workload_type: inference, training, fine_tuning, batch
Accepted routing_mode: cost, speed, balanced
Returns: classification, routing, capacity, cost range, availability, screening

Required: name, workload_type, image
Optional: command, args, env, input_files, script_files, script_file, expected_artifacts, routing_mode, template, metadata
input_files/script_files: [{ "input_id": "inp_..." }]
Returns: job_id, status, routing fields, input/script details, artifact contract when returned

Required: filename
Optional: content_type, kind
Returns: upload.input_id, method, upload_url, token, expires_at, complete_url
Follow-up: PUT bytes to upload_url, then POST complete_url with token and file metadata.

list_job_inputs()
list_jobs(limit?, cursor?, status?)
get_job(job_id)
get_job_events(job_id)
get_job_logs(job_id, limit?, cursor?)
cancel_job(job_id, reason?)
list_artifacts(job_id)
get_artifact(job_id, artifact_id)

04

Simple Production Example

A simple job estimates first, submits only after approval, then polls status, lifecycle events, and logs until it reaches completed, failed, rejected, or cancelled. Artifacts are listed after completion.

{
  "workload_type": "batch",
  "image": "pytorch/pytorch:2.4.0-cuda12.1-cudnn9-runtime",
  "command": ["python", "-c", "from pathlib import Path; Path('/workspace/artifacts/output.txt').write_text('done')"],
  "routing_mode": "balanced"
}

{
  "name": "mcp-simple-artifact",
  "workload_type": "batch",
  "image": "pytorch/pytorch:2.4.0-cuda12.1-cudnn9-runtime",
  "command": ["python", "-c", "from pathlib import Path; Path('/workspace/artifacts/output.txt').write_text('done')"],
  "expected_artifacts": ["/workspace/artifacts/output.txt"],
  "routing_mode": "balanced"
}

get_job({ "job_id": "job_123" })
get_job_events({ "job_id": "job_123" })
get_job_logs({ "job_id": "job_123", "limit": 100 })
list_artifacts({ "job_id": "job_123" })
get_artifact({ "job_id": "job_123", "artifact_id": "art_123" })

05

File-Backed Example

For files and scripts, upload first and keep the returned input_id. The MCP upload tool creates the signed upload slot; your client still uploads bytes to upload_url and completes the upload using complete_url.

• •Script uploads mount at /workspace/scripts/<filename>.
• •Input uploads mount at /workspace/inputs/<filename>.
• •The current REST submit path supports one uploaded script reference.
• •Submit returns JOB_INPUT_NOT_FOUND when an input_id is unknown and JOB_INPUT_NOT_READY when the upload was not completed.

{
  "filename": "transcribe.py",
  "content_type": "text/x-python",
  "kind": "script"
}

{
  "name": "mcp-file-backed-transcription",
  "workload_type": "inference",
  "image": "pytorch/pytorch:2.4.0-cuda12.1-cudnn9-runtime",
  "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"]
}

get_job_events({ "job_id": "job_123" })
get_job({ "job_id": "job_123" })
get_job_logs({ "job_id": "job_123", "limit": 100 })
list_artifacts({ "job_id": "job_123" })
get_artifact({ "job_id": "job_123", "artifact_id": "art_transcript" })

06

Status, Events, Logs, Runtime, and Artifacts

Agents should not treat status, events, logs, runtime, and artifacts as one stream. Status is a snapshot, events are lifecycle activity, logs are persisted workload/platform log entries, runtime summarizes execution details, and artifacts are output files.

• •get_job returns current state, execution phase, status message, phase timing, delayed_start, scheduling, failure information, billing, and artifact readiness when returned by the API.
• •get_job_events returns lifecycle events that can exist before workload logs begin.
• •get_job_logs returns persisted log entries with pagination; it is not true streaming.
• •The current MCP server does not register a runtime-specific tool. Use get_job for runtime-adjacent status fields and the REST API when full /v1/jobs/{job_id}/runtime details are required.
• •list_artifacts returns artifact metadata; get_artifact creates temporary download information.

07

Troubleshooting

Most issues come from missing OAuth tokens for hosted MCP, missing API keys for local stdio, stale host configuration, incomplete uploads, unsupported CPU-only workloads, or checking logs before the workload process has started.

• •Hosted 401 with WWW-Authenticate — the client has not completed OAuth or sent a valid access token for https://mcp.junglegrid.dev.
• •Local error: JUNGLE_GRID_API_KEY is required — the env block in your host config is missing or the key name has a typo. Check the exact field name matches JUNGLE_GRID_API_KEY.
• •Tools not appearing in the host — restart the AI host after editing the config file. Some hosts require a full quit-and-reopen, not just a reload.
• •Stale package version — clear the npx cache or pin the current package version in your MCP config.
• •Empty logs before startup — call get_job_events to inspect queueing, scheduling, provisioning, and runtime preparation.
• •Artifact not ready — wait for completion and call list_artifacts again before get_artifact.
• •Terminal job cancellation — completed, failed, rejected, or already cancelled jobs return a conflict.
• •Verify the server starts correctly by running it directly in a terminal before adding it to the host config.

JUNGLE_GRID_API_KEY=jg_placeholder npx @jungle-grid/mcp

npx @modelcontextprotocol/inspector npx @jungle-grid/mcp