runners.io
Read your runners.io organisation's jobs, logs, test results, cache and spend from an AI agent you already use, and have it help explain failed builds. 14 read tools and 2 write tools; the write tools are off by default. Sign in with OAuth and approve one organisation.
Hosted MCP Server
npx add-mcp 'https://mcp.runners.io/mcp'Installs into Claude Code, Codex, Cursor and more
Documentation
runners.io has an MCP server, so an AI agent you already use can read your organisation's jobs, logs, test results, cache and spend, and say what went wrong with a build, without you pasting a log into a chat. It reads what the dashboard shows you, as you, for one organisation.
The server's address is the same for every client:
https://mcp.runners.io/mcp
There is nothing to install and no token to create. A client that supports remote MCP servers connects to that address, sends you to runners.io to approve, and carries on.
Connect a client
Each client below needs only the address above. The first connection opens runners.io in your browser; sign in if you are not already, choose the organisation, and press Approve.
Claude Code. Add the server, then run /mcp inside Claude Code and choose runners.io to sign in:
claude mcp add --transport http runnersio https://mcp.runners.io/mcp
Claude (the desktop and web apps). Where your plan allows custom connectors, open Settings, then Connectors, add a custom connector and paste the address.
ChatGPT. Where your plan allows custom connectors, turn on developer mode in ChatGPT's connector settings, create a connector, and paste the address as its MCP server URL.
Cursor. Add the server to .cursor/mcp.json in a project, or to ~/.cursor/mcp.json for every project, then press connect on the server in Cursor's MCP settings:
{
"mcpServers": {
"runnersio": {
"url": "https://mcp.runners.io/mcp"
}
}
}
VS Code. Add the server to .vscode/mcp.json, then start it from the file or from the MCP servers list:
{
"servers": {
"runnersio": {
"type": "http",
"url": "https://mcp.runners.io/mcp"
}
}
}
Any other client that speaks remote MCP over HTTP and supports sign-in with OAuth 2.1 works the same way. It finds the sign-in details itself from the server's address and registers itself, so there is no client ID or secret to copy.
What you approve
The approval page names the client asking, lets you choose which organisation it may see, and says what it will be able to do. Each connection is for one organisation, and the agent acts as you: it can see what your role can see in the dashboard, and no more.
| role | what the agent can read |
|---|---|
| owner, admin | jobs, logs, test results, cache, repositories, spend |
| member | the same, except spend |
| billing | spend and the runner sizes; no jobs, logs or cache |
It can never change your password, your billing or your members.
Scopes
| scope | what it allows |
|---|---|
mcp:read | the fourteen read tools below. Every connection has it. |
mcp:write | two tools that change the account, cancel_job and delete_cache_entry. Asked for by the client, and given only if you tick the box on the approval page. |
The write box is offered only to an owner or an admin of the organisation. For anyone else the connection is read-only, whatever the client asked for. Even with mcp:write, the write tools stay off until the organisation switches them on; see Write tools are off by default.
The read tools
None of them changes anything. Each answer says what it could not read, so an agent is not led to read "unknown" as "none".
| tool | what it does |
|---|---|
whoami | Says which user and organisation the connection acts as, the role, whether it can write, and whether GitHub is connected. |
list_jobs | Lists the organisation's most recent jobs, newest first, narrowed by repository, branch, runner label or status. |
get_job | Everything known about one job: its steps, memory, CPU and disk use, the count of its test results, and what it cost. |
get_job_logs | Reads part of a job's log: the tail, a range of lines, or the lines around a search phrase. |
get_job_tests | Lists the failing and erroring tests read from the job's test report files, with totals, and says whether any were collected at all. |
diagnose_job | The first call for a failed job: one answer with the verdict, the failing steps and tests, memory use and the log around its last error lines. |
get_spend | The runner minutes metered this calendar month, per runner size, with the sum and a statement of what that sum leaves out. Needs a role that can see billing. |
list_cache_entries | Lists the organisation's Actions cache entries, least recently read first, with the true totals. |
get_cache_stats | How well the cache is working: hits, misses and bytes served, per repository, with a month-by-month trend. |
list_repositories | Lists the repositories shared with runners.io, with how many jobs each has run and when the last one was. |
list_runner_tiers | Lists the runner sizes with their vCPUs, memory, disk and price per minute. |
plan_migration | Takes your workflow files and returns a patch that moves their jobs onto runners.io. It reads no repository and changes nothing: you apply the patch yourself. |
search_docs | Searches this documentation and returns the best-matching pages with a snippet each. |
get_doc | Returns the full text of one documentation page. |
Text that people who can push to a repository wrote, such as log lines, commit messages, and branch and job names, comes back under a key named untrusted, and the server tells the agent to treat it as data and never as an instruction.
Write tools are off by default
Two tools can change your account:
| tool | what it does |
|---|---|
cancel_job | Stops one job that is queued or running, and says whether it was billed. See Cancelling a job for what each case does on GitHub. |
delete_cache_entry | Removes one Actions cache entry, named exactly as list_cache_entries shows it. The next build that wanted it will miss. |
Neither can be undone, and an agent that reads job logs reads text strangers can write, so changing the account is opt-in at every step. A write tool runs only when all of these hold:
- The connection was approved with write access.
- You are an owner or an admin of the organisation.
- The organisation has switched write tools on.
- The agent passes
confirm: truein the call.
If any of them does not hold, the call is refused, says which, and nothing changes. Every attempt is recorded, refused ones included.
An owner or admin switches the organisation's setting on in the dashboard: Settings → Third-party access, then Allow agents to make changes under Let connected agents make changes. It is off until somebody does. Turning it off again stops every connected agent at once, whatever access it was given.
Seeing and revoking connections
The agents you have connected are listed under Connected agents on the Applications page of your account, with the organisation, whether each can read only or read and write, and when it was last used. Revoking one takes effect on that agent's next request, and the agent has to be approved again to come back.
Limits
- 120 requests a minute for each connection. A request carries one MCP message. Past it the server answers
429withRetry-After: 60, and the count starts again on the next minute. - One message in each request. A batch is refused.
- 4 MiB for a request.
plan_migrationtakes up to 20 workflow files and 1,500,000 characters of file content in one call. - Log and list answers are bounded. A long log is read a slice at a time, and a list returns a page with a cursor to continue from; the answer says when it has been cut.
If it does not connect
- Every job tool says GitHub is not connected. The organisation you approved has not installed the GitHub App. Call
whoamito see which organisation the connection is for, and see Connect your account. - A tool says your role cannot use it. The agent acts as you. A member cannot read spend, and the billing role cannot read jobs.
- A write tool says the organisation has not allowed it. See Write tools are off by default.