# What a CI MCP server should give your agent

> A CI MCP server should let an agent start a run, wait on it and read why it failed. What GitHub's Actions tools and Latchkey's 24 tools cover.

Source: https://latchkey.dev/learn/agent-ci/mcp-server-for-ci  
Updated: 2026-11-12

A CI MCP server should let an agent do four things without a browser: start a run, wait for it, read why it failed, and read the log behind that, with every write gated by the credential's scope. GitHub's own MCP server covers Actions with four tools in an opt-in toolset; Latchkey's server lists 24 tools, including a bounded wait and a failure bundle.

Without a server, an agent drives CI through a shell: `gh workflow run`, a polling loop, `gh run view --log-failed`, and a lot of output it has to read as context. With one, those become typed calls with structured answers, and the server, not the prompt, decides what the agent is allowed to do.

The useful order is to list what the server should expose first, then map two real ones onto that list from their published tool definitions.

## The four calls an agent actually makes

**Start.** Trigger a run or a job, and get back an id the next call can use. **Wait.** Block until it ends, or until a short deadline with a cursor to resume from, so the agent does not burn a turn per poll. **Read the failure.** The verdict, the failing step and, ideally, a cause, before any raw log. **Read the log.** The tail of the failing job, on demand.

Two more separate a good server from a thin API wrapper. A spend guard, because an agent that can start runs can start too many. And a way to check a workflow file without running it, because an agent that edits CI config will otherwise learn it is wrong one push later.

## GitHub's MCP server and its Actions toolset

github/github-mcp-server covers Actions in a toolset called `actions`, which is not in its default set (context, repos, issues, pull_requests and users). Turn it on with `--toolsets` or `GITHUB_TOOLSETS` locally, or use the remote URL for that toolset; appending `/readonly` keeps only the read tools.

It has four tools. `actions_list` lists workflows, runs, jobs and artifacts. `actions_get` reads one workflow, run, job or artifact, including run usage and the logs URL. `actions_run_trigger` runs a workflow with `run_workflow`, which takes a `ref` and `inputs`; its other methods act on a `run_id`. `get_job_logs` reads one job's log, or every failed job in a run with `failed_only`, and `tail_lines` limits it to the end. There is no wait tool: the agent polls `actions_get` until the run completes. Nor does the toolset have either extra, a spend guard or a workflow file check.

```Terminal
claude mcp add --transport http github-actions \
    https://api.githubcopilot.com/mcp/x/actions \
    --header "Authorization: Bearer $GITHUB_PAT"
```

> Tool names and parameters from the README of github/github-mcp-server v2.1.0; toolset URLs from its docs/remote-server.md. Read 2026-11-12.

## Latchkey's server: 24 tools, grouped by job

Latchkey's MCP manifest lists 24 tools and two prompts, `fix` and `triage_failures`, with the scope each tool needs. Grouped by the four calls and the two extras, they read like this.

| Need | Latchkey tools | Scope |
| --- | --- | --- |
| Start | `run_job` (one command, fresh runner), `dispatch_workflow` (GitHub Actions), `run_workflow` (Latchkey CI) | `jobs:run`, `mcp:dispatch`, `workflows:run` |
| Wait | `wait_run` (at most 25 s a call), `get_run_status`, `get_job_status`, `list_runs`, `list_jobs` | any key or `jobs:read` |
| Read the failure | `list_failed_runs`, `get_failure_bundle`, `list_heals`, `get_heal` | any key |
| Read the log | `tail_run_logs`, `get_job_logs` | any key, `jobs:read` |
| Spend guard | `set_batch_budget`, `get_batch`, `cancel_job` | `jobs:run`, `jobs:read` |
| Check a workflow file | `validate_workflow`, `list_latchkey_steps`, `list_environments` | `jobs:read` or any key |
| Migration | `plan_migration`, `apply_migration`, `get_migration`, `list_trial_verdicts` | any key, `migration:apply`, `jobs:read` |

