Use Jungle Grid From AI Agents and Apps

01

Hosted MCP over OAuth

The hosted MCP server is a Streamable HTTP gateway. It challenges unauthenticated requests with OAuth protected-resource metadata, uses the Jungle Grid authorization server at https://api.junglegrid.dev, introspects access tokens, and forwards scoped tool calls to the orchestrator MCP envelope API.

• •Hosted clients authenticate with OAuth access tokens, not raw jg_... 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

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

02

Local stdio compatibility

Local MCP hosts such as Claude Desktop, Cursor, Windsurf, and MCP Inspector can run the npm package over stdio. In this mode the local process reads JUNGLE_GRID_API_KEY and forwards tool calls to the Jungle Grid API. Use this only on machines where local environment variables are acceptable for MCP secrets.

• •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.
• •JUNGLE_GRID_API_URL is the legacy local stdio API base override and defaults to https://api.junglegrid.dev.
• •The newer hosted gateway also supports JUNGLEGRID_API_BASE as its canonical API base env var; JUNGLE_GRID_API_URL remains a supported alias.
• •Restart your AI host after editing the config file.

JUNGLE_GRID_API_KEY=jg_... npx -y @jungle-grid/mcp

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

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

03

Available tools

Hosted MCP tool names below match the current standalone MCP server. Read-only tools declare readOnlyHint=true. submit_job can start real compute and spend credits; cancel_job is destructive because it can stop a running job.

• •estimate_job — read-only; estimates routing, capacity, and cost before submission. Requires jobs:estimate.
• •submit_job — side-effecting; submits a workload and may spend credits. Requires jobs:submit.
• •list_jobs — read-only; lists recent jobs with pagination and optional status filtering. Requires jobs:read.
• •get_job — read-only; returns status and detail for one job. Requires jobs:read.
• •get_job_logs — read-only; fetches stored log entries for a job. Requires logs:read.
• •cancel_job — side-effecting and destructive; cancels pending, queued, or running jobs. Requires jobs:submit.
• •list_artifacts — read-only; lists managed result artifacts for a job. Requires jobs:read.
• •get_artifact — read-only but sensitive; creates temporary download information for an existing artifact. Requires jobs:read.

04

Real-time job pattern

GPU jobs can run for seconds to hours. submit_job returns immediately with a job_id, then the agent polls get_job and reads get_job_logs until the job reaches a terminal state. Managed jobs can also write files into /workspace/artifacts and retrieve them later through the artifact tools.

result = submit_job(
    workload_type="inference",
    image="python:3.11-slim",
    command=["python", "-c", "import os; exec(os.environ['CODE'])"],
    environment={
        "CODE": "import os, json\nos.makedirs('/workspace/artifacts', exist_ok=True)\nwith open('/workspace/artifacts/output.json','w') as f:\n    json.dump({'status':'ok'}, f)"
    },
)
job_id = result.id

# 2. Watch logs in real time
logs = get_job_logs(jobId=job_id, limit=100)
print(logs)

# 3. Poll until done if needed
while True:
    job = get_job(job_id=job_id)
    if job.status in ("completed", "failed", "cancelled"):
        break
    sleep(10)

# 4. Retrieve saved artifacts
artifacts = list_artifacts(jobId=job_id)
download = get_artifact(jobId=job_id, artifactId=artifacts[0]["artifact_id"])

05

Submit request shape

Hosted submit_job accepts workload intent, image, optional command and args, routing mode, environment variables, and saved credential IDs. Local stdio compatibility versions may model command as an array; check the tool schema surfaced by your host.

• •Use environment for large inline scripts, tokens, or runtime configuration that should not bloat the command array.
• •Anything written to /workspace/artifacts is automatically saved as a Jungle Grid artifact for managed jobs.
• •For GPU-accelerated PyTorch or Diffusers jobs, prefer CUDA-enabled images such as pytorch/pytorch:2.2.0-cuda12.1-cudnn8-runtime. Generic bases like python:3.11-slim can fall back to CPU when CUDA user-space libraries are missing.
• •Use estimate_job before submit_job when cost matters — it returns the expected tier, region, and credit cost without starting a real job.

{
  "command": ["python", "-c", "import os; exec(os.environ['CODE'])"],
  "environment": {
    "CODE": "import os, json\nos.makedirs('/workspace/artifacts', exist_ok=True)\nwith open('/workspace/artifacts/output.json','w') as f:\n    json.dump({'status':'ok'}, f)"
  }
}

06

Troubleshooting

Most issues come down to a missing OAuth token for hosted MCP, a missing API key for local stdio, a stale npx cache, or a host that was not restarted after config changes.

• •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 a current version such as ["-y", "@jungle-grid/mcp@0.1.9"].
• •Verify the server starts correctly by running it directly in a terminal before adding it to the host config.

JUNGLE_GRID_API_KEY=jg_... npx @jungle-grid/mcp

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