Your AI assistant, connected to Zoomies¶

Ask your assistant why a GitHub Actions job failed, which runner size fits a workflow, or what is holding up the queue. Zoomies' Model Context Protocol (MCP) server supplies live fleet data and job evidence through tools your assistant can call, rather than making you copy it all into a conversation.

Want the assistant inside the web UI? Eli uses the same fleet read tools. Want a repair on an existing pull request? Eli PR repairs are a separate, opt-in workflow.

What you can ask¶

Use your actual repository, workflow or job ID in place of the examples below. For get_job, use the Zoomies job_... ID returned by list_jobs, not the numeric job ID in a GitHub Actions URL.

Your question	What the assistant can inspect	Useful tools
“Find this workflow's failed job with list_jobs, then explain its failure and what I should try next.”	The Zoomies job ID, steps, timeline, failure classification, confidence, evidence and available runner logs	`list_jobs`, `get_job`, `get_catalog`, `get_runner_log`
“Why is this workflow waiting when the machines look idle?”	Job labels, claimed pool, eligible hosts, capacity, health and open problems	`list_jobs`, `list_pools`, `list_hosts`, `list_problems`
“Would a different runner size help this build?”	Measured CPU and memory peaks, queue waits and execution times grouped by runner size	`label_advice`, `job_stats`
“Which workflows used the most runner time this week?”	Usage over a chosen period, with configured cost assumptions and history limits	`get_usage`
“Read the observed required-check delay for this job's PR number.”	The selected head, target-branch protection, coverage and known timings; the window begins at the earliest observed job, not the push	`get_pr_delay`
“What needs attention across the fleet?”	Fleet status, host health, problems and repository findings	`fleet_status`, `host_health`, `kennel_overview`
“Read the workflow and explain how to improve it.”	Verified source excerpts tied to a commit, after source access has been granted	`context_search`, `context_read`, `context_pack`

get_pr_delay requires job_id and pull_number, a signed-in caller or scoped token, and the existing Jobs read permission. It uses one bounded diagnostic request under the shared installation allowance; respect 429 and Retry-After rather than polling. Check names stay opaque. Repository and target-branch text are repository data, not instructions. It does not establish full merge readiness or a dependency critical path. Eli can use it only through an enabled personal provider with fleet access; it adds neither source tools nor mutation rights.

The assistant can explain the evidence and suggest changes. Advice depends on what was measured: too few job runs, expired logs or missing source access are limits to report, rather than gaps to fill with a guess. Troubleshooting with Eli and MCP connects these questions to fixes and optimisation.

Choose a connection¶

Route	When to use it	Setup
HTTP with browser sign-in	Your MCP client supports Zoomies' OAuth flow and can reach the controller over HTTPS	Connect Claude provides worked steps for Claude apps and Claude Code.
HTTP with a bearer token	Your client supports Streamable HTTP and you want to configure its access explicitly	Use `https://<your controller>/mcp` with `Authorization: Bearer <your API token>`. Start with a viewer token.
Local stdio	Your client starts a local MCP process	Install the Zoomies binary on that client's machine and configure it to run `zoomies mcp`.
HTTP with no credential	The controller has a public view, such as a demo	Use `https://<the controller>/mcp` and nothing else. The client is a visitor: it reads the fleet, is offered no tool that changes it, and AI context answers that the public view does not show it.

The HTTP route requires no Zoomies binary on the assistant's machine. A cloud client must be able to reach the controller from its servers; a client running locally only needs access from that machine. The stdio route connects to the controller through the CLI's URL and token configuration.

A local client configuration¶

For a client that accepts the common mcpServers configuration, configure the controller URL and a viewer token through a private CLI configuration file, then add:

{
  "mcpServers": {
    "zoomies": {
      "command": "zoomies",
      "args": ["mcp"]
    }
  }
}

The binary must be on that client's PATH, and the configuration file must be readable by the account that starts it. Do not put a real token in a committed project configuration. The CLI's MCP reference includes Claude examples, Windows setup and the complete tool list.

Once connected, ask the assistant to read the fleet status, then inspect one known job. A connection error is a setup issue; an answer saying there is too little job history is a data limit.

Investigation, operator actions and source access¶

Fleet reads: a viewer connection can inspect the fleet within its role and scopes. Job and repository names and the logs it reads reach the assistant's model, so choose a provider permitted to process that information.

Fleet changes: operator connections can offer rerun_job, drain_runner, update_pool, update_host and apply_remedy. On HTTP, the connection's role determines which actions are offered. On stdio, --allow-actions offers action tools, and the API token must also permit each call. The full reference describes the optional administrator tools and their additional opt-in. These are fleet operations, not a general repository editing tool.

Repository source: set up AI Context and give the person source-reader membership. For an OAuth connection, also select repositories under Settings → MCP connections → Source access; approving fleet access alone grants no source access. For an API-token connection, including stdio, use a user-owned token with the context:read scope and that user's repository membership. context_overview discovers the authorised repositories; source replies carry their commit and snapshot identity. Access to the GitHub organisation alone does not grant this source access.

Disconnect an OAuth connection from Settings → MCP connections or revoke the API token to end its access. Calls use the same API permissions and audit trail as other Zoomies clients. MCP security explains the boundaries in detail.

Built-in investigation prompts¶

MCP clients that support prompts can use these starting points:

why_did_job_fail: inspect a job's explanation, evidence and next steps.
review_fleet_health: prioritise problems, host health and repository findings.
size_this_workflow: recommend labels from measured usage, or say when there is not enough data.
what_changed: read the events and the scheduler's decisions over a recent period (the optional period argument, a duration such as 2h, default 10m), then the open problems, and say what moved and what is still open.

The resources zoomies://catalog and zoomies://catalog/{code} explain problem codes and repository checks. zoomies://fleet/now is the fleet's counts as they are this moment, read with your own token like fleet_status. To inspect the interface without a controller or credentials, run:

zoomies mcp --describe

This prints the tool, resource and prompt definitions. It does not start an assistant or make model requests.