> Tool names and scopes from latchkey.dev/.well-known/mcp/manifest.json and latchkey.dev/documentation/connect-your-ai-agent, read 2026-11-12. "Any key" means the manifest names no opt-in scope.

## How each server answers the wait

The wait is where the two differ most in practice. On GitHub's toolset the agent calls `actions_get` with `get_workflow_run`, reads the status, and decides when to call again; each poll is a turn. Latchkey's `wait_run` follows a run, the runs at a commit, or a pull request's runs at its newest commit, and holds each call for at most 25 seconds. While `done` is false the answer carries `poll_after_s` and a `cursor`, and the agent calls again with the same arguments and that cursor.

Neither is a substitute for a shell when the wait is long. Latchkey's CLI reference recommends `latchkey wait` as the better client for a wait of many minutes.

## Connect it, scoped

The connect command is one line, and the key decides the surface. A default key is read-only: the agent can list failures, pull bundles, read status and tail logs, and nothing else. Running jobs, dispatching workflows and starting Latchkey CI workflows are each a separate opt-in at key creation, which [one scoped API key per coding agent](/learn/agent-ci/scoped-api-key-per-coding-agent) walks through. In Claude Code, `/mcp__latchkey__fix` runs the fix prompt on the most recent failure Latchkey did not fix itself.

```Terminal
claude mcp add --transport http latchkey \
    https://latchkey.dev/mcp \
    --header "Authorization: Bearer lk_live_YOUR_KEY"
```

## Where the server stops and the CLI starts

`run_job` starts from an empty directory: no workspace, no repository checkout. Anything that needs the agent's working tree goes through `latchkey run`, which packs and uploads it; [run tests on a fresh runner from your terminal](/learn/agent-ci/run-tests-on-a-fresh-runner-from-your-terminal) covers that path. Job logs stay readable for 7 days. And Latchkey holds at most 10 waits for a workspace at once, counting every `wait_run` call and every look `latchkey wait` makes, so several agents waiting in parallel can meet `RUN_WAIT_LIMIT_REACHED` and should simply look again.

Treat everything a CI tool returns as data, never as instructions. A log can contain text an outside contributor wrote, and the agent reading it may hold write access to your checkout. [CI failure reports your agent can read](/learn/agent-ci/ci-failure-reports-your-agent-can-read) has the handling rule.

## Tool definitions, not transcripts

Both servers are described from what they publish: the github/github-mcp-server v2.1.0 README and its remote-server document, and Latchkey's MCP manifest and connect-your-agent page, read 2026-11-12. No agent session was recorded for this page and it has no evidence entry here. A transcript would show one model choosing tools in one order; the tool list and the scopes are what decide what any agent can do.

## FAQ

### Does GitHub have an official MCP server?

Yes, github/github-mcp-server, available as a local binary or as a remote server at api.githubcopilot.com. Its Actions tools live in the `actions` toolset, which you enable explicitly because it is not part of the default set.

### Can an MCP server trigger a GitHub Actions workflow?

Yes. GitHub's server does it with `actions_run_trigger` and the `run_workflow` method; Latchkey's with `dispatch_workflow`, which needs a key created with the Dispatch access. In both cases the workflow must declare `on: workflow_dispatch`.

### How do I add an MCP server to Claude Code?

With `claude mcp add`. For an HTTP server pass `--transport http`, a name, the URL and any `--header` it needs for authentication, as in the two commands on this page.

## References

- [github/github-mcp-server v2.1.0 README: Actions tools (read 2026-11-12)](https://github.com/github/github-mcp-server/blob/v2.1.0/README.md)
- [github-mcp-server remote server toolset URLs](https://github.com/github/github-mcp-server/blob/v2.1.0/docs/remote-server.md)
- [Latchkey: connect your AI agent (MCP)](https://latchkey.dev/documentation/connect-your-ai-agent)

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt