# Connect your AI agent (MCP)

> Give Claude Code, Cursor, or any MCP-compatible agent secure access to your CI failures, plus opt-in workflow re-runs and one-off jobs on fresh runners, so it can triage, fix, and verify from your editor.

Source: https://latchkey.dev/documentation/connect-your-ai-agent

## Summary

- **Settings, API Keys** creates `lk_live_` keys for Latchkey's MCP server at `https://latchkey.dev/mcp`.
- Connected agents (Claude Code, Cursor, any MCP client) can triage failures, pull failure bundles, check run status, tail logs, drive fixes from your editor, and run one-off jobs on fresh runners.
- The AI Insight page can hand a finding straight to your agent with **Copy prompt** or a **Set up MCP** shortcut.
- Keys are read-only by default, workspace-scoped, shown once at creation, and revocable at any time. Re-running workflows, reading CLI job status and logs, and running jobs are each a separate, explicit opt-in at key creation.

Latchkey ships an **MCP server**: your AI coding agent connects to it with a Latchkey API key and can pull real CI failure context (failed runs, logs, diagnosis bundles) straight into your editor session. Instead of copy-pasting logs into a chat, your agent asks Latchkey directly and gets everything it needs to fix the failure.

This is the hand-off half of [self-healing](/documentation/self-healing): self-healing fixes environment failures during the run and never touches your source, so when the real problem is a bug in your code, the build fails truthfully, and that failure arrives here as a ready-to-fix bundle for your agent.

There are two ways in: create a key yourself in **Settings, API Keys** (the setup below), or let the [AI Insight](/documentation/optimization-insights) page do it for you. Findings better fixed by your own coding agent offer **Copy prompt**, a ready-made prompt to paste into your agent, and a **Set up MCP** shortcut that creates a key named `coding-agent` and shows the exact connect command. The minted key expires in 90 days and can run one-off jobs on billable runners (the card says so next to the button), so treat it like the spend-capable credential it is.

## What a connected agent can do

The server exposes ten capabilities: eight **tools** your agent calls for data and actions, and two **prompt flows** that orchestrate a whole task:

- **List failed runs** Enumerate recent failed workflow runs with their key metadata. Failed CLI jobs appear too.
- **Get failure bundle** Pull the full context for one failure: logs, diagnosis, and workflow details.
- **Check run status** Poll any run for its status, conclusion, and per-job timing.
- **Tail run logs** Read the secret-scrubbed log tail of any completed job, green runs included.
- **Re-run a workflow** Trigger a workflow_dispatch run to verify a fix. Requires a dispatch-enabled key.
- **Run a one-off job** Run a shell command on a fresh Latchkey runner. Requires a jobs-enabled key and bills runner minutes.
- **Check job status** A CLI job's state and, once it finishes, the command's exit code.
- **Read job logs** A CLI job's output, so the agent reads the result of the command it ran.
- **Fix a CI failure** Drive a guided fix of a specific failure from inside your editor.
- **Triage CI failures** Survey what is failing across your monitored repositories and prioritize.

You never call these by name. You ask your agent a plain-language question, and it decides which capability answers it. Some illustrative pairings:

| You ask your agent | Capability it reaches for |
| --- | --- |
| "What is failing across our repos right now?" | **Triage CI failures** |
| "Show me the recent failed runs for this repo" | **List failed runs** |
| "Pull everything you have on that failed run" | **Get failure bundle** |
| "Fix the failing build" | **Fix a CI failure** |
| "Did that run pass? How long did each job take?" | **Check run status** |
| "Show me the end of the deploy job's log" | **Tail run logs** |
| "I pushed the fix, re-run CI and watch it" | **Re-run a workflow** |
| "Run the test suite on a clean Linux runner" | **Run a one-off job** |
| "Is that job done? What did it print?" | **Check job status** and **Read job logs** |

### What a session looks like

