Documentation menu
Dashboard & analytics
Managed runners
Team & notifications
Billing & plans
Workflow files
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.
In short
- Settings, API keys and agents creates
lk_live_keys for Latchkey's MCP server athttps://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, run one-off jobs on fresh runners, and list and cancel their jobs.
- The AI Insight page can hand a finding straight to your agent with Copy prompt, and First time? Connect your agent or the Set up MCP finding shows the connect command.
- 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.
Settings, API keys and agents tab. The API keys panel, with 3 keys, walks three steps: 1 Details, 2 Copy key and 3 Connect agent. On step 2 the new key ci-agent-codex is shown once in full, under the warning Copy your key now. You will not be able to see it again. and the line that Latchkey stores only a hashed version. The continue button, I've saved it, continue, waits until the key is copied. The key is copied, and step 3 opens Connect your agent with Claude Code chosen: the command claude mcp add --transport http latchkey https://latchkey.dev/mcp --header "Authorization: Bearer" with the new key already filled in, a box to read the key from $LATCHKEY_API_KEY instead of pasting it, a note that the command writes the token in plaintext to ~/.claude.json, and the Latchkey CLI install command npm install -g @latchkeydev/cli. The command is copied. Under the steps, the Active table lists ci-agent-codex first, marked New, masked to its prefix lk_live_7f3a and its last four characters 3f2a, with access mcp:read, jobs:read and jobs:run, never used and never expiring, then deploy-bot, and cursor-ci marked Unused 30d.
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: self-healing fixes environment failures during the run and never touches your source, so when the real problem is a bug in your code that fails on every try, the build fails, 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 and agents (the setup below), or let the AI Insight 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, under Hand off to agent, and First time? Connect your agent there, like the workspace-wide Set up MCP finding, shows the exact connect command with Create a key for your agent (owners and admins), which creates a key named coding-agent and fills it in. 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 thirty capabilities: twenty-eight tools your agent calls for data and actions, and two prompt flows that orchestrate a whole task:
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 is still running?" | List jobs |
| "Give this batch of jobs a $5 budget" | Set a batch budget |
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.
You open your editor and ask: "What is failing in our repos?" The agent runs the Triage CI failures flow and comes back with a survey of failures across your monitored repositories, prioritized. You narrow it: "Which of those matter most for the release?" and the agent reasons over the same data without you ever opening a CI tab.
The value is the loop staying in one place: question, context, next question, all inside the editor session where you will make the fix.
You ask: "Pull the failure bundle for the latest red build and fix it." The agent lists recent failed runs to find the right one, pulls what Latchkey holds for it (logs, diagnosis and workflow details, where Latchkey kept them), and then drives a guided fix from inside your editor, proposing changes for you to review.
Note what did not happen: the agent never touched Latchkey settings or GitHub through the key. It read failure context; the code changes went through you.
What is in a failure bundle#
The failure bundle hands your agent the pieces it would otherwise reconstruct by hand, where Latchkey kept them:
- 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 found and why it stood down, plus the workflow definition.
Setup#
Open Settings, API keys and agents (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. Under Access, pick what the key may do: Read-only is the default, CLI runner adds running CLI jobs, Full access grants every capability, and Customize access sets each capability on its own; capabilities are fixed at creation.
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.
The Connect your agent block on the same settings tab shows the exact command for your workspace. For Claude Code it looks like:
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.
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 the Dispatch access. 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 when their jobs run on Latchkey runners, 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 GitHub Actions workflows that declare the
workflow_dispatchtrigger. A Latchkey CI workflow file needs theworkflows:runscope instead. - Existing keys never gain dispatch retroactively; mint a new key with the Dispatch access.
- The re-run runs whatever is on the branch you dispatch against; push the fix first, then dispatch.
Run jobs on fresh runners (opt-in)#
The second opt-in write is running one-off jobs. A key created with the CLI runner access 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, which packs and uploads it. Under Customize access, 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 3 hours, and the agent picks a runner size (
smallwhen it does not). - A jobs-enabled key spends money: every job bills by the minute at its runner size's list rate ($0.0025 on small, $0.0050 on medium, $0.0100 on large, $0.0200 on xlarge). Name the key for the agent that holds it, give it an expiry, and give the agent's work a budget: a per-job budget, or a budget on a batch named for the agent or person who started it.
- A refusal at a spend limit, the included minutes or the workspace's plan is a limit to report to your human, never one to retry. A batch at its budget takes a new batch name or a report, never a retry under the same name.
- Those refusals carry a code:
JOB_CREATION_BLOCKED_SPEND_CAP_REACHEDat the spend limit,JOB_CREATION_BLOCKED_FREE_ALLOWANCE_REACHEDat the included minutes of a workspace with no plan, andTRIAL_EXPIRED,SUBSCRIPTION_REQUIREDorSUBSCRIPTION_CANCELEDwhen the workspace's plan does not let it run jobs (at job creation, the rarerJOB_CREATION_BLOCKED_NO_SUBSCRIPTION,JOB_CREATION_BLOCKED_TRIAL_EXPIREDandJOB_CREATION_BLOCKED_SUBSCRIPTION_INACTIVEsay the same). A new job in a batch at its budget is refused withJOB_BATCH_BUDGET_REACHED. - Cancel a job with the Cancel a job tool or
latchkey cancel, which need thejobs:runscope, or with Cancel job in the title bar of its own page in the dashboard, which its row under Running now on the Runs page opens.
In a terminal in ~/acme-api, a coding agent runs latchkey run 'npm test'. The CLI packs and uploads the working tree and the job's log streams back: state: running, then vitest. src/billing/invoice.test.ts passes. In src/auth/refresh.test.ts the test keeps a token with an hour left fails with AssertionError: expected true to be false // Object.is equality, and the summary reads 1 failed and 411 passed of 412 tests. The CLI prints state: failed and Job cli-3a7f1e92-6c4b-4d18-8e5a-2b9c0d7f4a16 failed (exit 1). The agent types the comment # fix: convert expires_at from seconds to ms in src/auth/refresh.ts, then runs latchkey run 'npm test' again. The new job packs the edited tree the same way, src/auth/refresh.test.ts passes, all 412 tests in 38 files pass, and the CLI prints state: succeeded and Job cli-9e04b6d3-1f7a-4c2e-b5d8-6a3f0e1c7b29 succeeded (exit 0).
Approve runs for an environment (opt-in)#
A key created with the Approve runs or Full access preset, or with Allow approving runs for an environment under Customize access, carries the jobs:approve scope. Its holder can approve or reject a waiting run for any environment in this workspace through the Jobs API, which starts the jobs that name that environment or ends them without starting. It works only while the person who created the key is an owner or admin. An agent that holds such a key and can also push to a repository can approve the runs of its own changes, with no other person deciding.
Open migration pull requests (opt-in)#
A key created with the Migration pull requests or Full access preset, or with Allow opening migration pull requests under Customize access, carries the migration:apply scope. Its holder can open the pull request that adds a migration plan's Latchkey CI workflow files to a repository that is connected to Latchkey CI, and close an earlier migration pull request of that repository. It works only while the person who created the key is an owner or admin.
Start Latchkey CI workflows (opt-in)#
A key created with the Full access preset, or with Allow starting Latchkey CI workflows under Customize access, carries the workflows:run scope. Its holder can start any Latchkey CI workflow file that declares on: workflow_dispatch, in any repository of this workspace connected to Latchkey CI, at any branch or tag and with any inputs, deploy workflows included. Its jobs run on billable Latchkey runners, and a job bound to an environment that needs an approval still waits for one, unless it is held in a trial run or a pipeline on trial, or its environment does not accept the run. The scope works only while the person who created the key is in the workspace.
Re-run and cancel Latchkey CI runs (opt-in)#
A key created with the Full access preset, or with Allow re-running and cancelling Latchkey CI runs under Customize access, carries the runs:control scope. Its holder can re-run the jobs that did not pass of any Latchkey CI run in this workspace other than a preflight, deploy runs included, and cancel any run that has not finished. A re-run's jobs run on billable Latchkey runners, and a job bound to an environment that needs an approval waits for one, unless it is held in a trial run or a pipeline on trial, or its environment does not accept the run. The scope works only while the person who created the key is in the workspace.
Security model#
- Read-only by default. Keys can read CI failure and run data and your workspace's AI Insight findings; changing anything in Latchkey or GitHub is off by default. The writes a key can opt into at creation are workflow dispatch (
mcp:dispatch), running jobs on Latchkey runners (jobs:run), setting workspace secrets (secrets:write), approving runs for an environment (jobs:approve), opening migration pull requests (migration:apply), starting Latchkey CI workflows (workflows:run) and re-running and cancelling Latchkey CI runs (runs:control). A secrets key can set or replace a secret but never read one back, and no key reaches any other Latchkey setting 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 and agents, and it loses access within 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, the log tail of any completed job in a GitHub Actions run of a monitored repository, green runs included, the migration plan of any repository connected to Latchkey CI, and your workspace's AI Insight findings with the evidence behind them (estimated savings and money already spent, lists of unpinned actions, proposed workflow changes, the commit, run, job and step of the newest failure a trial saw only on Latchkey CI, and the batch or API key name, job count and spend behind a burst of jobs), 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, a stolen jobs-enabled key can run commands on billable runners in your workspace and read the logs of the workspace's Latchkey CI and CLI jobs, a stolen key with workflows:run can start any Latchkey CI workflow that can be started on demand, deploy workflows included, a stolen key with runs:control can re-run the jobs that did not pass of any Latchkey CI run other than a preflight, deploy runs included, or cancel any run that has not finished, a stolen key with migration:apply can open the pull request that adds a migration plan's Latchkey CI workflow files to any repository connected to Latchkey CI, or close an earlier migration pull request of that repository, and a stolen secrets-enabled key can set or replace any workspace or repository secret your jobs read (though it can never read one back), and a stolen approvals-enabled key can approve a waiting run for any environment and so start its jobs, 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 and Security and permissions for the wider model.
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 an OpenAPI 3.1 specification describes its job, batch, environment and approval operations; the MCP server has its own manifest listing every tool and the scope it needs.
| File | What it is |
|---|---|
| /openapi.json | OpenAPI 3.1 contract for the job, batch, environment and approval operations of the Jobs API: typed schemas, scopes and error shapes. |
| /.well-known/mcp/manifest.json | MCP server descriptor: transport, auth, and all twenty-eight tools with their scopes. |
| /agent.txt | Short plain-text brief on when to reach for Latchkey and how to call it. |
| /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.
Q.01What 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.
Q.02Are 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.
Q.03How 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 First time? Connect your agent, under it, shows the connect command and, for owners and admins, a button that creates a key for it, so you do not have to reconstruct the problem by hand.