runners.io
Leia os jobs, logs, resultados de testes, cache e gastos da sua organização runners.io por meio de um agente de IA que você já usa e peça ajuda para explicar builds com falha. 14 ferramentas de leitura e 2 ferramentas de escrita; as ferramentas de escrita ficam desativadas por padrão. Entre com OAuth e autorize uma organização.
Servidor MCP hospedado
npx add-mcp 'https://mcp.runners.io/mcp'Instala no Claude Code, Codex, Cursor e outros
Documentação
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.
No REST API or API token
There is no REST API or API token for runners yet. Programmatic reads go through the MCP server; usage exports as CSV; job and billing events can be sent to a webhook. The CSV is Download CSV on Usage, and the webhook is set up as in Notifications.
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 runnersio, the name the command gives it, to sign in:
claude mcp add --transport http runnersio https://mcp.runners.io/mcp
If you use the runners.io plugin for Claude Code, you already have this server: the plugin includes it as runners-io-mcp, so do not add it again. Choose runners-io-mcp in /mcp to sign in, or runnersio if you added the server yourself before installing the plugin: Claude Code keeps one entry per address, so /mcp shows only that one.
Claude (the desktop and web apps). Add it from Claude's connector directory. Where your plan allows custom connectors, you can instead 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.
The server is also listed in the official MCP Registry as io.runners/mcp-server, for any client or tool that looks servers up there. The entry gives the same address as above.
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 sixteen 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, the access the connection was granted, whether the write tools would run now (and if not, whether the grant, the role, the organisation's setting or GitHub is why), whether GitHub is connected, whether a card is on file, and whether the runners.io GitHub App is installed and how many repositories it can see. |
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. With several GitHub accounts connected it adds them together, as the Usage page does, and github_accounts names them. 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. With several GitHub accounts connected it lists each account's in turn, the totals cover all of them, and githubAccount names the account each entry belongs to. |
get_cache_stats | How well the cache is working: hits, misses and bytes served, per repository, with a month-by-month trend. With several GitHub accounts connected it adds them together; to narrow the trend to one repository, name it as owner/name. |
list_repositories | Lists the repositories shared with runners.io, with how many jobs each has run and when the last one was. With several GitHub accounts connected it lists every account's repositories, under their full owner/name. |
list_runner_tiers | Lists the runner sizes with their vCPUs, memory, disk and price per minute. |
wait_for_ci | Waits up to 45 seconds for CI on a commit to finish, then says how it ended: success, failure (naming the failed jobs) or cancelled. It answers at once when a run waits for an approval, and says it is still running when the 45 seconds pass first, so the agent calls it again. It says success only once the commit's first run is five minutes old, so a workflow that starts late is not missed. |
get_ci_events | Lists what CI just did on the organisation's repositories: a workflow failed, passed or was cancelled, a run waits for an approval, or every workflow for a commit finished. Events are kept seven days, and a cursor returns only what happened since the last call. |
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. Name the repository and it also says whether the GitHub App can see it and whether a card is on file, with the fix for each that is missing: a moved job waits on GitHub until both are in place. |
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.
For how this server compares with the others that read GitHub Actions, see Is there an MCP server for GitHub Actions?, and for what to restrict when an agent reads logs, see Is it safe to let an AI agent read my CI logs?.
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. With several GitHub accounts connected, name the repository as owner/name with the entry's githubAccount as the owner; a bare name is refused, because it could be either account's. 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.
Write access is asked for by the agent, not switched on afterwards: it signs in asking for the mcp:write scope as well as mcp:read. A connection approved for reading only that calls a write tool is answered 403 with scope="mcp:read mcp:write", which tells the agent to sign in again and ask for both. The consent page then shows a box, Also let it cancel jobs and delete cache entries, to an owner or admin of the organisation. Left unticked, the connection reads only.
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.
- A tool fails, saying its result does not match the tool's output schema. Your client is holding a list of tools from before an update to the server. It reads the list again only when it reconnects. In Claude Code, run
/mcp, choose the server and reconnect it, or start a new session. In any other client, disconnect the server and connect it again. Nothing is lost, and you do not have to approve the connection again.