@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/ja-JP/mcp-clients.md

@@ -0,0 +1,330 @@
+---
+title: "MCP クライアント"
+description: "エージェント ネイティブ アプリをローカル MCP サーバー (クロードインクローム、ファイルシステム、プレイライトなど) に接続して、エージェントがツールを入手できるようにします。"
+---
+
+# MCP クライアント
+
+**このページ: エージェントにさらに多くのツールを提供します。** ローカルまたはリモートの MCP サーバーにエージェント ネイティブ アプリを指定すると、そのツールがエージェント チャットに表示されます。これは _client_ 方向であり、[MCP Protocol](/docs/mcp-protocol) の鏡像です (アプリを MCP _server_ にします)。
+
+| もしご希望であれば…                                                          | 読む                                     |
+| ---------------------------------------------------------------------------- | ---------------------------------------- |
+| 外部エージェント/ホストをアプリに接続する                                    | [External Agents](/docs/external-agents) |
+| エージェントにさらに多くのツールを提供します (他の MCP サーバーを使用します) | **このページ** — MCP クライアント        |
+| Claude/ChatGPT でレンダリングするインライン UI を構築する                    | [MCP Apps](/docs/mcp-apps)               |
+| 下位レベルの MCP サーバー参照 (認証、ツール、カスタム マウント)              | [MCP Protocol](/docs/mcp-protocol)       |
+
+1 つの構成ファイルを使用すると、ワークスペース内のすべてのエージェント ネイティブ アプリが、マシン上の MCP サーバーによって提供されるツール (ブラウザ自動化用の `claude-in-chrome`、ファイル読み取り用の `@modelcontextprotocol/server-filesystem`、ブラウザ テスト用の `@playwright/mcp`、および MCP を話すその他のもの) にアクセスできるようになります。
+
+構成ファイルを編集せずに、個々のユーザーまたは組織全体で [connect remote (HTTP) MCP servers at runtime](#remote-via-ui) を実行することもできます。
+
+すべてのソースは 1 つのランタイム **MCP マネージャー**に解決され、学習したすべてのツールは、衝突防止の `mcp__<server-id>__<tool>` プレフィックスの下でエージェントのツール レジストリに配置されます。`tool-search` を通じて意図によって検索できます。
+
+```an-diagram title="Client direction: many sources, one tool registry" summary="Config files, env, and runtime UI all merge into the MCP manager; its tools appear prefixed and tool-searchable alongside your app's actions. This is the mirror of the server direction."
+{
+  "html": "<div class=\"mcp-merge\"><div class=\"diagram-col sources\"><div class=\"diagram-box\" data-rough>Workspace <code>mcp.config.json</code><br><small class=\"diagram-muted\">shared across apps</small></div><div class=\"diagram-box\" data-rough>App-root <code>mcp.config.json</code><br><small class=\"diagram-muted\">per-app override</small></div><div class=\"diagram-box\" data-rough><code>MCP_SERVERS</code> env<br><small class=\"diagram-muted\">CI / production</small></div><div class=\"diagram-box\" data-rough>Remote via settings UI<br><small class=\"diagram-muted\">personal &amp; org scope</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">MCP manager</span><small class=\"diagram-muted\">merge &middot; hot-reload</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col out\"><div class=\"diagram-node\">Agent tool registry<br><small class=\"diagram-muted\"><code>mcp__&lt;server-id&gt;__&lt;tool&gt;</code></small></div><div class=\"diagram-node\"><code>tool-search</code><br><small class=\"diagram-muted\">discover by intent</small></div></div></div>",
+  "css": ".mcp-merge{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.mcp-merge .diagram-col{display:flex;flex-direction:column;gap:8px}.mcp-merge .center{display:flex;flex-direction:column;align-items:center;gap:4px}.mcp-merge .diagram-arrow{font-size:22px;line-height:1}.mcp-merge code{font-size:.85em}"
+}
+```
+
+> 逆の方向 (_your_ アプリを他のホストが使用する MCP サーバーにする) は、[MCP Protocol](/docs/mcp-protocol) と [External Agents](/docs/external-agents) に存在します。
+
+## 内蔵ブラウザおよびコンピュータ使用機能 {#built-in-capabilities}
+
+エージェント ネイティブには、一般的な stdio MCP サーバー用のローカル開発切り替えが含まれています。
+デフォルトではオフになっており、ユーザーごとまたは組織ごとにのみ有効にできます
+アプリがローカルで実行されているとき。運用環境およびホスト型サーバーレス ランタイムはスキップ
+古い設定行が存在する場合でもこれらの組み込みとワークスペース リソース
+ツリーにはデフォルトの `mcp-servers/*.json` リソースとして表示されません。
+
+| 能力                      | サーバー ID       | コマンド                                                                |
+| ------------------------- | ----------------- | ----------------------------------------------------------------------- |
+| Chrome デベロッパーツール | `chrome-devtools` | `npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics` |
+| 劇作家ブラウザ            | `playwright`      | `npx -y @playwright/mcp@latest`                                         |
+| コンピュータの使用        | `computer-use`    | `npx -y computer-use-mcp@latest`                                        |
+
+スコープ内で一度に有効にできるブラウザ機能は 1 つだけです。 Chrome DevTools を有効にすると、同じユーザーまたは組織の Playwright が無効になり、Playwright を有効にすると Chrome DevTools が無効になります。
+
+コンピュータの使用は macOS のみです。他のプラットフォームでは、この設定は使用不可としてリストされ、古い設定行にその設定が含まれている場合でもスキップされます。
+
+Chrome DevTools はデフォルトで `--autoConnect` を使用します。これは、適格な実行中の Chrome インスタンスに接続されます。分離されたブラウザー プロファイルを作成したり、ユーザーの通常のプロファイルにサインインしたりすることはありません。リモート デバッグが有効になっている Chrome 144 以降が必要です。手動の `browser-url` 構成は、展開で特定のデバッグ エンドポイントが必要になったときに、後で追加できます。
+
+ビルトインは、個人切り替えの場合は `u:<email>:mcp-builtin-capabilities`、チーム切り替えの場合は `o:<orgId>:mcp-builtin-capabilities` の下にあるフレームワークの `settings` テーブルに保存されます。有効にすると、`mcp__user_<emailhash>_playwright__*` や `mcp__org_<orgId>_chrome-devtools__*` など、リモート サーバーと同じ範囲指定された可視性形式でランタイム MCP マネージャーにマージされます。
+
+### ユーザー向けのセットアップに関する注意事項
+
+機密性の高い組み込みには、簡潔で明示的なセットアップ コピーを使用します。
+
+- **Chrome DevTools** は、実行中の Chrome デバッグ ターゲットに接続します。ユーザーに伝える
+  これはブラウザのテストとログイン検証を目的としており、
+  ツールが表示される前に Chrome リモート デバッグを有効にする必要がある場合があります。
+- **Playwright** は分離されたブラウザを起動します。決定論的に推奨
+  ユーザーのライブ Chrome プロファイルが必要ない場合の QA。
+- **コンピュータ使用** はローカル アプリを操作できます。デフォルトではオフにしておきます。
+  macOS 画面録画とアクセシビリティ プロンプト、および撮影前に質問する
+  購入、財務上の変更、アカウントの変更などの機密性の高い actions。
+
+### 組み込みエンドポイント
+
+| メソッド | ルート                       | 目的                                                                                   |
+| -------- | ---------------------------- | -------------------------------------------------------------------------------------- |
+| GET      | `/_agent-native/mcp/builtin` | 組み込み機能、有効なスコープ、マージされた ID、およびライブ ステータスをリストします。 |
+| POST     | `/_agent-native/mcp/builtin` | スコープを更新します。本文: `{ scope, enabledIds }` または `{ scope, id, enabled }`。  |
+
+## ローカル MCP サーバーの追加 {#adding-a-server}
+
+ワークスペース ルート (または個々のアプリ ルート - 両方が存在する場合はワークスペース ルートが優先) で `mcp.config.json` を作成します。
+
+```jsonc
+{
+  "$schema": "https://agent-native.com/schema/mcp.config.json",
+  "servers": {
+    "claude-in-chrome": {
+      "command": "claude-in-chrome-mcp",
+      "args": [],
+      "env": { "LOG_LEVEL": "info" },
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"],
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem@latest",
+        "/Users/me/projects",
+      ],
+    },
+  },
+}
+```
+
+形状は小さく、サーバー ID をキーとする `servers` マップで、各エントリは標準入出力ランチャー (`command` + `args` + オプションの `env`) またはリモート `{ "type": "http", "url", "headers" }` エントリのいずれかです。
+
+```an-annotated-code title="mcp.config.json, annotated"
+{
+  "filename": "mcp.config.json",
+  "language": "jsonc",
+  "code": "{\n  \"$schema\": \"https://agent-native.com/schema/mcp.config.json\",\n  \"servers\": {\n    \"claude-in-chrome\": {\n      \"command\": \"claude-in-chrome-mcp\",\n      \"args\": [],\n      \"env\": { \"LOG_LEVEL\": \"info\" }\n    },\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-filesystem@latest\", \"/Users/me/projects\"]\n    }\n  }\n}",
+  "annotations": [
+    { "lines": "3", "label": "Server id", "note": "The key becomes the tool prefix: this server's tools surface as `mcp__claude-in-chrome__*` in the agent's registry, so they can't collide with your template's actions." },
+    { "lines": "4-6", "label": "stdio launcher", "note": "`command` + `args` spawn a local binary. Stdio servers are intended for **local development** — they are a no-op in edge runtimes." },
+    { "lines": "6", "label": "Process env", "note": "Optional `env` is passed to the spawned process. Keep secrets out of committed config; prefer `MCP_SERVERS` or the settings UI for tokens." }
+  ]
+}
+```
+
+次回アプリを起動すると、次のように表示されます。
+
+```
+[mcp-client] loaded config from /path/to/mcp.config.json (3 server(s))
+[mcp-client] connected to claude-in-chrome: 12 tools
+[mcp-client] connected to playwright: 9 tools
+[mcp-client] connected to filesystem: 4 tools
+```
+
+ツールは、プレフィックス `mcp__<server-id>__<tool-name>` を付けてエージェントのツール レジストリに登録されているため、テンプレートの actions と衝突することはありません。これらは `tool-search` にも含まれているため、エージェントは事前に正確な接頭辞付きの名前を必要とするのではなく、意図によって新しく接続された MCP 機能を検出できます。
+
+## 構成の優先順位 {#precedence}
+
+MCP 設定は次の順序で解決され、最初に一致したものが優先されます:
+
+1. **ワークスペース ルート `mcp.config.json`** — `package.json` の `agent-native.workspaceCore` 経由で検出されました。ワークスペース内のすべてのアプリ間で共有されます。
+2. **App-root `mcp.config.json`** — すべてのアプリで MCP サーバーを使用したくない場合は、アプリごとのオーバーライド。
+3. **`MCP_SERVERS` env var** — ファイルが意味をなさない CI/運用環境用の、同じ形状の JSON 文字列。
+
+## 本番デプロイ: `MCP_SERVERS` {#mcp-servers-env}
+
+実稼働デプロイの場合は、リモート HTTP MCP サーバーを優先し、完全な構成を設定します
+環境変数としての形状 (または内部サーバー マップ):
+
+```bash
+MCP_SERVERS='{"servers":{"zapier":{"type":"http","url":"https://mcp.example.com/mcp","headers":{"Authorization":"Bearer paste-token-value-here"}}}}'
+```
+
+`MCP_SERVERS` は JSON として解析されるため、`${...}` プレースホルダーは展開されません
+文字列内。トークンを別のシークレットに保存する場合は、
+最終的な JSON 値を書き込みます。
+
+Stdio MCP サーバーはローカル バイナリを生成し、ローカル開発を目的としています。
+MCP ツールはノード ランタイムでのみ有効になります — Cloudflare ワーカーおよびその他のエッジ
+ターゲットは MCP をサイレントにスキップし、残りのアプリの動作を続行します
+通常通りです。
+
+## 自動検出: `claude-in-chrome` {#autodetect}
+
+**no** `mcp.config.json` があり、`claude-in-chrome-mcp` バイナリが `PATH` (または既知のインストール場所 `~/.claude-in-chrome/bin/claude-in-chrome-mcp`) にある場合、エージェントネイティブはそれをデフォルトの MCP サーバーとして自動登録します。 `AGENT_NATIVE_DISABLE_MCP_AUTODETECT=1` をオプトアウトに設定します。
+
+これは、claude-in-chrome 拡張機能をインストールしたユーザーは、設定を変更することなく、開いたすべてのエージェント ネイティブ アプリにわたってブラウザー制御を取得できることを意味します。
+
+## 設定 UI によるリモート MCP サーバー {#remote-via-ui}
+
+MCP (モデル コンテキスト プロトコル) サーバーは、Zapier、Cloudflare、Composio、または会社の内部ツールへの接続など、エージェントに新しい機能を提供します。接続すると、エージェントはこれらのツールを組み込みツールと同じように使用できるようになります。
+
+### リモート MCP サーバーに接続する方法
+
+1. **サーバー名** — 独自の参照用の短いラベル (例: "zapier"、"slack-tools")。
+2. **URL** — MCP サーバープロバイダーから提供された HTTPS エンドポイント (例: `https://mcp.zapier.com/s/abc123/mcp`)。これは通常、プロバイダーのダッシュボードまたは統合ドキュメントに記載されています。
+3. **説明** (オプション) — このサーバーの動作に関するメモ。
+4. **Headers** — サーバーが必要とする認証資格情報 (1 行に 1 つ)。ほとんどのサーバーには `Authorization` ヘッダーが必要です。例: `Authorization: Bearer sk-your-key-here`。ここに何を入力するかについては、プロバイダのドキュメントを参照してください。
+
+保存する前に [**テスト**] をクリックして接続を確認します。成功すると、使用可能なツールの数が表示されます。 [**接続**] をクリックして追加します。
+
+### 個人と組織の範囲
+
+2 つのスコープがサポートされています:
+
+- **個人** — サインインしているユーザーのみがツールを取得します。ユーザースコープ設定として保存されます。
+- **チーム** — アクティブな組織の全員がツールを利用できます。所有者と管理者は追加できます。メンバーにはリストが読み取り専用で表示されます。組織スコープ設定として保存されます。
+
+実行中の MCP マネージャーにホットリロードを追加および削除します。プロセスの再起動やサーバーの再起動はありません。新しい `mcp__<scope>-<name>__*` ツールは次のメッセージでエージェントに表示され、`tool-search` 経由で検索できます。
+
+HTTPS URL はどこでも受け入れられます。プレーン `http://` は、開発中に `localhost` に対してのみ許可されます。オプションの認証は、リクエストごとに `Authorization: Bearer …` 経由で送信されるベアラー トークンとして入力されます。
+
+内部では、これらのサーバーはキー `u:<email>:mcp-servers-remote` (個人) または `o:<orgId>:mcp-servers-remote` (チーム) の下でフレームワークの `settings` テーブルに保存され、起動時に `mcp.config.json` とマージされます。
+
+### HTTP エンドポイント
+
+| メソッド | ルート                                                | 目的                                                                                  |
+| -------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| GET      | `/_agent-native/mcp/servers`                          | 現在のユーザーの個人サーバーと組織サーバーをライブ ステータスとともに一覧表示します。 |
+| POST     | `/_agent-native/mcp/servers`                          | サーバーを追加します。本文: `{ scope, name, url, headers?, description? }`。          |
+| DELETE   | `/_agent-native/mcp/servers/:id?scope=user\|org`      | Remove a server and reconfigure the manager.                                          |
+| POST     | `/_agent-native/mcp/servers/:id/test?scope=user\|org` | Dry-run the existing server's connect + list-tools.                                   |
+| POST     | `/_agent-native/mcp/servers/test`                     | 永続化する前に、任意の URL をドライランします。本文: `{ url, headers? }`。            |
+
+Stdio サーバーは Node ランタイム外では引き続き no-op ですが、リモート HTTP MCP サーバーは、デスクトップ実稼働ビルドを含む、`fetch` を備えたあらゆる環境で動作します。
+
+## ハブ経由で MCP サーバーを共有 {#hub}
+
+ワークスペースで複数のエージェント ネイティブ アプリ (ディスパッチ + メール + クリップなど) を実行している場合、**1 つ** のアプリをハブとして構成し、他のアプリがその組織スコープの MCP サーバーを自動的にプルするようにできます。 URL とベアラー トークンをアプリごとにコピーアンドペーストする必要はありません。ディスパッチ ワークスペース MCP リソースを使用した正規のアプローチについては、[Multi-App Workspace](/docs/multi-app-workspace) を参照してください。
+
+Dispatch は従来のハブであり、すでにアプリ間で調整されています。
+
+```an-diagram title="Hub model: one app serves org-scope MCP servers" summary="Dispatch holds the org-scope MCP servers; consumer apps pull and merge them as mcp__hub_<orgId>_<name>__*. Only org-scope rows are shared — personal credentials stay put."
+{
+  "html": "<div class=\"mcp-hub\"><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">Dispatch hub</span><small class=\"diagram-muted\">org-scope MCP servers</small><small class=\"diagram-muted\"><code>GET /mcp/hub/servers</code></small></div><div class=\"diagram-col arrows\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div></div><div class=\"diagram-col consumers\"><div class=\"diagram-box\" data-rough>Mail<br><small class=\"diagram-muted\"><code>mcp__hub_&lt;orgId&gt;_&lt;name&gt;__*</code></small></div><div class=\"diagram-box\" data-rough>Clips<br><small class=\"diagram-muted\">pull + merge each ~60s</small></div></div></div><p class=\"diagram-muted note\">Bearer-gated by <code>AGENT_NATIVE_MCP_HUB_TOKEN</code>. Personal (user-scope) servers are never re-exposed.</p>",
+  "css": ".mcp-hub{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.mcp-hub .center{display:flex;flex-direction:column;align-items:center;gap:4px}.mcp-hub .diagram-col{display:flex;flex-direction:column;gap:10px}.mcp-hub .arrows .diagram-arrow{font-size:22px;line-height:1}.mcp-hub .note{margin:8px 0 0;font-size:.85em}.mcp-hub code{font-size:.85em}"
+}
+```
+
+新しいワークスペースのセットアップの場合は、**ワークスペース MCP リソースをディスパッチする**ことを選択してください。
+ワークスペース skills で使用される同じすべてのアプリと選択されたアプリの付与モデルが必要です。
+説明書、および参照リソース。次のコマンドを使用してワークスペース リソースを追加します。
+
+```json
+{
+  "type": "http",
+  "url": "https://example.com/mcp",
+  "headers": {
+    "Authorization": "Bearer ${keys.MCP_SERVER_TOKEN}"
+  },
+  "description": "Shared MCP tools for workspace apps"
+}
+```
+
+種類 `mcp-server` で `mcp-servers/<name>.json` の下に保存します。すべてのアプリ
+リソースはすべてのワークスペース アプリによって読み込まれます。選択したリソースは
+アクティブなディスパッチ許可を持つアプリ。シークレット プレースホルダーはアプリから解決されます
+秘密ストアなので、生のベアラー トークンを Dispatch Vault に入れて参照します
+リソース本体に保存する代わりに、`${keys.NAME}` を使用します。
+
+アプリはマージされた MCP 構成を 1 分に 1 回程度更新するため、中央リソースが必要になります
+編集、変更の付与、および削除は、デプロイしなくても有効になります。セット
+`AGENT_NATIVE_MCP_CONFIG_REFRESH_MS=0` を使用してバックグラウンド更新を無効にするか、
+間隔を調整するには、少なくとも `5000` ミリ秒の値に設定します。
+
+以下の古いハブ モードは、大まかな「すべての組織スコープ MCP の共有」に引き続き役立ちます
+「Dispatch からのサーバー」セットアップおよびすでに MCP を使用している展開の場合
+真実の情報源として UI を設定します。
+
+### 1.ハブ アプリでハブ サーブを有効にする (ディスパッチ)
+
+ディスパッチのデプロイメントで環境変数を設定します:
+
+```bash
+AGENT_NATIVE_MCP_HUB_TOKEN=<a-long-random-secret>
+```
+
+Dispatch は `GET /_agent-native/mcp/hub/servers` をマウントするようになり、`settings` テーブルに格納されているすべての組織スコープの MCP サーバーを、トークンによって認証された完全な URL + ヘッダーとともに返します。
+
+### 2.ハブでのポイント消費アプリ
+
+すべてのコンシューマ (メール、クリップなど) に設定:
+
+```bash
+AGENT_NATIVE_MCP_HUB_URL=https://dispatch.acme.com
+AGENT_NATIVE_MCP_HUB_TOKEN=<the-same-secret>
+```
+
+起動時に、各コンシューマーはハブのサーバー リストを取得し、それを独自の MCP マネージャーにマージします。ツールはエージェントには `mcp__hub_<orgId>_<name>__*` として表示されます。これはコンシューマ自身のローカル `mcp__org_…` とは異なるため、衝突は発生しません。
+
+### 3.共有されるもの
+
+**org-scope** サーバーのみが共有されます。ユーザー スコープ (個人) サーバーは、サーバーを追加したユーザーとともにあり、ハブがアプリ間で個人認証情報を再公開することはありません。
+
+ハブの応答には、完全な認証ヘッダー (ベアラー トークンなど) が含まれます。トランスポートは HTTPS で、エンドポイントは共有シークレットを必要とし、組織スコープの行のみを返します。ハブ URL + トークンをデータベース認証情報のように扱います。
+
+### 4.ホットリロードと再起動
+
+ローカル UI は、`McpClientManager.reconfigure()` 経由で各アプリにホットリロードを追加します。再起動は必要ありません。ハブソースのサーバーは、ワークスペース リソース パスが使用するのと同じ定期的なバックグラウンド更新 (約 60 秒、`AGENT_NATIVE_MCP_CONFIG_REFRESH_MS` によって調整可能または無効化可能) によって選択されるため、Dispatch で行われた変更は、再起動せずに約 1 分以内にすべてのコンシューマー アプリに反映されます。さらに、コンシューマ アプリのローカルな変更が発生すると、そのアプリの再構成が即座にトリガーされます。
+
+### エンドポイントの概要
+
+| メソッド | ルート                           | 目的                                                                                                                                                   |
+| -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| GET      | `/_agent-native/mcp/hub/servers` | すべての組織スコープのサーバーを完全な認証情報で提供します (ベアラーゲート、`AGENT_NATIVE_MCP_HUB_TOKEN` が設定されている場合にのみマウントされます)。 |
+| GET      | `/_agent-native/mcp/hub/status`  | 設定 UI カードの `{ serving, consuming, hubUrl }` を返します。                                                                                         |
+
+## ステータスルート {#status-route}
+
+すべてのアプリはツールとオンボーディングのために `GET /_agent-native/mcp/status` を公開します:
+
+```an-api
+{
+  "method": "GET",
+  "path": "/_agent-native/mcp/status",
+  "summary": "MCP client status for tooling and onboarding",
+  "description": "Reports which configured servers connected, the total live tool count, the merged prefixed tool list, and any per-server connection errors. Use it to build \"detected — your agent can now drive X\" hints or to debug connection problems.",
+  "responses": [
+    {
+      "status": "200",
+      "description": "Configured vs connected servers, tool inventory, and per-server errors.",
+      "example": "{\n  \"configuredServers\": [\"claude-in-chrome\", \"playwright\"],\n  \"connectedServers\": [\"claude-in-chrome\", \"playwright\"],\n  \"totalTools\": 21,\n  \"tools\": [\n    {\n      \"source\": \"claude-in-chrome\",\n      \"name\": \"mcp__claude-in-chrome__navigate\",\n      \"description\": \"Navigate the browser to a URL\"\n    }\n  ],\n  \"errors\": {}\n}"
+    }
+  ]
+}
+```
+
+```json
+{
+  "configuredServers": ["claude-in-chrome", "playwright"],
+  "connectedServers": ["claude-in-chrome", "playwright"],
+  "totalTools": 21,
+  "tools": [
+    {
+      "source": "claude-in-chrome",
+      "name": "mcp__claude-in-chrome__navigate",
+      "description": "Navigate the browser to a URL"
+    }
+  ],
+  "errors": {}
+}
+```
+
+これを使用して、「claude-in-chrome が検出されました - エージェントは Chrome を操作できるようになりました」オンボーディング ヒントを作成したり、MCP 接続の問題をデバッグしたりできます。
+
+## 障害モード {#failures}
+
+個々の MCP サーバーの障害によってエージェントがダウンすることはありません:
+
+- `command` の設定が間違っている → サーバーはスキップされ、そのエラーは `errors.<server-id>` の下の `/mcp/status` に表示され、他のすべてのサーバーは引き続き動作します。
+- MCP SDK が `node_modules` にありません → すべての MCP 機能が警告とともにスキップされます。エージェント チャットは、MCP ツールを使用しなくても機能し続けます。
+- エッジ ランタイムで実行 → MCP クライアントは何もしません。
+
+エージェントネイティブは常に起動します。 MCP 構成が壊れているということは、ツールが少ないことを意味します。
+
+## セキュリティ {#security}
+
+MCP ツールは、生成されたプロセスが持つ権限を使用してマシン上で実行されます。 `mcp.config.json` は、エージェントに実行させたい他の実行可能ファイルのリストと同様に扱います。 MCP サーバーのツールは、テンプレート独自の actions と同様に、エージェントのツール使用ループに表示されるため、構成するすべてのサーバーを信頼していることを確認してください。

package/corpus/core/docs/content/locales/ja-JP/mcp-protocol.md

@@ -0,0 +1,279 @@
+---
+title: "MCP プロトコル"
+description: "エージェント ネイティブ アプリをリモート MCP サーバーとして公開すると、Claude、ChatGPT、Claude コード、カーソル、その他の AI ツールがアプリの actions を直接呼び出すことができます。"
+---
+
+# MCP プロトコル
+
+**このページ: 下位レベルの MCP サーバー リファレンス。** すべてのエージェント ネイティブ アプリが MCP 上で actions を公開する方法 (自動マウントされたエンドポイント、認証モード、`tools/call` / `ask-agent` サーフェス、カスタム マウント)。サーバーの内部情報が必要な場合は、それに手を伸ばしてください。ホストに接続するには、[External Agents](/docs/external-agents) から始めてください。
+
+| もしご希望であれば…                                                          | 読む                                     |
+| ---------------------------------------------------------------------------- | ---------------------------------------- |
+| 外部エージェント/ホストをアプリに接続する                                    | [External Agents](/docs/external-agents) |
+| エージェントにさらに多くのツールを提供します (他の MCP サーバーを使用します) | [MCP Clients](/docs/mcp-clients)         |
+| Claude/ChatGPT でレンダリングするインライン UI を構築する                    | [MCP Apps](/docs/mcp-apps)               |
+| 下位レベルの MCP サーバー参照 (認証、ツール、カスタム マウント)              | **このページ** — MCP プロトコル          |
+
+すべてのエージェント ネイティブ アプリはリモート MCP (モデル コンテキスト プロトコル) サーバーを自動的に公開するため、Claude、ChatGPT カスタム MCP アプリ、Claude コード、カーソル、Codex、VS コード GitHub Copilot などの外部 AI ツールは、アプリの actions を検出して直接呼び出すことができます。追加のコードが必要です。目的が、これらのホストの 1 つをホストされたアプリに「接続」することである場合、[External Agents](/docs/external-agents) は、推奨される単一のディスパッチ コネクタ、アプリごとの URL、OAuth、MCP アプリ インライン UI、およびディープ リンクをカバーします。このページには、その下にあるものについて説明します。
+
+## 概要 {#overview}
+
+MCP は、AI ツールを外部機能に接続するための標準プロトコルです。エージェント ネイティブ アプリをデプロイすると、既存の A2A エンドポイントと並んで MCP エンドポイントが自動的にマウントされます。 MCP 互換クライアントは、アプリのツールに接続して使用できます。
+
+重要な概念:
+
+- **自動マウント** — すべてのアプリは無料で `/_agent-native/mcp` を入手でき、セットアップは必要ありません
+- **ストリーミング可能な HTTP** — 標準の HTTP (POST + SSE) ではなく最新の MCP トランスポートを使用します
+- **同じ actions** — エージェント チャットと A2A を強化するまったく同じアクション レジストリ
+- **`ask-agent` ツール** — 複雑なタスクをエージェント ループ全体に委任するメタツール
+- **MCP アプリ** — actions は、公式 `io.modelcontextprotocol/ui` 拡張機能を通じてインタラクティブな UI リソースをアドバタイズできます
+- **標準リモート MCP OAuth** — OAuth 2.1 検出、動的クライアント登録、認可コード + PKCE、リフレッシュ トークン ローテーション
+- **ベアラー認証フォールバック** — OAuth を実行できないクライアントには、`ACCESS_TOKEN`、`ACCESS_TOKENS`、または接続ミント JWT を使用します
+
+```an-diagram title="Your app as an MCP server" summary="External hosts connect over Streamable HTTP. Each action is one tool; ask-agent delegates to the full agent loop."
+{
+  "html": "<div class=\"diagram-mcp\"><div class=\"diagram-col\"><div class=\"diagram-node\">Claude</div><div class=\"diagram-node\">ChatGPT</div><div class=\"diagram-node\">Cursor · Codex</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\"><span class=\"diagram-pill accent\">POST /_agent-native/mcp</span><small class=\"diagram-muted\">Streamable HTTP</small><small class=\"diagram-muted\">initialize &rarr; tools/list &rarr; tools/call</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\" data-rough>each action<br><small class=\"diagram-muted\">= one tool</small></div><div class=\"diagram-box\" data-rough>ask-agent<br><small class=\"diagram-muted\">&rarr; full agent loop</small></div></div></div>",
+  "css": ".diagram-mcp{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.diagram-mcp .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-mcp .diagram-panel{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-mcp .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+## MCP 対 A2A {#mcp-vs-a2a}
+
+両方のプロトコルは自動マウントされます。ユースケースに合ったものを使用してください:
+
+|                    | MCP                                                                                | A2A                                                  |
+| ------------------ | ---------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| **最適な用途**     | アプリを呼び出す外部ツール                                                         | エージェント間のコミュニケーション                   |
+| **プロトコル**     | MCP ストリーミング可能な HTTP                                                      | JSON-RPC 2.0                                         |
+| **ツールの発見**   | `tools/list`                                                                       | `/.well-known/agent-card.json` のエージェント カード |
+| **エンドポイント** | `/_agent-native/mcp`                                                               | `/_agent-native/a2a`                                 |
+| **サポート対象**   | Claude、ChatGPT、Claude コード、カーソル、Codex、Cowork、およびその他の MCP ホスト | その他のエージェントネイティブ アプリ                |
+| **実行**           | 直接ツール呼び出し (追加の LLM なし)                                               | 完全なエージェント ループ (LLM 推論)                 |
+
+`ask-agent` MCP ツールを使用して、両方の長所を活用することもできます。Claude コードから呼び出して、アプリのエージェントに複雑なタスクを推論させます。
+
+## 手動 MCP クライアント構成 {#manual-config}
+
+推奨される 1 つのコマンド セットアップでは、[External Agents](/docs/external-agents) を使用します。 OAuth 対応クライアントの MCP 構成を手書きしている場合は、静的ヘッダーのないリモート MCP サーバーとしてアプリを追加します。
+
+```bash
+claude mcp add --transport http mail https://mail.example.com/_agent-native/mcp
+```
+
+または、`.mcp.json` (プロジェクト スコープ) または `~/.claude.json` (ユーザー スコープ) にエントリを手動で書き込みます。
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "mail": {
+      "type": "http",
+      "url": "https://mail.example.com/_agent-native/mcp",
+    },
+  },
+}
+```
+
+次に、Claude コードで `/mcp` を実行し、**認証** を選択します。リモート MCP OAuth を実行できないクライアントの場合は、[接続] ページまたは `headers.Authorization` の静的ベアラー トークン エントリを使用します。認証されると、アプリのツールを自然に使用できるようになります。
+
+```
+> draft an email to John about the Q3 report
+
+Claude Code calls: draft-email(to: "john@example.com", subject: "Q3 Report", body: "...")
+```
+
+## 他の MCP クライアントからの接続 {#other-clients}
+
+ストリーミング可能な HTTP トランスポートをサポートするすべての MCP クライアントが接続できます。エンドポイントは次のとおりです:
+
+```
+POST https://your-app.example.com/_agent-native/mcp
+```
+
+サーバーは、標準の MCP ハンドシェイク: `initialize` → `initialized` → `tools/list` → `tools/call` をサポートします。
+
+```an-api title="MCP endpoint" summary="The auto-mounted Streamable HTTP endpoint every agent-native app exposes."
+{
+  "method": "POST",
+  "path": "/_agent-native/mcp",
+  "summary": "MCP Streamable HTTP endpoint",
+  "description": "Auto-mounted on every app. Speaks the standard MCP handshake (`initialize` → `initialized` → `tools/list` → `tools/call`) plus `resources/list`, `resources/templates/list`, and `resources/read` when an action declares `mcpApp`. Each action maps to one tool; `ask-agent` delegates to the full agent loop.",
+  "auth": "Standard remote MCP OAuth (Bearer access token), connect-minted JWT, or static ACCESS_TOKEN/ACCESS_TOKENS",
+  "params": [
+    { "name": "Authorization", "in": "header", "type": "string", "required": false, "description": "Bearer access token. Required except for loopback local-dev probes." },
+    { "name": "method", "in": "body", "type": "string", "required": true, "description": "MCP method, e.g. initialize, tools/list, tools/call." }
+  ],
+  "request": {
+    "contentType": "application/json",
+    "example": "{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"ask-agent\",\n    \"arguments\": { \"message\": \"Summarize Q3 signups by source\" }\n  }\n}"
+  },
+  "responses": [
+    { "status": "200", "description": "MCP result (POST + SSE)." },
+    { "status": "401", "description": "Unauthenticated — responds with a WWW-Authenticate header pointing at OAuth discovery." }
+  ]
+}
+```
+
+アクションが `mcpApp` を宣言する場合、サーバーは公式の MCP アプリ拡張機能 (`io.modelcontextprotocol/ui`) もアドバタイズし、アプリ リソースの `resources/list`、`resources/templates/list`、および `resources/read` をサポートします。 MCP アプリをレンダリングするホストは、UI をインラインで表示できます。そうでないホストでもツールを呼び出してディープリンク フォールバックを使用できます。製品 UI は、`embedApp()` を使用する必要があります。これにより、インライン サーフェスは、別のプレーン HTML 実装ではなく、実際の React アプリ ルート、または分析チャートなどの共有 React コンポーネントをレンダリングする焦点の高いルートになります。サーバーは標準の MCP アプリ メタデータと ChatGPT アプリ SDK 互換性メタデータの両方を発行するため、アプリ対応ホストは同じ `ui://` リソースを見つけることができます。現在の公式拡張機能マトリックスには、Claude、Claude デスクトップ、VS Code GitHub Copilot、Goose、Postman、MCPJam、ChatGPT、および Cursor が含まれています。ホストのサポートはバージョンやプランによって異なるため、ユーザー向けのガイダンスとして [External Agents MCP Apps notes](/docs/external-agents#mcp-apps-compatibility) を使用してください。
+
+### MCP アプリ埋め込みブリッジ {#mcp-app-embed-bridge}
+
+`embedApp()` は、低レベルの URL-first MCP アプリ ヘルパーです。署名されたアプリを起動します
+移植 (Claude)、制御フレーム (ChatGPT)、または直接経由のインライン ルート
+ナビゲーション、`ui/*` JSON-RPC ブリッジ (および
+制御フレーム パスの `agentNative.mcpHost.*` postMessage リレー)、および
+フルアプリのルートがレンダリングされないようにリソース シェルの高さを固定します
+特大のチャット アーティファクト。
+
+埋め込みブリッジの完全な詳細については、[MCP Apps](/docs/mcp-apps#mcp-app-bridge) を参照してください。移植と制御フレーム、`ui/*` と postMessage テーブル、`create_embed_session` / `embedStartUrl`、CSP とドメイン ルール、拡張機能 `srcDoc` 埋め込み、高さクランプ、およびホスト ブリッジ クライアント API。
+
+## ツール {#tools}
+
+すべての呼び出し元は、**デフォルトでコンパクトなカタログ** (テンプレートで宣言されたアプリ actions とクロスアプリの組み込み) を取得します。完全なアクション サーフェスは明示的なオプトインでのみ提供され、`tool-search` は残りの部分に常にアクセスできます。完全な説明については、[External Agents → Catalog tiers](/docs/external-agents#catalog-tiers) を参照してください。
+
+各アクションは 1 つの MCP ツールに直接マッピングされます:
+
+| アクションプロパティ | MCP ツール プロパティ |
+| -------------------- | --------------------- |
+| `tool.description`   | `description`         |
+| `tool.parameters`    | `inputSchema`         |
+| アクション名         | ツール名              |
+
+`mcpApp` が存在する場合、ツール エントリには `_meta.ui.resourceUri`、`_meta["ui/resourceUri"]`、および `_meta["openai/outputTemplate"]` も含まれ、対応する `ui://` リソースは `text/html;profile=mcp-app` として返されます。
+
+### `ask-agent` ツール {#ask-agent}
+
+個々のアクション ツールに加えて、すべての MCP サーバーには `ask-agent` メタツールが含まれています。これにより、アプリの AI エージェントに自然言語メッセージが送信され、応答が返されます。
+
+エージェントの推論とコンテキストから恩恵を受ける複雑なタスクには、`ask-agent` を使用します。
+
+```json
+{
+  "name": "ask-agent",
+  "arguments": {
+    "message": "Draft a follow-up email to the Q3 planning thread with John, summarizing the action items we discussed"
+  }
+}
+```
+
+エージェントは対話型チャットと同じループを実行します。エージェントは複数のツールを呼び出し、コンテキストを推論し、思慮深い応答を生成できます。
+
+## 認証 {#authentication}
+
+MCP エンドポイントは、標準のリモート MCP OAuth に加えて、既存のベアラー トークン フォールバックをサポートします。
+
+| モード                         | 仕組み                                                                                                                         |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| 標準 MCP OAuth                 | クライアントは `WWW-Authenticate` から認証を検出し、登録し、PKCE を実行し、`Authorization: Bearer <access-token>` を送信します |
+| コネクトミント JWT             | `npx @agent-native/core@latest connect` / 接続ページはユーザーごとに取り消し可能な JWT を作成します                            |
+| `ACCESS_TOKEN`                 | 静的ベアラー トークン — クライアントが `Authorization: Bearer <token>` を送信                                                  |
+| `ACCESS_TOKENS`                | 有効な静的ベアラー トークンのカンマ区切りリスト                                                                                |
+| `A2A_SECRET`                   | JWT ベースの認証 — トークンは暗号的に検証されます                                                                              |
+| _(設定なし、ループバックのみ)_ | ローカル開発プローブには認証は必要ありません                                                                                   |
+
+OAuth 対応の MCP ホストの場合は、静的ヘッダーなしでリモート サーバー URL を構成します。
+
+```bash
+claude mcp add --transport http agent-native https://dispatch.agent-native.com/_agent-native/mcp
+```
+
+最初の未認証の MCP リクエストは以下を受け取ります。
+
+```http
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: Bearer resource_metadata="https://dispatch.agent-native.com/.well-known/oauth-protected-resource", scope="mcp:read mcp:write mcp:apps"
+```
+
+検出エンドポイント:
+
+| エンドポイント                            | 目的                                    |
+| ----------------------------------------- | --------------------------------------- |
+| `/.well-known/oauth-protected-resource`   | RFC 9728 保護されたリソースのメタデータ |
+| `/.well-known/oauth-authorization-server` | OAuth 認可サーバーのメタデータ          |
+| `/_agent-native/mcp/oauth/register`       | 動的パブリッククライアント登録          |
+| `/_agent-native/mcp/oauth/authorize`      | ブラウザの承認 + 同意                   |
+| `/_agent-native/mcp/oauth/token`          | 認可コードとリフレッシュトークンの付与  |
+
+```an-diagram title="OAuth discovery flow" summary="A 401 kicks off discovery, registration, and a PKCE authorize → token exchange. The Bearer token is audience-bound and scoped."
+{
+  "html": "<div class=\"diagram-oauth\"><div class=\"diagram-box\" data-rough>first request<br><small class=\"diagram-muted\">no token</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill warn\">401 · WWW-Authenticate</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\"><span class=\"diagram-pill\">/.well-known/oauth-protected-resource</span><span class=\"diagram-pill\">/.well-known/oauth-authorization-server</span><small class=\"diagram-muted\">discover</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-pill\">register</div><div class=\"diagram-pill\">authorize (PKCE)</div><div class=\"diagram-pill\">token</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Bearer access token<br><small class=\"diagram-muted\">audience-bound · mcp:read / write / apps</small></div></div>",
+  "css": ".diagram-oauth{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-oauth .diagram-panel{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-oauth .diagram-col{display:flex;flex-direction:column;gap:6px}.diagram-oauth .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+アクセス トークンは、対象者が正確な MCP リソース URL である署名付き JWT です。サーバーは、サーバー自体に対して発行されたトークンのみを受け入れ、ツールをリストしたり呼び出したりする前にスコープを適用します。
+
+| 範囲        | 許可                                        |
+| ----------- | ------------------------------------------- |
+| `mcp:read`  | 読み取り専用 actions                        |
+| `mcp:write` | actions と `ask-agent` を変更します         |
+| `mcp:apps`  | MCP アプリ リソース (`ui://` HTML リソース) |
+
+リフレッシュ トークンはハッシュとしてのみ保存され、リフレッシュのたびにローテーションされます。 `npx @agent-native/core@latest connect` は、デフォルトで、Claude コード クライアントに対してこの URL 専用の OAuth エントリを書き込みます。接続ページ、`npx @agent-native/core@latest connect --token <token>`、ローカル stdio プロキシ、古いクライアント、緊急/デバッグ フロー用の静的ベアラー設定を保持します。
+
+## カスタム MCP セットアップ {#custom-setup}
+
+MCP サーバーは、エージェント チャット プラグインによって自動マウントされます。ほとんどのアプリでは、構成は必要ありません。カスタム動作が必要な場合は、サーバー プラグインで手動でマウントできます。
+
+```ts
+// server/plugins/mcp.ts
+import { mountMCP } from "@agent-native/core/mcp";
+import { autoDiscoverActions } from "@agent-native/core/server";
+
+export default defineNitroPlugin(async (nitro) => {
+  const actions = await autoDiscoverActions(import.meta.url);
+
+  mountMCP(nitro, {
+    name: "My App",
+    description: "Custom MCP server",
+    actions,
+    // Optional: provide ask-agent handler
+    askAgent: async (message) => {
+      // Your custom agent logic
+      return "Response";
+    },
+    // Optional: override the route prefix (default "/_agent-native")
+    // routePrefix: "/_agent-native",
+  });
+});
+```
+
+## 例: Claude コードからの分析 {#example}
+
+`analytics.example.com` に分析アプリがデプロイされています。 Claude コードから:
+
+```bash
+claude mcp add --transport http analytics https://analytics.example.com/_agent-native/mcp
+```
+
+または、`.mcp.json` に手動で追加します。
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "analytics": {
+      "type": "http",
+      "url": "https://analytics.example.com/_agent-native/mcp",
+    },
+  },
+}
+```
+
+Claude コードでは次のようになります。
+
+```
+> How many signups did we get last week?
+
+Claude Code calls: run-query(sql: "SELECT count(*) FROM signups WHERE created_at > now() - interval '7 days'")
+→ "1,247 signups last week"
+```
+
+より複雑な分析の場合:
+
+```
+> Ask the analytics agent to prepare a full breakdown of Q3 signups by source, with trends
+
+Claude Code calls: ask-agent(message: "Prepare a full breakdown of Q3 signups by source, with trends")
+→ The analytics agent runs multiple queries, reasons about the data, and returns a formatted report
+```