mcp-server

Jungle Grid MCP Server enables agents that support the MCP protocol to estimate, submit, monitor, and cancel Jungle Grid workloads, and to retrieve artifacts. It supports local stdio clients and hosted Streamable HTTP deployments, and tool calls are forwarded to the Jungle Grid API. Applicable scenarios include asynchronous AI workload execution, batch processing, training, fine-tuning, tasks based on uploaded files or scripts, lifecycle diagnostics, workload logs, and hosted output artifacts.

Main Capabilities

The current tool registry exposes the following tool names:

• Estimate a workload, returning classification, routing status, capacity source, estimated cost range, availability, and filtering details. An estimate is not a reservation and does not guarantee immediate startup.
• Submit an asynchronous job. workload_type accepts inference, training, fine_tuning, and batch; routing mode accepts cost, speed, and balanced. model_size is an optional size (GB) used to select suitable GPU capacity. command preferably uses a string array. env must be an object with string values. input_files and script_files accept arrays of { "input_id": "..." }; the current REST implementation supports only one uploaded script reference.
• Create a signed upload slot. The tool itself does not upload file bytes; you need to use the returned upload.method to upload bytes to upload.upload_url, then complete the upload via upload.complete_url and upload.token. kind is any string, conventionally input for ordinary input files and script for scripts. Scripts are mounted at /workspace/scripts/<filename>, and inputs are mounted at /workspace/inputs/<filename>.
• List uploaded inputs, including input_id, filename, content_type, size_bytes, kind, status, ready, mount_path, and timestamps.
• List jobs, returning jobs, limit, next_cursor, and has_more. limit is subject to API limits. status is a free-form filter string; do not assume the MCP schema is limited to a fixed enum.
• Get the current status and details of a job. Status, execution phase, lifecycle events, runtime details, and workload logs are separate interfaces.
• Get lifecycle events before and during execution. Events may exist before workload logs begin and can be used to diagnose queuing, routing selection, scheduling, provider configuration, input preparation, startup, retries, failures, and cancellation.
• Get stored log entries, returning items, next_cursor, has_more, failure_highlight, usage_hint, etc. Logs may be empty while a job is queuing, scheduling, configuring, or preparing; if logs are empty but the job has not terminated, get job events should be called. This tool retrieves persisted logs and does not provide true streaming.
• Request cancellation of a pending, queued, assigned, starting, or running job. Completed, failed, rejected, or already canceled jobs will return a conflict. Cancellation may trigger managed teardown, but immediate infrastructure shutdown is not guaranteed.
• List the managed artifacts of a job, including artifact_id, job_id, filename, content_type, size_bytes, status, ready, and timestamps. Failed jobs may have no artifacts or only partial artifacts.
• Create temporary download information for a single artifact, returning artifact metadata, a signed URL, and expires_at. Signed URLs should be treated as confidential.

Usage

For local stdio, run with npx, or install globally to obtain a stable executable. Local stdio uses environment variables for configuration. Managed HTTP gateway deployments also support corresponding configuration.

Connection mode: the local client starts the package and communicates via stdio. You can add the mcpServers block to claude_desktop_config.json, then fully quit and reopen Claude Desktop. Project configuration should avoid committing secrets; place keys in the environment used to start Cursor. Local uncommitted Cursor configuration also works.

The HTTP server exposes GET /.well-known/oauth-protected-resource. After starting HTTP locally, managed MCP clients must send Authorization: Bearer to POST /mcp. <oauth_access_token>. The server introspects the token at /oauth/introspect on the configured API base address and requires tool-specific scopes.

Minimal working example: first have the MCP client call the tools in order. If the estimate is acceptable, submit the job. Use the returned job_id to call get_job, get_job_events, get_job_logs, list_artifacts, and get_artifact.

File-based task workflow: create an upload slot; upload each file to the returned signed upload_url, then complete the upload; submit using the input ID; monitor via get_job_events, get_job, and get_job_logs; retrieve /workspace/artifacts/transcript.txt with list_artifacts and get_artifact.

Production workflow: repeatedly call get_job, get_job_events, and get_job_logs with the same job_id until the status is terminal. Then call list_artifacts, and fetch artifacts as needed.

REST MCP routes return envelopes. The MCP server converts API errors into tool errors. Common API codes include UNAUTHORIZED, FORBIDDEN, INVALID_REQUEST, JOB_INPUT_NOT_FOUND, JOB_INPUT_NOT_READY, ARTIFACT_NOT_READY, NOT_FOUND, CONFLICT, INSUFFICIENT_FUNDS, MAINTENANCE_ACTIVE, and INTERNAL_ERROR.

Applicable Scenarios

Suitable for asynchronous AI workload execution, batch processing, training, fine-tuning, tasks based on uploaded files or scripts, lifecycle diagnostics, workload log viewing, managed output artifact management, and scenarios requiring agents to automatically submit and monitor GPU inference, training, fine-tuning, and batch processing tasks.

Limitations and Security Notes

Requires Node.js 18 or later. Local stdio requires a Jungle Grid API key, and hosted HTTP requires an OAuth bearer token. You need to configure the API scopes that match the tools you want to call. Never submit API keys, OAuth tokens, signed upload URLs, signed artifact URLs, or callback secrets. Keep API keys and OAuth tokens away from prompts, source control, browser bundles, logs, and issue trackers. Prefer using the host's secret storage or a local-only MCP configuration file to store JUNGLE_GRID_API_KEY. Treat signed upload and artifact URLs as temporary bearer secrets. Do not print environment variables containing tokens from workload code. Review before allowing agents to execute submit_job and cancel_job requests, as they may consume credits or stop active work.