# 外部エージェント (/ja/docs/ai/agents)

EcholotにはMCPサーバが組み込まれています。Claude Code、Claude Desktop、Cursor、VS Code、CodexなどのAIクライアントは、このサーバを通じて、
保存済みのリクエストの一覧表示、送信、レスポンスの読み取り、チェックの追加、フォルダの実行ができます。使うツールはアプリ自身が使うものと同じです。
ワークスペースがEcholotで開いている間、クライアントの呼び出しはアプリの中で実行されます。データを変更する可能性のある操作はあなたが承認し、
すべての呼び出しを確認でき、シークレットの値がエージェントに渡ることはありません。

## 仕組み [#how-it-works]

クライアントは、ワークスペースのパスを指定して `echolot mcp serve` を起動します。その後の動作は、アプリの状態によって変わります。

- **ワークスペースがEcholotで開いていて、エージェントがオンの場合。** コマンドはアプリに接続し、クライアントの呼び出しはワークスペースのウインドウで
  実行されます。承認が必要な呼び出しはシートで確認され、すべての呼び出しがページヘッダーの**エージェント**に表示されます。
- **それ以外の場合**（アプリが終了している、ワークスペースが開いていない、またはエージェントがオフ）、コマンドが単独でワークスペースを提供します。
  確認できる相手がいないため、確認が必要な操作は拒否されます。[単独で動作する場合](#on-its-own)を参照してください。

開いている各ウインドウは、自分のワークスペースを `127.0.0.1` だけで、システムが選んだポートで提供します。呼び出せるのは、そのセッション用に作られた
ランダムなトークンを提示した相手だけです。コマンドは、EcholotのApplication Supportフォルダにある非公開のファイルを通じてウインドウを見つけます。
ネットワーク上で待ち受けるものはありません。

## エージェントをオンにする [#turn-agents-on]

<Steps>
<Step>
**設定 › エージェント**を開き、**開いているワークスペースの使用をエージェントに許可**をオンにします。オンにするまではオフです。同じスイッチは、
ワークスペースのウインドウのページヘッダーにある**エージェント**ポップオーバーにもあります。
</Step>
<Step>
Echolotでワークスペースを開きます。ウインドウがワークスペースを提供している間、ページヘッダーの**エージェント**の横のドットが緑色になります。
クライアントが接続されていると、その数が表示されます。
</Step>
<Step>
次の手順でクライアントを接続します。ワークスペースとクライアントの組み合わせごとに1回だけ行います。
</Step>
</Steps>

ワークスペース側でエージェントをオフにすることもできます：**ワークスペース設定 › エージェント › エージェントにこのワークスペースの使用を許可**。
オフにすると、アプリ経由でも単独でも、クライアントはこのワークスペースから何も取得できません。

## クライアントを接続する [#connect-a-client]

ページヘッダーの**エージェント**をクリックします。**クライアントを接続**の下に、クライアントごとのボタンがあります。

<Shot id="ai-agents-popover" alt="ページヘッダーのエージェントポップオーバー。エージェントを許可するスイッチ、接続中のクライアント、最近の呼び出し、クライアントを接続のボタンが並んでいる" />

| クライアント | ボタン | 動作 |
| --- | --- | --- |
| **Claude Desktop** | **Claudeに追加** | このワークスペース用のClaude Desktop拡張機能を作成し、Claude Desktopで開きます。Claude Desktopが確認を求めます。直接ダウンロード版のみです。 |
| **Claude Code** | **コマンドをコピー** | `claude mcp add` コマンドをコピーします。ターミナルにペーストしてください。 |
| **Cursor** | **Cursorに追加** | MCPサーバをインストールするためのCursorのプロンプトを開きます。 |
| **VS Code** | **VS Codeに追加** | MCPサーバをインストールするためのVS Codeのプロンプトを開きます。 |
| **Codex** | **config.tomlのエントリをコピー** | Codexの `config.toml` にペーストするエントリをコピーします。 |
| **その他** | **JSONをコピー** | `mcpServers` エントリをコピーします。ほとんどのMCPクライアントが読み込む形式です。 |

その下には、コマンド自体と**コピー**ボタンがあります。コマンドと引数を求めるクライアントに使えます。

サーバ名は、`echolot-` にワークスペース名を続けたものになります。Alpenglowワークスペースの場合、Claude Codeのコマンドは次のようになります
（`echolot` へのパスはアプリ内にあるツールです）。

```sh
claude mcp add --scope user echolot-alpenglow -- /Applications/Echolot.app/Contents/Helpers/echolot mcp serve ~/Alpenglow.echolot
```

Codexのエントリは次のようになります。

```toml
[mcp_servers.echolot-alpenglow]
command = "/Applications/Echolot.app/Contents/Helpers/echolot"
args = ["mcp", "serve", "/Users/you/Alpenglow.echolot"]
```

ターミナルから `echolot mcp setup <client> -w <workspace>` を実行すると、`claude-code`、`claude-desktop`、`cursor`、`vscode`、`codex` 向けの
同じ設定を出力できます。[`echolot mcp`](/docs/cli/mcp)を参照してください。

<Edition only="appstore">
  Mac App Store版には、アプリ内のコマンドラインツールも、Claude Desktop拡張機能もありません。コマンドラインツールを別途インストールしてください
  （設定 › エージェントとエージェントポップオーバーにある「コマンドラインツールを入手」からダウンロードできます）。クライアントがそれを実行し、
  ワークスペースがEcholotで開いている間は、呼び出しは引き続きアプリの中で実行されます。ボタンはコマンドやスニペットをコピーするか、
  クライアント自身のインストールプロンプトを開くだけで、ほかのアプリのフォルダには書き込みません。
</Edition>

### Claude Desktopをワンクリックで追加する [#claude-desktop-in-one-click]

<Edition only="direct">
  Claude Desktop拡張機能（`.mcpb`）にはコマンドラインツールが含まれているため、直接ダウンロード版でのみ使えます。
</Edition>

**設定 › エージェント › Claude Desktop**には、最近使ったワークスペースが一覧表示されます。ワークスペースの横の**Claudeに追加**を押すと、エージェントがオンになり、
そのワークスペース用の拡張機能が作成されてClaude Desktopに渡され、確認を求められます。Claude Desktopに追加されると、行には**追加済み**と表示されます。
あとで拡張機能を更新するには、**追加済み**をControlキーを押しながらクリックし、**もう一度追加**を選びます。

Claude Desktopがインストールされていない場合は、このセクションにその旨が表示され、**Claude Desktopを入手**のリンクが出ます。
このとき**Claudeに追加**は、拡張機能をFinderに表示します。

## ツールセット [#toolsets]

エージェントに見えるツールは、1つごとにコンテキストの容量を消費します。そのためEcholotは、ツールをグループにまとめて提供します。
グループは**設定 › エージェント › エージェント用のツール**で選びます。**リクエスト**は常にオンです。**リクエスト**と**フロー**は、変更するまでオンになっています。
これらのチェックボックスで決まるのは、エージェントに見えるツールであり、確認なしで許可される操作ではありません。データを変更するとき、
新しいホストに接続するときは、どのツールも確認します。内蔵のアシスタントが何を確認するかは、**設定 › アシスタント › 確認するタイミング**で決まります。

| ツールセット | エージェントにできること |
| --- | --- |
| **リクエスト** | リクエストの一覧表示、読み取り、作成、送信、レスポンス、履歴、GraphQL、実行中のモック |
| **フロー** | エージェント向けに公開したフローの実行、フローからの質問への回答 |
| **ワークスペース** | フォルダとリクエストの作成、名前の変更、移動、複製、削除、フォルダの認証、ワークスペースの変数、収集したデータのファイルとしての保存 |
| **環境** | 環境の作成、変更、削除 |
| **仕様** | OpenAPI仕様の読み取り、書き込み、リント、フォルダとの紐づけ、変更の適用 |
| **モック** | モックサーバとそのルートの作成、変更、削除（ダミーデータを含む）、ルートからのリクエスト作成、レスポンスのサンプルとしての保存 |
| **MCPサーバ** | MCPサーバの追加、変更、チェック、削除 |
| **履歴** | 過去のやり取りの表示、比較、削除 |
| **フローの編集** | フローの読み取り、作図、削除、承認後に1回だけ試し実行 |

デフォルトのツールセットでは、エージェントは次のことができるツールを利用できます：リクエストの一覧表示、読み取り、作成、更新、送信、チェック付きでのフォルダの実行、
レスポンスの部分ごとの読み取り、履歴の確認、GraphQLクエリのチェック、リクエストのcURLやコードとしてのコピー、読み込み、仕様のリント、モックの開始と停止、
エージェント向けに公開したフローの実行。プロンプトも `debug_request` と `write_tests` の2つが使えます。

ツールセットを変更すると、開いているウインドウは新しい内容で提供を再開します。反映するにはクライアントを接続し直してください。

どのツールセットでも**提供されない**もの：エージェントのルール、プロキシ、証明書、ワークスペースの認証の変更、認証以外のフォルダ設定、スクリプト
（リクエスト、フォルダ、モックのスクリプト）、シークレットを使って取得や署名を行う認証（OAuth 2.0、AWS、JWTなど）。これらはあなただけが操作できます。

エージェントは、リクエストとフォルダに**Bearer**、**Basic**、**APIキー**の認証を設定できます。また、リクエストにレスポンスの値を保持させることもできます
（サインインのトークンを、その後のリクエストで使うなど）。`create_request` と `update_request` は `auth` と `captures` を受け取り、
`save_folder_auth` はフォルダのリクエストが継承する内容を設定します。認証情報は `{{variables}}` でなければなりません。エージェントがパスワードやトークンを
直接書き込もうとすると拒否されるため、それらがファイルに残ることはありません。名前が認証情報らしい（token、password、keyなど）キャプチャした値は、
シークレットとして保持されます。

エージェントは、自分に公開されたフロー（フロー一覧でスパークルのマークが付いたもの）を、専用のツールで開始します。開始のたびに、現在の状態のフローについて
あなたの承認が必要です。[フローの実行](/docs/flows/running-and-triggers)を参照してください。**フローの編集**がオンの場合、`try_flow` はそれ以外のフロー
（エージェントが作図中のものを含む）を1回だけ実行します。送信、保存、実行される内容が表示され、ルールにかかわらず毎回あなたが承認します。
**このセッションでは許可**が有効なのは、そのバージョンのフローに対してだけです。

## エージェントの動作を確認する [#see-what-agents-do]

ページヘッダーの**エージェント**ポップオーバーには、ウインドウがワークスペースを提供している間、次の内容が表示されます。

- 呼び出しを行った各クライアントと、その呼び出し回数、失敗回数、最後に確認された時刻。スイッチをオフにすると、以後そのクライアントの呼び出しと、
  待機中の承認が拒否されます。
- **最近の呼び出し**：直近の呼び出しと、そのツール、クライアント、時刻、所要時間、エラー。

クライアントが呼び出すまでは<strong>このワークスペースを使用したエージェントはまだありません。</strong>と表示されます。エージェントがオフの場合は、クライアントが
あなたの承認なしに単独で動作することを説明するメッセージが表示されます。

エージェントが行った送信はすべて、クライアント名とともにワークスペースの[履歴](/docs/workspaces/history)にも残ります。

## 承認 [#approvals]

ルールで確認が必要な操作をクライアントが行おうとすると、ワークスペースのウインドウにシートが表示されます：***クライアント*が*データを変更する可能性のある
リクエストを送信*しようとしています**。送信されるとおりのリクエストが表示され、シークレットはマスクされます。**1回だけ許可**、
**このセッションでは許可**（ウインドウを閉じるまで、同じ呼び出しを確認なしで許可）、**拒否**のいずれかを選びます。5分以内に誰も答えなかった確認は
拒否されます。このシートは、[アシスタント](/docs/ai/assistant#approve-what-changes)が使うものと同じです。

ワークスペースのルールがない場合に、確認する操作は次のとおりです。

| 操作 | デフォルト |
| --- | --- |
| **リクエストと環境の読み取り** | 許可 |
| **安全な送信（GET、GraphQLクエリ、MCPの読み取り）** | 許可 |
| **その他の送信** | 確認 |
| **保護された環境への送信** | 常に確認 |
| **新しいホストへの送信** | 常に確認 |
| **ワークスペースへの変更** | 確認 |
| **削除** | 確認 |

新しいホストとは、ウインドウが提供を開始した時点で、ワークスペースのどのリクエストや環境も使っていなかったホストです。エージェントが読み取ったデータが
そこから外へ出る可能性があるため、常に確認します。[保護された環境](/docs/workspaces/protected-environments)への送信も同様です。

## ワークスペースのルール [#workspace-rules]

<strong>ワークスペース設定 › エージェント</strong>（サイドバー下部のワークスペースメニューにある<strong>ワークスペース設定…</strong>から開きます）では、このワークスペースのルールを設定します。
ルールは `workspace.toml` に保存されるため、Gitを通じてワークスペースとともに受け渡され、外部エージェントとアシスタントの両方に適用されます。

<Shot id="ai-agents-workspace-rules" alt="ワークスペース設定のエージェントタブ。エージェントのスイッチ、操作ごとのルール、ホストと制限のフィールドが表示されている" />

- **エージェントにこのワークスペースの使用を許可**：オフにすると、エージェントはこのワークスペースから何も取得できません。
- **エージェントに許可する操作**：上の表の各操作に対するルール。**デフォルト**（デフォルトの内容も表示されます）、**許可**、**確認**、**拒否**から選びます。
  保護された環境と新しいホストへの送信は、**確認**か**拒否**のどちらかだけです。
- **ホストと制限**：
  - **許可するホスト**：エージェントが送信してよいホスト。カンマまたはスペースで区切ります。
  - **1セッションあたりの送信数**：エージェントが1セッションで行える送信の上限。空欄は無制限です。
  - **1分あたりの送信数**：エージェントが1分間に行える送信の上限。空欄は無制限です。

より厳しいルールは常に適用されます。ファイルとともに届いた（チームメイトからGit経由などで）より緩いルールは、あなたが信頼するまでMacでは適用されません。
それまでは、エージェントポップオーバーに、ワークスペースのルールなら確認なしで許可される操作が表示されますが、エージェントは引き続き確認を求めます。
受け入れるには**これらのルールを信頼**を選びます。ワークスペース設定であなた自身が設定したルールは、信頼済みです。

## エージェントに渡らないもの [#what-agents-never-get]

- **シークレットの値。** Echolotは、エラーを含め、エージェントが受け取るすべての内容で、シークレットの値を置き換えます。プレーン、JSON、URLエンコード、
  Base64のいずれの形式でも同様です。エージェントに見えるのは、シークレット変数の名前だけです。
- **履歴内の認証情報。** 過去のやり取りは、認証情報のヘッダーをマスクし、通信のキャプチャを除いた状態でエージェントに渡されます。
- **他人のホストでのあなたのシークレット。** エージェントの送信が、ワークスペースで使っていないホストにリダイレクトされると、認証情報のヘッダーは
  その途中で破棄されます。

## 単独で動作する場合 [#on-its-own]

アプリでワークスペースが開いていない場合や `--headless` を指定した場合、`echolot mcp serve` がワークスペースを自分で提供し、ポリシーだけで判断します。

| `--policy` | 実行する操作 | 拒否する操作 |
| --- | --- | --- |
| `standard`（デフォルト） | 読み取りと安全な送信 | その他の送信、変更、削除、保護された環境、新しいホスト |
| `readonly` | 読み取り | すべての送信、変更、削除 |
| `permissive` | 読み取り、すべての送信、変更 | 削除、保護された環境、新しいホスト |

シークレットはこのMacのキーチェーンと `ECHOLOT_SECRET_…` 変数から解決され、エージェントに渡ることはありません。`--toolsets` はグループを指定します
（すべてを指定するには `all`）。`--env` は、環境を指定しない呼び出しが使う環境を指定します。`--http 0` は、標準入出力の代わりに、トークン付きの
Streamable HTTPを `127.0.0.1` で提供します。ワークスペース自身のルールはポリシーを厳しくします。`--trust-workspace-policy` を指定すると、ポリシーを緩めることも
できます。[`echolot mcp`](/docs/cli/mcp)を参照してください。

```sh
echolot mcp serve ~/Alpenglow.echolot --policy readonly --toolsets requests,history
```

## トラブルシューティング [#troubleshooting]

- **クライアントは接続されるが、確認が表示されず、変更が拒否される。** コマンドが単独で動作しています。Echolotでワークスペースを開き、
  **設定 › エージェント › 開いているワークスペースの使用をエージェントに許可**をオンにしてから、クライアントを接続し直してください。
- **クライアントにツールがまったく表示されない。** ワークスペース設定 › エージェントで**エージェントにこのワークスペースの使用を許可**がオフになっているか、
  エージェントポップオーバーでそのクライアントのスイッチをオフにしています。
- **エージェントに必要なツールがない。** **設定 › エージェント › エージェント用のツール**でそのツールセットをオンにし、クライアントを接続し直してください。
- **「Claudeに追加」が使えない。** このビルドにはコマンドラインツールが含まれていません。echolot.devのリリース版には含まれています。