# AI エージェントを接続する (MCP)

> Claude Code、Cursor、または MCP 対応の任意のエージェントに、CI の失敗への安全なアクセスに加えて、オプトインのワークフロー再実行と、まっさらなランナーでの単発ジョブを与え、エディタからトリアージ、修正、検証を行えるようにします。

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

## Summary

- **Settings, API Keys** で、`https://latchkey.dev/mcp` にある Latchkey の MCP サーバー用の `lk_live_` キーを作成します。
- 接続したエージェント (Claude Code、Cursor、任意の MCP クライアント) は、失敗のトリアージ、失敗バンドルの取得、実行ステータスの確認、ログのテール、エディタからの修正の実行、そしてまっさらなランナーでの単発ジョブの実行を行えます。
- AI Insight ページは、**Copy prompt** または **Set up MCP** ショートカットで、検出結果をそのままエージェントに引き渡せます。
- キーはデフォルトで読み取り専用、ワークスペースにスコープされ、作成時に一度だけ表示され、いつでも取り消せます。ワークフローの再実行、CLI ジョブのステータスとログの読み取り、ジョブの実行は、それぞれキー作成時の別個の明示的なオプトインです。

Latchkey は **MCP サーバー** を提供します。AI コーディングエージェントは Latchkey の API キーで接続し、実際の CI 失敗コンテキスト (失敗した実行、ログ、診断バンドル) をエディタセッションに直接取り込めます。ログをチャットにコピー＆ペーストする代わりに、エージェントが Latchkey に直接問い合わせ、失敗を修正するために必要なものをすべて取得します。

これは [自己修復](/documentation/self-healing) の引き継ぎ側です。自己修復は実行中に環境の失敗を修正し、ソースには一切触れません。そのため、本当の問題がコードのバグである場合、ビルドは正直に失敗し、その失敗はエージェント向けのすぐ修正できるバンドルとしてここに届きます。

入り口は 2 つあります。**Settings, API Keys** で自分でキーを作成するか (以下のセットアップ)、[AI Insight](/documentation/optimization-insights) ページに任せるかです。自分のコーディングエージェントで修正する方がよい検出結果には、エージェントに貼り付けられる既製のプロンプト **Copy prompt** と、`coding-agent` という名前のキーを作成して正確な接続コマンドを表示する **Set up MCP** ショートカットが用意されています。発行されたキーの有効期限は 90 日で、課金対象のランナーで単発ジョブを実行できるため (その旨はカードのボタンの横に明記されています)、支出できる資格情報としてそれ相応に扱ってください。

## 接続したエージェントができること

サーバーは 10 個の機能を公開します。エージェントがデータと操作のために呼び出す 8 つの **ツール** と、タスク全体をオーケストレーションする 2 つの **プロンプトフロー** です:

- **失敗した実行の一覧** 最近の失敗したワークフロー実行を、主要なメタデータとともに列挙します。失敗した CLI ジョブも表示されます。
- **失敗バンドルの取得** 1 つの失敗の完全なコンテキスト (ログ、診断、ワークフローの詳細) を取得します。
- **実行ステータスの確認** 任意の実行のステータス、結果、ジョブごとの所要時間をポーリングします。
- **実行ログのテール** 完了した任意のジョブの、シークレット除去済みログの末尾を読み取ります。成功した実行も対象です。
- **ワークフローの再実行** 修正を検証するために workflow_dispatch 実行をトリガーします。ディスパッチ有効のキーが必要です。
- **単発ジョブの実行** まっさらな Latchkey ランナーでシェルコマンドを実行します。ジョブ有効のキーが必要で、ランナー分数が課金されます。
- **ジョブステータスの確認** CLI ジョブの状態と、完了後はコマンドの終了コード。
- **ジョブログの読み取り** CLI ジョブの出力。エージェントは自分が実行したコマンドの結果を読み取れます。
- **CI 失敗の修正** 特定の失敗について、エディタ内からガイド付きの修正を実行します。
- **CI 失敗のトリアージ** 監視対象リポジトリ全体で何が失敗しているかを調べ、優先順位を付けます。

