Most CI debugging starts with a fragment: a screenshot, the last twenty lines of a failed step, or a message that says only that the build is red. An agent given the same fragment can produce a faster guess, but it still has to guess.
Runnable's MCP server exposes the run as structured operational context: repository and workflow identity, jobs, attempts, step conclusions, bounded masked logs, and a cursor that waits for state changes. The agent can follow the system instead of scraping its interface.
Discovery before diagnosis
The read scope begins with list_runs and list_workflows. An agent can filter recent runs by repository or status, select an exact run ID, and then retrieve its workflow, source revision, trigger, jobs, attempts, dependencies, and step results.
That order matters. It prevents a similarly named workflow, an old rerun, or a failed matrix sibling from becoming the evidence for the wrong incident.
Logs are bounded evidence
get_job_logs returns a masked tail for one job attempt with explicit line and byte limits. The response says whether earlier content was truncated, and expired chunks remain expired rather than reappearing through a larger request.
An agent can start with the smallest useful tail, inspect the failure, and increase the bounds only when the evidence requires it. Reading logs is audit logged, preserving the fact that operational data was accessed.
Waiting is a tool, not a polling loop
wait_for_run performs a bounded long poll and returns a cursor derived from current run and job state. Repeating the call with that cursor returns early when something changes and marks a normal wait expiry separately from a workflow timeout.
The agent can monitor a deployment without burning runner compute, holding an in-memory subscription, or repeatedly downloading an unchanged run object.
Observation and authority are separate
Read tokens expose five tools. Operator scope adds rerun, cancel, and workflow dispatch. A separate secrets scope adds name-and-scope listing plus create-or-replace, while secret values are never returned.
The split lets a diagnostic agent investigate broadly without automatically gaining permission to mutate production. When an operator action is appropriate, the tool contract states whether it is idempotent, destructive, or creates a new run.
- ObserveList workflows and runs, inspect one run, read bounded masked logs, and wait for change.
- OperateRerun the same snapshot, cancel unfinished work, or dispatch a declared manual workflow.
- Handle secretsList metadata or replace a value through a separately scoped, audited path—never read it back.
Context still needs judgment
Whole-run context does not make every repair automatic. A failed test can reveal a product defect, a flaky dependency, an expired external credential, or an intentional compatibility refusal. The tools expose evidence and bounded actions; they do not erase those distinctions.
The productive pattern is diagnosis first, a proposed change second, and mutation only with the authority the task actually requires.