Idlerate

Tools reference

Idlerate exposes five MCP tools on https://relay.idlerate.dev/mcp. Every call needs a bearer key with the matching scope (see Keys).

Typical flow: list_models → run_model → get_status (with wait_ms) → get_result. Use cancel to stop a queued or running job.

list_models

List Ollama models on each paired machine.

Scope: models:list
Arguments: none

Returns:

Field Meaning
models Flat list of models (each includes which device it came from when you have more than one machine)
machines One entry per paired machine: device_id, name, platform, status, paused, connected, stale, models, optional GPU fields, pause_reason
stale true when none of your machines are connected
device_connected true when at least one machine is connected

run_model

Queue a model run. Returns immediately with a job id; it does not wait for the GPU.

Scope: models:run

Argument Required Notes
model yes Ollama model name, for example qwen2.5:7b
prompt yes User prompt (max about 1,000,000 bytes)
system no Optional system prompt
options no Optional Ollama sampler options object
machine no Device id or exact machine name. Omit to pick a free machine of yours that has the model. A shared machine is used only if you pass its id here or turn on Auto overflow to shared machines (off by default). Sharing is rolling out to accounts over the first weeks

Returns (structured): job_id, status (usually queued), device_id, machine, device_paused, pause_reason.

If device_paused is true, the job stays queued until that machine is free again.

Your account needs an active trial or plan to run jobs. Otherwise the tool returns subscription_required.

get_status

Read a job. Optionally wait until it finishes.

Scope: jobs:read

Argument Required Notes
job_id yes From run_model
wait_ms no How long to wait for a terminal status. 0 (default) returns immediately. Max 25000. Call again to keep waiting

Terminal statuses: succeeded, failed, cancelled.

Returns (among other fields): job_id, status, device_id, machine, device_paused, pause_reason, queue_position, error, partial (tail of the latest output, at most 8192 characters), output_bytes, timestamps.

partial is a preview only. Use get_result for the full answer after success.

get_result

Return one page of model output for a finished job (succeeded). Errors if the job is not done yet.

Scope: jobs:read

Argument Required Notes
job_id yes
offset no Byte offset into the result. Default 0
length no Max bytes to return. Default 100000, max 100000

Returns: job_id, status, output, truncated (true while more pages remain), total_bytes / result_bytes, next_offset, done.

When done is false, call again with offset set to next_offset until done is true.

cancel

Cancel a queued or running job. If Ollama already started, the PC stops that request.

Scope: jobs:cancel

Argument Required
job_id yes

Returns: job_id and status (typically cancelled).

Tips

  • Prefer get_status with wait_ms: 25000 over tight polling.
  • Pass machine when you care which PC runs the job; omit it when any free machine of yours with that model is fine.
  • To run one job on a shared machine, pass that machine’s id as machine. Sharing is rolling out to accounts over the first weeks. This runs on another member’s PC. Don’t send anything private.
  • Large answers come back in pages — always follow next_offset until done.