これらを名前で呼び出すことはありません。エージェントに平易な言葉で質問すると、エージェントがどの機能で答えるかを判断します。いくつかの対応例:

| エージェントへの質問 | エージェントが使う機能 |
| --- | --- |
| 「今、私たちのリポジトリ全体で何が失敗している?」 | **CI 失敗のトリアージ** |
| 「このリポジトリの最近の失敗した実行を見せて」 | **失敗した実行の一覧** |
| 「あの失敗した実行について持っている情報をすべて取得して」 | **失敗バンドルの取得** |
| 「失敗しているビルドを修正して」 | **CI 失敗の修正** |
| 「あの実行は通った? 各ジョブはどれくらいかかった?」 | **実行ステータスの確認** |
| 「デプロイジョブのログの末尾を見せて」 | **実行ログのテール** |
| 「修正をプッシュした。CI を再実行して見守って」 | **ワークフローの再実行** |
| 「クリーンな Linux ランナーでテストスイートを実行して」 | **単発ジョブの実行** |
| 「あのジョブは終わった? 何を出力した?」 | **ジョブステータスの確認** と **ジョブログの読み取り** |

### セッションの様子

2 つの例示的なセッションです。正確な言い回しやエージェントの実際の返答はエージェントによって異なります。重要なのはやり取りの形です。

## 失敗バンドルに含まれるもの

失敗バンドルは、エージェントが本来手作業で再構築するものを渡します:

- **根本原因** を平易な言葉で。
- 失敗したステップの **終了コード** と、エラーが表面化した正確なソースファイル。
- 失敗したステップの **キャプチャされた完全なログ**。GitHub がログビューアで隠す出力も含みます。非常に大きなログは末尾部分が保持され、その旨が明記されます。ログが Latchkey を離れる前にシークレットは除去されます。
- **自己修復がすでに調査した内容** と、なぜ引き下がったか、加えてワークフロー定義。

## セットアップ

1. **API キーを作成する** **Settings, API Keys** を開きます (キーの管理はオーナーと管理者が行います)。**Generate key** をクリックし、設置場所にちなんだ名前を付け (例: 「私のノート PC の Cursor」)、有効期限を選びます: **無期限** (デフォルト)、30 日、60 日、90 日、または 1 年。キーに必要な機能 (ワークフローのディスパッチ、CLI ジョブのステータスとログの読み取り、CLI ジョブの実行) にチェックを入れます。機能は作成時に固定されます。
2. **キーをすぐにコピーする** 完全なキー (`lk_live_` で始まります) は作成時に **一度だけ** 表示されます。その後、UI にはプレースホルダーしか表示されません。パスワードのように扱ってください。紛失した場合は取り消して新しいものを作成します。
3. **エージェントを接続する** 同じ設定タブの **Connect your agent** ブロックに、あなたのワークスペース向けの正確なコマンドが表示されます。Claude Code の場合は次のようになります:
4. **使ってみる** 失敗している CI についてエージェントに尋ねます (「私たちのリポジトリで何が失敗している?」「最新の赤いビルドの失敗バンドルを取得して修正して」)。ベアラーヘッダー付きの HTTP トランスポートに対応する MCP 互換クライアントであれば、どれも同じように動作します。

> **Claude Code のショートカット**
> Claude Code では、組み込みの `/mcp__latchkey__fix` コマンドが「Fix a CI failure」プロンプトフローを 1 ステップで実行します。最も新しい未修正の失敗を取得し、作業に取りかかります。

## 修正後にワークフローを再実行する (オプトイン)

デフォルトではキーは読み取り専用です。ループを閉じたい場合 (エージェントがコードを修正し、プッシュし、CI を再実行し、グリーンになるのを見届ける)、**Allow workflow dispatch** にチェックを入れてキーを作成します。そのキーは追加で `mcp:dispatch` スコープを持ち、エージェントは監視対象リポジトリで `workflow_dispatch` 実行をトリガーし、実行ステータスツールでポーリングし、完了後にログを読めるようになります。グリーンの実行も読み取れるため、エージェントは失敗を観察するだけでなく、修正を確認できます。