Two illustrative sessions. The exact wording, and the agent's exact replies, will vary by agent; the shape of the exchange is the point.

## What is in a failure bundle

The failure bundle hands your agent what it would otherwise reconstruct by hand:

- The **root cause**, in plain language.
- The failing step's **exit code** and the exact source file where the error surfaced.
- The **full captured logs** of the failing step, including output GitHub hides in its log viewer; very large logs keep their final portion and say so. Secrets are stripped before the logs leave Latchkey.
- What **self-healing already investigated** and why it stood down, plus the workflow definition.

## Setup

1. **Create an API key** Open **Settings, API Keys** (owners and admins manage keys). Click **Generate key**, name it after where it will live (for example "Cursor on my laptop"), and pick an expiry: **Never** (the default), 30 days, 60 days, 90 days, or 1 year. Tick the capabilities the key needs (workflow dispatch, reading CLI job status and logs, running CLI jobs); capabilities are fixed at creation.
2. **Copy the key immediately** The full key (it starts with `lk_live_`) is shown **once**, at creation. After that the UI only shows a placeholder. Treat it like a password; if you lose it, revoke it and create a new one.
3. **Connect your agent** The **Connect your agent** block on the same settings tab shows the exact command for your workspace. For Claude Code it looks like:
4. **Use it** Ask your agent about failing CI ("what is failing in our repos?", "pull the failure bundle for the latest red build and fix it"). Any MCP-compatible client that supports HTTP transport with a bearer header works the same way.

> **Claude Code shortcut**
> In Claude Code, the built-in `/mcp__latchkey__fix` command runs the "Fix a CI failure" prompt flow in one step: it grabs the most recent unfixed failure and gets to work.

## Re-run workflows after a fix (opt-in)

By default a key is read-only. If you want the loop to close (agent fixes the code, pushes, re-runs CI, and watches it go green), create a key with **Allow workflow dispatch** checked. That key additionally carries the `mcp:dispatch` scope, and your agent can then trigger `workflow_dispatch` runs in your monitored repositories, poll them with the run-status tool, and read their logs when they finish. Green runs are readable too, so the agent can confirm the fix, not just observe the failure.

- Dispatch works only on repositories your workspace monitors, and only for workflows that declare the `workflow_dispatch` trigger.
- Existing keys never gain dispatch retroactively; mint a new key with the checkbox enabled.
- The re-run runs whatever is on the branch you dispatch against; push the fix first, then dispatch.

> **A dispatch key can trigger any dispatchable workflow**
> That includes deploy workflows, if they are manually dispatchable in a monitored repository. Enable dispatch only on keys whose agent you trust with that surface, name the key after where it lives, and revoke it the moment it is in doubt.

## Run jobs on fresh runners (opt-in)

The second opt-in write is running one-off jobs. A key created with **Allow running CLI jobs (includes reading)** carries the `jobs:run` scope (`jobs:read`, for status and logs, comes with it), and your agent can then use the **Run a one-off job** tool: one shell command on a fresh, isolated Latchkey runner, billed as ordinary runner minutes from the same free-minute pool as your workflows. The runner starts clean, with no repository contents; jobs that need your working tree go through the [Latchkey CLI](/documentation/latchkey-cli), which packs and uploads it. **Allow reading CLI job status and logs** is the narrower grant (`jobs:read` alone) for a key that should follow jobs but never start them.

- Jobs default to a 30 minute timeout, configurable up to 2 hours, and the agent picks a runner size (`small` when it does not).
- A jobs-enabled key spends money: every job bills at the runner's standard per-minute rate. Name the key for the agent that holds it and give it an expiry.
- Cancelling a job is a CLI action (`latchkey cancel`), not an MCP tool.

## Security model

