Skip to content
Latchkey home
Documentation menu

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

  1. Settings, API keys and agents creates lk_live_ keys for Latchkey's MCP server at https://latchkey.dev/mcp.
  2. 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.
  3. 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.
  4. 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.
app.latchkey.dev / acme / settings

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.

FIG. 2.7-AThe full key is shown once, when it is created; after that the list shows only its prefix and last four characters, and the access the key was created with never changes. Copy the key first: step 3 then gives the connect command with the key already in it.

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:

List failed runstool
Enumerate the recent failures on Latchkey runners that self-heal recorded but did not fix, with their key metadata. Failed CLI jobs appear too.
Get failure bundletool
Pull what Latchkey holds for one failure: logs, diagnosis and workflow details, where Latchkey kept them.
List healstool
Read the self-heal records of your workspace in a date range, of every outcome, a page at a time.
Get a healtool
Read one self-heal record in full, of any outcome, with secrets scrubbed.
List findingstool
Read the open AI Insight findings of your workspace, the ones the AI Insight page shows, highest figure first.
Get a findingtool
Read one AI Insight finding in full, of any status, with the evidence it was computed from and, where the finding stores one, the change an apply would make.
Check run statustool
Poll a run Latchkey served for its status, conclusion, and per-job timing, or read an earlier attempt of a Latchkey CI run.
List runstool
The Latchkey CI runs of a commit or a pull request, each with its jobs, how they failed and its cost. Requires a jobs-enabled key.
Wait for a runtool
Follow a run, the runs at a commit, or a pull request's runs at its newest commit, until they end, at most 25 seconds a call. A scheduled run that began after the wait is not followed. Requires a jobs-enabled key.
Tail run logstool
Read the secret-scrubbed log tail of a completed job in a GitHub Actions run of a monitored repository, green runs included.
Re-run a workflowtool
Trigger a GitHub Actions workflow_dispatch run to verify a fix. Requires a dispatch-enabled key.
Start a Latchkey CI workflowtool
Start a Latchkey CI workflow file on a branch or tag, with its inputs. Requires a key with the workflows:run scope and bills runner minutes.
Re-run a Latchkey CI runtool
Re-run the jobs of a Latchkey CI run that did not pass, as a new attempt; 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. Requires a key with the runs:control scope and bills runner minutes.
Cancel a Latchkey CI runtool
Cancel every job of a Latchkey CI run that has not finished. Requires a key with the runs:control scope.
Run a one-off jobtool
Run a shell command on a fresh Latchkey runner. Requires a jobs-enabled key and bills runner minutes.
Check job statustool
A CLI job's state and, once it finishes, the command's exit code.
Read job logstool
A Latchkey CI or CLI job's output from the start or its latest lines, so the agent reads how the job ended or sees that a long job is still writing.
List jobstool
The workspace's jobs, newest first, or only the ones still queued or running, each with its state, elapsed time and cost so far.
Cancel a jobtool
End a job the agent started, at once if it is still waiting in the queue. Requires a jobs-enabled key.
Set a batch budgettool
Set or lower a budget for a batch of jobs. Once its jobs have cost that much at list rates, Latchkey starts no more of them. Requires a jobs-enabled key.
Get a batchtool
One batch's budget, what its jobs have cost at list rates, how many are in each state and why its queued jobs wait, with its jobs newest first.
Plan a migrationtool
Propose the move of a repository's pipelines to Latchkey CI, and the answers it needs.
Apply a migrationtool
Open the one pull request that adds the plan's workflow files, for a repository connected to Latchkey CI; a person merges it.
Get a migrationtool
See where the newest migration pull request stands.
List Latchkey stepstool
The Latchkey steps a workflow file can name, with each published version's inputs, their rules and defaults, and its outputs.
List trial verdictstool
How a repository's trial runs and pipelines on trial compared with GitHub Actions, from what Latchkey recorded when each ended, with the failed step it kept for a run that failed on Latchkey CI alone. Requires a jobs-enabled key.
List environment branch rulestool
The branches each environment of a repository accepts, which an owner or admin sets in the dashboard.
Validate a workflow filetool
The first refusal a changed workflow file would earn, or the jobs it compiles to and the most one run of them can cost, with nothing started. Requires a jobs-enabled key.
Fix a CI failureprompt
Drive a guided fix of a specific failure from inside your editor.
Triage CI failuresprompt
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 agentCapability 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#

01
Create an API key

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.

02
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.

03
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:

terminal
1claude mcp add --transport http latchkey \
2 https://latchkey.dev/mcp \
3 --header "Authorization: Bearer lk_live_YOUR_KEY"
04
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.

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_dispatch trigger. A Latchkey CI workflow file needs the workflows:run scope 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 (small when 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_REACHED at the spend limit, JOB_CREATION_BLOCKED_FREE_ALLOWANCE_REACHED at the included minutes of a workspace with no plan, and TRIAL_EXPIRED, SUBSCRIPTION_REQUIRED or SUBSCRIPTION_CANCELED when the workspace's plan does not let it run jobs (at job creation, the rarer JOB_CREATION_BLOCKED_NO_SUBSCRIPTION, JOB_CREATION_BLOCKED_TRIAL_EXPIRED and JOB_CREATION_BLOCKED_SUBSCRIPTION_INACTIVE say the same). A new job in a batch at its budget is refused with JOB_BATCH_BUDGET_REACHED.
  • Cancel a job with the Cancel a job tool or latchkey cancel, which need the jobs:run scope, 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.
acme-api · zsh · latchkey run

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).

FIG. 2.7-BAn agent drives latchkey run like any shell command: the failing test is already in the stream it reads, and the exit code, 1 then 0, is the verdict. Every run packs the working tree again, so the fix reaches the next job without a commit or a push.

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.

FileWhat it is
/openapi.jsonOpenAPI 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.jsonMCP server descriptor: transport, auth, and all twenty-eight tools with their scopes.
/agent.txtShort plain-text brief on when to reach for Latchkey and how to call it.
/llms.txtIndex 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.