- ディスパッチは、ワークスペースが監視しているリポジトリでのみ、かつ `workflow_dispatch` トリガーを宣言しているワークフローに対してのみ機能します。
- 既存のキーが遡ってディスパッチ権限を得ることはありません。チェックボックスを有効にして新しいキーを作成してください。
- 再実行は、ディスパッチ先のブランチにあるものをそのまま実行します。まず修正をプッシュしてから、ディスパッチしてください。

> **ディスパッチキーは、ディスパッチ可能な任意のワークフローをトリガーできます**
> 監視対象リポジトリで手動ディスパッチ可能になっていれば、デプロイワークフローも含まれます。その範囲を任せられるエージェントのキーに限ってディスパッチを有効にし、キーには置き場所がわかる名前を付け、疑わしくなった瞬間に取り消してください。

## まっさらなランナーでジョブを実行する (オプトイン)

2 つ目のオプトインの書き込みは、単発ジョブの実行です。**Allow running CLI jobs (includes reading)** を有効にして作成したキーは `jobs:run` スコープを持ち (ステータスとログのための `jobs:read` も一緒に付与されます)、エージェントは **単発ジョブの実行** ツールを使えるようになります。まっさらで隔離された Latchkey ランナーで 1 つのシェルコマンドを実行し、ワークフローと同じ無料分プールから通常のランナー分数として課金されます。ランナーはリポジトリの内容を持たないクリーンな状態で起動します。作業ツリーが必要なジョブは、それをパックしてアップロードする [Latchkey CLI](/documentation/latchkey-cli) を経由します。**Allow reading CLI job status and logs** は、ジョブを追跡するが決して開始しないキーのための、より狭い権限 (`jobs:read` のみ) です。

- ジョブのタイムアウトはデフォルトで 30 分、最大 2 時間まで設定可能です。ランナーサイズはエージェントが選択します (選択しない場合は `small`)。
- ジョブ有効のキーはお金を使います。すべてのジョブは、ランナーの標準的な 1 分あたりの料金で課金されます。キーには保持するエージェントがわかる名前を付け、有効期限を設定してください。
- ジョブのキャンセルは CLI の操作 (`latchkey cancel`) であり、MCP ツールではありません。

## セキュリティモデル

- **デフォルトで読み取り専用。** キーは CI の失敗と実行のデータを読み取れます。Latchkey や GitHub の変更はデフォルトで無効です。キーが作成時にオプトインできる書き込みはワークフローのディスパッチ (`mcp:dispatch`) と Latchkey ランナーでのジョブ実行 (`jobs:run`) で、どちらも Latchkey の設定や任意の GitHub 操作に及ぶことはありません。
- **ワークスペーススコープ。** ワークスペースはキー自体から導出されるため、キーは自分のワークスペースのデータしか見られません。
- **取り消し可能。** Settings, API Keys から任意のキーを取り消せます。書き込み可能なキー (ディスパッチまたはジョブ) は即座にアクセスを失い、読み取り専用キーも約 1 分以内にアクセスを失います。取り消したキーは監査用に「Revoked (n)」セクションに一覧され続けます。

これら 3 つの性質が実際に何を意味するか。デフォルト読み取り専用は漏洩時の影響範囲を限定します。盗まれたデフォルトキーは CI の失敗データ (ログの抜粋を含む) を露出させるため、依然として保護すべきですが、PR を開いたり、設定を変更したり、あなたに代わって GitHub 上で操作したりはできません。盗まれたディスパッチ有効キーは、それに加えて監視対象リポジトリのディスパッチ可能なワークフローをトリガーでき、盗まれたジョブ有効キーはワークスペースの課金対象ランナーでコマンドを実行できます。だからこそ各書き込みはデフォルトではなく、作成時に警告付きのキーごとのオプトインになっています。ワークスペーススコープは、設定すべきものも間違えるものも何もないことを意味します。キー自体が見られる範囲を決定し、他のワークスペースを見ることは決してできません。そして取り消しは迅速で、取り消したキーは監査用に一覧され続けるため、少しでも疑わしければ取り消して再発行するのが安全な対応です。