- **Read-only by default.** Keys can read CI failure and run data; changing anything in Latchkey or GitHub is off by default. The writes a key can opt into at creation are workflow dispatch (`mcp:dispatch`) and running jobs on Latchkey runners (`jobs:run`), and neither extends to Latchkey settings or arbitrary GitHub actions.
- **Workspace-scoped.** The workspace is derived from the key itself, so a key can only ever see its own workspace's data.
- **Revocable.** Revoke any key from Settings, API Keys: a write-capable key (dispatch or jobs) loses access immediately, a read-only key within about a minute. Revoked keys stay listed under a "Revoked (n)" section for audit.

What those three properties mean in practice. Read-only-by-default bounds the blast radius of a leak: a stolen default key exposes CI failure data (including log excerpts), which is why you should still protect it, but it cannot open PRs, alter settings, or act on GitHub on your behalf. A stolen dispatch-enabled key can additionally trigger dispatchable workflows in your monitored repositories, and a stolen jobs-enabled key can run commands on billable runners in your workspace, which is exactly why each write is a per-key opt-in with a warning at creation, not a default. Workspace scoping means there is nothing to configure and nothing to get wrong: the key itself determines what it can see, and it can never see another workspace. And because revocation is fast and revoked keys stay listed for audit, the safe response to any doubt is simply to revoke and reissue.

Two low-effort habits that keep this clean: create a separate key for each tool or machine (the naming prompt at creation, like "Cursor on my laptop", exists exactly for this), so revoking one key never breaks the others; and pick the shortest expiry that fits how you work, reserving **never** for setups you actively track. Key management lives with owners and admins; see [Team and roles](/documentation/team-and-roles) and [Security and permissions](/documentation/security-and-permissions) for the wider model.

> **Handle keys like passwords**
> Anyone holding the key can read your CI failure data (including log excerpts). Store it in your agent configuration, not in a repository, and rotate it if it may have leaked.

Latchkey also publishes machine-readable descriptors so an agent can discover the surface without being told. The REST Jobs API is served from `https://api.latchkey.dev` and is fully described by an OpenAPI 3.1 specification; the MCP server has its own manifest listing every tool and the scope it needs.

| File | What it is |
| --- | --- |
| [/openapi.json](https://latchkey.dev/openapi.json) | OpenAPI 3.1 contract for the Jobs API: operations, typed schemas, scopes and error shapes. |
| [/.well-known/mcp/manifest.json](https://latchkey.dev/.well-known/mcp/manifest.json) | MCP server descriptor: transport, auth, and all eight tools with their scopes. |
| [/agent.txt](https://latchkey.dev/agent.txt) | Short plain-text brief on when to reach for Latchkey and how to call it. |
| [/llms.txt](https://latchkey.dev/llms.txt) | Index of the site and its content, with a when-to-use section. |

Every content page on the site also has a markdown twin at the same URL plus `.md`, linked from the page head as a `rel="alternate"` link. It carries the same content without the page markup, which is far cheaper for an agent to read.

> **If your agent starts getting 401s**
> A 401 means the key no longer authenticates: it was revoked, or it reached the expiry you set at creation. The fix is the same either way: create a new key in Settings, API Keys and update the Authorization header in your agent configuration. Remember the full key is only shown once, at creation. For other connection problems, start with [Troubleshooting](/documentation/troubleshooting).

### What can a connected AI agent actually do?

Triage failures, pull failure bundles, check run status, tail logs, drive fixes from your editor and run one-off jobs on fresh runners. Any MCP client works, including Claude Code and Cursor, against Latchkey's MCP server at `https://latchkey.dev/mcp`.

### Are API keys read-only?

By default, yes. Keys are workspace-scoped, shown once at creation and revocable at any time. Re-running workflows, reading CLI job status and logs, and running jobs are each a separate explicit opt-in chosen when the key is created, so nothing gains write access by accident.

### How do I hand a specific finding to my agent?

From the AI Insight page. Copy prompt puts the finding and its context on your clipboard in a form an agent can act on, and a Set up MCP shortcut is offered if no key exists yet, so you do not have to reconstruct the problem by hand.

---

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