これをきれいに保つ、手間のかからない 2 つの習慣。ツールやマシンごとに別々のキーを作成すること (作成時の命名プロンプト、たとえば「私のノート PC の Cursor」は、まさにこのために存在します)。そうすれば 1 つのキーを取り消しても他のキーは壊れません。そして、自分の働き方に合った最短の有効期限を選び、**無期限** は積極的に把握している構成のためだけに使うこと。キー管理はオーナーと管理者が担当します。より広いモデルについては [チームとロール](/documentation/team-and-roles) と [セキュリティと権限](/documentation/security-and-permissions) を参照してください。

> **キーはパスワードのように扱う**
> キーを持つ者は誰でもあなたの CI 失敗データ (ログの抜粋を含む) を読めます。リポジトリではなくエージェントの設定に保存し、漏洩した可能性があればローテーションしてください。

Latchkey は、エージェントが説明を受けなくても利用面を発見できるよう、機械可読なディスクリプタも公開しています。REST の Jobs API は `https://api.latchkey.dev` で提供され、OpenAPI 3.1 仕様で完全に記述されています。MCP サーバーには、すべてのツールと必要なスコープを列挙した独自のマニフェストがあります。

| ファイル | 内容 |
| --- | --- |
| [/openapi.json](https://latchkey.dev/openapi.json) | Jobs API の OpenAPI 3.1 契約: オペレーション、型付きスキーマ、スコープ、エラー形式。 |
| [/.well-known/mcp/manifest.json](https://latchkey.dev/.well-known/mcp/manifest.json) | MCP サーバーのディスクリプタ: トランスポート、認証、8 つのツールとそのスコープ。 |
| [/agent.txt](https://latchkey.dev/agent.txt) | Latchkey をいつ使い、どう呼び出すかを簡潔にまとめたプレーンテキスト。 |
| [/llms.txt](https://latchkey.dev/llms.txt) | サイトとコンテンツの索引。利用場面のセクション付き。 |

サイト上のすべてのコンテンツページには、同じ URL に `.md` を付けたマークダウン版もあり、ページの head から `rel="alternate"` リンクで参照されています。ページのマークアップを含まず同じ内容を持つため、エージェントにとって読み取りコストが大幅に低くなります。

> **エージェントが 401 を受け取り始めたら**
> 401 は、キーがもう認証されないことを意味します。取り消されたか、作成時に設定した有効期限に達したかです。どちらの場合も対処は同じです。Settings, API Keys で新しいキーを作成し、エージェント設定の Authorization ヘッダーを更新してください。完全なキーは作成時に一度だけ表示されることを忘れないでください。その他の接続の問題については、まず [トラブルシューティング](/documentation/troubleshooting) から始めてください。

### 接続した AI エージェントは実際に何ができますか?

失敗のトリアージ、failure bundle の取得、実行状況の確認、ログの追跡、エディタからの修正の実行、そして新しいランナーでの単発ジョブ実行ができます。Claude Code や Cursor を含む任意の MCP クライアントが、`https://latchkey.dev/mcp` の Latchkey MCP サーバーに接続できます。

### API キーは読み取り専用ですか?

既定では読み取り専用です。キーはワークスペース単位で、作成時に一度だけ表示され、いつでも失効できます。ワークフローの再実行、CLI ジョブの状態とログの参照、ジョブの実行は、キー作成時にそれぞれ個別に明示的なオプトインが必要なため、誤って書き込み権限が付くことはありません。

### 特定の分析結果をエージェントに渡すには?

AI Insight ページから行えます。Copy prompt を使うと、その分析結果と文脈がエージェントの処理しやすい形でクリップボードにコピーされます。キーが未作成の場合は Set up MCP のショートカットが表示されるため、問題を手作業で組み立て直す必要はありません。

---

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