@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ja-JP/external-agents.md

@@ -0,0 +1,619 @@
+---
+title: "外部エージェント: Claude、ChatGPT、Codex、カーソル、Cowork"
+description: "Claude、ChatGPT、Codex、Cursor、Claude Cowork、または MCP 互換ホストをホストされたエージェント ネイティブ アプリに接続し、MCP アプリとディープ リンクを使用してアーティファクトを実行中の UI に往復させます。"
+search: "Claude ChatGPT Claude コード Codex カーソル Claude Cowork MCP アプリ エージェントネイティブ接続 ローカル エージェント ツール 外部エージェント"
+---
+
+# 外部エージェント
+
+**このページ: 外部エージェントまたは MCP ホストをアプリに接続します。** Claude、ChatGPT、Codex、Cursor、Claude Cowork、または別の MCP 互換ホストがホストされたエージェント ネイティブ アプリを駆動し、結果を実行中の UI にラウンドトリップする必要がある場合に使用します。
+
+| もしご希望であれば…                                                          | 読む                               |
+| ---------------------------------------------------------------------------- | ---------------------------------- |
+| 外部エージェント/ホストをアプリに接続する                                    | **このページ** — 外部エージェント  |
+| エージェントにさらに多くのツールを提供します (他の MCP サーバーを使用します) | [MCP Clients](/docs/mcp-clients)   |
+| Claude/ChatGPT でレンダリングするインライン UI を構築する                    | [MCP Apps](/docs/mcp-apps)         |
+| 下位レベルの MCP サーバー参照 (認証、ツール、カスタム マウント)              | [MCP Protocol](/docs/mcp-protocol) |
+
+エージェント ネイティブ アプリは、MCP 互換ホスト (Claude、Claude デスクトップ、Claude コード、ChatGPT カスタム MCP アプリ、Codex、カーソル、Claude Cowork、VS Code GitHub Copilot、Goose、Postman、 MCPJam、および標準を実装する将来のクライアント。外部エージェントは成果物 (ドラフト、イベント、ダッシュボード) の生成に優れていますが、多くの場合、端末または別のアプリ内に存在します。橋がないと、ユーザーは JSON の壁に直面し、それを探しに行かなければなりません。
+
+外部エージェント ブリッジがループを閉じます。まず、アプリのリモート MCP URL を Claude や ChatGPT などのチャット ホストに貼り付けるか、ローカル コーディング エージェントの開発者 CLI フローを実行することによって、独自のエージェントを **ホストされている** アプリに接続します。次に、エージェントは MCP を介して作業を実行し、互換性のあるホストのインライン **MCP アプリ** UI または、作成されたものに焦点を合わせた実際のアプリを開く単一の **「<アプリ> で開く →」** リンクのいずれかをユーザーに渡します。既存の `navigate` / `application_state` コントラクトを再利用します。UI はすでに 2 秒ごとに排出しています ([Context Awareness](/docs/context-awareness) を参照)。2 番目のナビゲーション メカニズムはありません。
+
+```an-diagram title="The external-agent round-trip" summary="An external host calls a tool over MCP; the app returns an artifact plus an Open link. Clicking it resolves the browser session and focuses the artifact in the running UI — the link carries no privileged state."
+{
+  "html": "<div class=\"xa-trip\"><div class=\"diagram-box\" data-rough>External host<br><small class=\"diagram-muted\">Claude &middot; ChatGPT &middot; Codex &middot; Cursor</small></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 tool call</span><small class=\"diagram-muted\">e.g. <code>manage-draft</code></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>App produces artifact<br><small class=\"diagram-muted\">+ <code>Open in &lt;app&gt; &rarr;</code> deep link / MCP App</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>User clicks link</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill ok\"><code>/_agent-native/open</code></span><small class=\"diagram-muted\">resolves the <strong>browser</strong> session</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Writes <code>navigate</code> app-state<br><small class=\"diagram-muted\">UI focuses the artifact</small></div></div>",
+  "css": ".xa-trip{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.xa-trip .center{display:flex;flex-direction:column;align-items:center;gap:4px}.xa-trip .diagram-arrow{font-size:22px;line-height:1}.xa-trip code{font-size:.85em}"
+}
+```
+
+アイデンティティ ルールは安全ヒンジです。リンクは単なる `view` + レコード ID + フィルターであり、レコードに焦点を当てた `navigate` 書き込みのスコープは **ブラウザ** にログインしているユーザーに限定されます。外部エージェントの MCP トークンではありません。このため、リンクを端末やチャットの記録に安全に貼り付けることができます。
+
+## どのエージェント パスが必要ですか? {#which-agent-path}
+
+- **外部 MCP ホスト:** Claude、ChatGPT、Codex、Cursor、OpenCode、GitHub Copilot / VS Code、または別の MCP 互換ホストがホストされたエージェント ネイティブ アプリを呼び出す必要がある場合は、このページを使用します。
+- **Agent-Native チャットの背後にある独自のランタイム:** 別のフレームワークで構築されたエージェントが `<AssistantChat runtime={...}>` を強化する必要がある場合は、[Agent Surfaces](/docs/agent-surfaces#byo-agent) および [Native Chat UI](/docs/native-chat-ui#byo-agent-runtimes) を参照してください。
+- **MCP ツールを使用するアプリ:** エージェント ネイティブ アプリが別の MCP サーバーによって公開されているツールを呼び出す必要がある場合は、[MCP Clients](/docs/mcp-clients) を参照してください。
+- **A2A 経由の別のアプリまたはエージェント:** エージェント ネイティブ アプリが相互に検出して委任する必要がある場合は、[Agent Mentions](/docs/agent-mentions) と [A2A](/docs/a2a-protocol) を使用します。
+- **ローカル カスタム サブエージェント:** エージェント ネイティブ ワークスペース自体内にカスタム エージェント プロファイルが必要な場合は、[Workspace](/docs/workspace) を使用します。
+
+## 簡単なセットアップ {#easy-setup}
+
+Agent-Native を使用するホストにリモート MCP コネクタを 1 つ追加します。
+
+ワークスペースまたはクロスアプリ作業の場合は、Dispatch を使用します。
+
+```text
+https://dispatch.agent-native.com/_agent-native/mcp
+```
+
+Dispatch は、メール、カレンダー、分析、脳、そしてあなたの
+ワークスペース アプリ。 Dispatch の **エージェント** ページで、ゲートウェイができるかどうかを選択します。
+すべてのアプリまたは選択したアプリのみにアクセスします。接続されたホストは
+`list_apps`、`ask_app`、および `open_app`、その許可されたセットにフィルタリングされます。
+
+意図的に分離された 1 つのアプリの場合、そのアプリを直接使用します。
+
+```text
+https://mail.agent-native.com/_agent-native/mcp
+https://<your-app>.agent-native.com/_agent-native/mcp
+```
+
+ホストされているすべてのアプリには、ヘルパー ページもあります
+`https://<app>/_agent-native/mcp/connect` とコピー可能な URL および
+Claude、ChatGPT、カーソル、Claude コード、Codex、その他のホスト固有のタブ。
+
+### Claude および ChatGPT OAuth {#oauth}
+
+Claude / Claude デスクトップ: カスタム コネクタを追加し、MCP URL を貼り付け、クリックします
+**接続**、Agent-Native アカウントでサインインし、MCP スコープを承認します。
+チャットでコネクタを有効にします。 Claude コードは同じ URL を使用します。
+リモート HTTP MCP サーバーで、`/mcp` を実行し、**認証** を選択します。
+
+ChatGPT: カスタム MCP コネクタまたは開発者モード アプリが存在するワークスペースを使用します
+有効、カスタム コネクタ/アプリを作成し、同じ MCP URL を貼り付け、OAuth を選択します。
+ツールのスキャン/検出、Agent-Native でのサインイン、スコープの承認、有効化
+チャットのコネクタ。
+
+OAuth 権限はホストごと、ユーザーごとに付与されます。ホストはトークンを保存し、
+ツール/リソース呼び出しを仲介するため、インライン MCP アプリ プレビューは生のデータを受信することはありません
+OAuth トークン。 ChatGPT は、レビューまたは公開されたコネクタのツールを保持できます
+スナップショットは再度更新/確認するまで保存されるため、MCP の後にコネクタを再スキャンしてください
+ツールまたは MCP アプリのメタデータが変更されます。古いアプリごとのコネクタがまだある場合
+各古いコネクタのディスパッチ、リフレッシュ、または再接続とともに有効になります。更新中
+Dispatch は、ChatGPT または Claude のキャッシュされたカレンダー/メールなどを書き換えません。
+スナップショット。スコープは次のとおりです:
+
+| スコープ    | それによって何が可能になるか                                         |
+| ----------- | -------------------------------------------------------------------- |
+| `mcp:read`  | 読み取り専用ツールとツール/リソースの検出                            |
+| `mcp:write` | ドラフト、更新、その他の変更中の actions                             |
+| `mcp:apps`  | インライン MCP アプリ、チャート、ダッシュボード、ドラフト、および UI |
+
+Cursor、Goose、Postman、MCPJam、VS Code GitHub Copilot は同じリモートを使用します
+ビルドがリモート OAuth をサポートしている場合、独自の MCP サーバー UI を介した MCP URL
+MCP サーバー。
+
+### クイック テスト プロンプト {#quick-test}
+
+接続後、次のいずれかを試してください:
+
+```text
+Use Agent-Native Analytics to generate a weekly conversion-rate bar chart and show it inline.
+```
+
+```text
+Use Agent-Native Mail to draft a short follow-up email to me, but do not send it.
+```
+
+MCP アプリをサポートするホストでは、Analytics は実際のダッシュボードと分析ルートをインラインでレンダリングでき、メールはドラフト レビュー用に実際の構成 UI をインラインでレンダリングできます。 MCP アプリをレンダリングしないホストでは、同じツール呼び出しで **メールで下書きを開く→** または **アナリティクスでダッシュボードを開く→** などのディープ リンクが返されます。
+
+## 高度な設定: ローカル エージェント {#connect}
+
+マシン上のローカル エージェント クライアント (Claude コード、Claude コード CLI、Codex、Claude Cowork、Cursor、OpenCode、および GitHub Copilot / VS Code) に対してこのフローを使用します。カーソルおよび他の OAuth ネイティブ クライアントは、UI がリモート MCP OAuth をサポートしている場合、上記の貼り付け URL フローを使用することもできます。
+
+npm を通じて接続コマンドを実行します。
+
+```bash
+npx @agent-native/core@latest connect https://dispatch.agent-native.com
+```
+
+コマンドは、どのローカル エージェント クライアントが MCP 構成を受信するかを尋ねます。すべてのクライアントは最初に事前に選択されます。選択すると、選択内容は `~/.agent-native/connect.json` に保存されるため、次回の実行で Enter キーを押して再利用したり、チェックした項目を編集したりできます。
+
+Claude コード、Claude コード CLI、カーソル、OpenCode、および GitHub コパイロット / VS コードの場合、`connect` は静的ヘッダーのない標準リモート HTTP MCP エントリを書き込みます。クライアントを再起動し、プロンプトが表示されたら、その MCP UI から認証します。 Codex および Claude Cowork の場合、`connect` は互換性のあるデバイス コード フローを使用します。アプリでブラウザーが開き、[**承認**] を 1 回クリックすると、コマンドがスコープ付きベアラー トークン エントリを書き込みます。クライアントの組み合わせを選択すると、両方が実行されます。
+
+ブラウザの承認が完了するまで、`connect` コマンドを実行し続けます。もし
+待機プロセスは早期に停止され、ブラウザでは承認は成功しますが、
+ローカル クライアント構成はトークンを受信しません。
+
+以前に古いベアラー トークン フローを通じて Claude コードを接続した場合は、同じ `npx @agent-native/core@latest connect ... --client claude-code` コマンドを再度実行するだけです。 CLI は、従来の `Authorization` ヘッダーを URL 専用の OAuth エントリに置き換え、`/mcp` から再認証するように指示します。
+
+| ローカルクライアント              | `connect` によって書き込まれた構成                        | 認証フロー                                   |
+| --------------------------------- | --------------------------------------------------------- | -------------------------------------------- |
+| Claude コード / Claude コード CLI | `.mcp.json` または `~/.claude.json`、`--scope` に応じて   | Claude の `/mcp` UI の標準リモート MCP OAuth |
+| カーソル                          | `.cursor/mcp.json` または `~/.cursor/mcp.json`            | カーソルの MCP UI 内の標準リモート MCP OAuth |
+| オープンコード                    | `opencode.json` または `~/.config/opencode/opencode.json` | OpenCode の MCP UI の標準リモート MCP OAuth  |
+| GitHub コパイロット / VS コード   | `.vscode/mcp.json` または VS Code ユーザー MCP 構成       | VS コードの MCP UI の標準リモート MCP OAuth  |
+| Codex                             | `$CODEX_HOME/config.toml` または `~/.codex/config.toml`   | ブラウザ承認ベアラー フォールバック          |
+| Claude コワーク                   | Claude コード MCP シェイプを使用した `~/.cowork/mcp.json` | ブラウザ承認ベアラー フォールバック          |
+
+接続後にエージェント クライアントを再起動し、新しい MCP サーバーを選択します。 OAuth ネイティブ クライアントは、MCP UI からの認証を求めるプロンプトを表示する場合があります。
+
+ローカルの MCP 構成のトラブルシューティングを行う場合は、`Authorization`、`http_headers` を編集してください。
+ログを共有する前のトークン値。生のカールを
+ホスト MCP セッション;接続後、ホスト公開ツールを使用するか、
+新しいサーバーがまだ表示されていない場合はクライアント。
+
+スクリプトまたは 1 回限りのインストールのピッカーをスキップするには、`--client codex` (または `--client claude-code`、`--client claude-code-cli`、`--client cursor`、`--client opencode`、`--client github-copilot`、`--client cowork`、`--client all`) を使用します。
+
+ファーストパーティ アプリ skills は、手順とホストされている MCP コネクタを Agent Native CLI とともにインストールします。
+
+```bash
+npx @agent-native/core@latest skills add assets              # alias: image-generation
+```
+
+移植性のみが必要な場合は、Vercel/open Skills CLI パスも使用できます
+手順:
+
+```bash
+npx skills@latest add BuilderIO/agent-native --skill assets
+```
+
+生の `skills` CLI は、`SKILL.md` ファイルのみをインストールします。ローカル MCP クライアントはまだ
+`npx @agent-native/core@latest connect https://assets.agent-native.com` などのコネクタが必要です。
+
+| スキル   | エイリアス         | 対象              |
+| -------- | ------------------ | ----------------- |
+| `assets` | `image-generation` | 画像/ビデオの生成 |
+
+デフォルトのクライアント選択は、サポートされているすべてのローカル クライアントです。 `--client codex`、`--client claude-code`、または別の特定のターゲットを追加してセットアップを絞り込みます。インライン ホスト (ChatGPT、Claude.ai、Claude デスクトップ メイン チャット) は、チャットでピッカー/バリアント グリッドをレンダリングします。 CLI/リンク専用ホスト (Codex、Claude コード、Claude デスクトップの「コード」タブ) は、ユーザーがブラウザーで選択してハンドオフの概要を貼り付ける「…で開く →」リンクを返します。
+
+Dispatch のワークスペース ゲートウェイの代わりに分離されたアプリが本当に必要な場合
+そのアプリのホストで同じコマンドを実行します:
+
+```bash
+npx @agent-native/core@latest connect https://mail.agent-native.com
+```
+
+`connect --all` は従来のアプリごとのクライアント設定用にまだ存在しますが、新しい
+ワークスペースのセットアップでは、単一のディスパッチ コネクタを優先する必要があります。
+
+接続は **ユーザーごと、スコープ指定され、取り消し可能**です。 OAuth パスでは、ホストは `/mcp` 認証後にトークンを保存します。フォールバック パスでは、認証したブラウザ セッションがエージェントとして機能する ID になります。デプロイメントの共有秘密を公開するものは何もありません。
+
+### 401 後の再認証 {#reconnect}
+
+一度接続すると、認証は長期間持続する必要があります。アクセス トークンはデフォルトで 30 日間持続し (サーバー上の `MCP_OAUTH_ACCESS_TOKEN_TTL`、例: `7d` または `12h`)、スライド式の 365 日更新ウィンドウがあるため、ランダムな 401 はまれになるはずです。この問題が発生した場合は、再インストールするのではなく、軽量の再接続コマンドを使用してください。
+
+```bash
+npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex
+```
+
+`reconnect` は、指定されたホストおよび選択されたクライアント (コネクタ名に関係なく、URL で一致) について、URL が `/_agent-native/mcp` で終わる MCP 構成エントリを検索し、インストールされている skills に手を触れたり、完全なインストール フローを再実行したりすることなく、認証マテリアルを更新または置換します。ベースアプリ URL (例: `https://plan.agent-native.com`) を渡します — `/_agent-native/mcp` サフィックスが推測されます。認証とツールの読み込みはクライアントごとに行われるため、後でそのクライアントを再起動/再読み込みします。 Codex は、新しくロードされたツールが表示される前に、新しいセッションが必要です。
+
+Claude コードでは、同等の UI パスは次のとおりです: `/mcp` を実行し、関連するコネクタに対して **認証** (または **再接続**) を選択します。
+
+401 を修正するためだけにスキルを最初から再インストールしないでください。`reconnect` が適切なツールです。
+
+### ページのフォールバック接続 {#connect-page-fallback}
+
+リモート OAuth URL を直接追加できない MCP クライアントの場合は、ブラウザでアプリを開いて、**接続** アフォーダンス (`https://<app>/_agent-native/mcp/connect` で提供) を使用します。ログインした状態で、**接続 / 認証** をクリックします。このページでは、検出されたエージェントを構成するワンクリックのディープ リンク、またはすぐに貼り付けられる `.mcp.json` ブロックのいずれかを提供します。
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "mail": {
+      "type": "http",
+      "url": "https://mail.agent-native.com/_agent-native/mcp",
+      "headers": { "Authorization": "Bearer <minted-token>" },
+    },
+  },
+}
+```
+
+接続後にエージェント クライアントを再起動し、新しい MCP サーバーを選択します。
+
+この手動ベアラー ブロックは、標準のリモート MCP OAuth フローを完了できない MCP クライアント、またはトークンを明示的に貼り付ける場合の 1 回限りのデバッグに使用します。
+
+### 標準リモート MCP OAuth {#standard-oauth}
+
+ホストされたエージェント ネイティブ アプリは、標準のリモート MCP OAuth フローもサポートします。 MCP OAuth を実装するクライアントの場合、静的ヘッダーのないリモート HTTP サーバー URL を追加します。
+
+```bash
+claude mcp add --transport http agent-native \
+  https://dispatch.agent-native.com/_agent-native/mcp
+```
+
+これは、`npx @agent-native/core@latest connect https://dispatch.agent-native.com --client claude-code` があなたのために書くのと同じ URL 専用のエントリです。次に、Claude コードで `/mcp` を実行し、**認証** を選択します。クライアントは、MCP サーバーの `401 WWW-Authenticate` チャレンジから認証を検出し、`/.well-known/oauth-protected-resource` と `/.well-known/oauth-authorization-server` を取得し、パブリック OAuth クライアントを動的に登録し、アプリの認証ページを開き、結果のトークンを安全に保存します。 ChatGPT 開発者モード コネクタは同じサーバー URL を使用します。
+
+```text
+https://dispatch.agent-native.com/_agent-native/mcp
+```
+
+OAuth フローは、リフレッシュ トークン ローテーションを伴う認証コード + PKCE です。アクセス トークンは、正確な MCP リソース URL にオーディエンス バインドされ、署名されたユーザー/組織 ID を保持するため、ツール呼び出し、`resources/read`、および MCP アプリ iframe で開始された `tools/call` はすべて、既存の接続ミント JWT パスと同じ `runWithRequestContext` テナント スコープを通じて実行されます。 iframe は生の OAuth トークンを受信しません。ホストは、認証された MCP 接続を通じて通話を仲介します。
+
+現在のスコープは次のとおりです:
+
+| スコープ    | 許可                                                                                      |
+| ----------- | ----------------------------------------------------------------------------------------- |
+| `mcp:read`  | 読み取り専用 MCP actions および通常のツール/リソース検出                                  |
+| `mcp:write` | actions と `ask-agent` メタツールを変更する                                               |
+| `mcp:apps`  | MCP アプリ リソースのリスト/読み取りとインライン UI レンダリング (サポートされている場合) |
+
+クライアントが明示的なスコープを要求しない場合、アプリは 3 つすべてを許可するため、コネクタはブラウザーで承認された接続フローのように動作します。すぐに貼り付けられる構成ブロックが必要なローカル開発、フォールバック ホスト、クライアント用に、ベアラー トークンの接続ページと `npx @agent-native/core@latest connect --token <token>` フォールバックを保持します。
+
+## カタログ階層 {#catalog-tiers}
+
+これは、MCP カタログ層の標準的な説明です。他のページはここにリンクされています。
+
+MCP サーバーは、ホスト型コネクタ (ChatGPT、Claude)、コード クライアント (Claude コード、カーソル、Codex)、およびローカル CLI/stdio プロキシなど、**デフォルトですべての呼び出し元** にコンパクトなカタログを提供します。完全なアクション サーフェスは、明示的なオプトインでのみ提供されます。カタログがクライアント名やユーザー エージェントから推測されることはありません。
+
+```an-diagram title="Two catalog tiers" summary="Every caller gets the compact tier by default; the full ~105-tool surface is opt-in only. tool-search bridges the gap so nothing is ever truly hidden."
+{
+  "html": "<div class=\"xa-tiers\"><div class=\"diagram-card\" data-rough><span class=\"diagram-pill ok\">Compact / connector tier &middot; default</span><strong>~20&ndash;30 tools</strong><small class=\"diagram-muted\">Template-declared app actions + cross-app builtins (<code>list_apps</code>, <code>open_app</code>, <code>ask_app</code>, <code>create_embed_session</code>) + always-present <code>tool-search</code>.</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill accent\">Full tier &middot; opt-in</span><strong>~105 tools</strong><small class=\"diagram-muted\">Explicit opt-in only: <code>--full-catalog</code> token or <code>AGENT_NATIVE_MCP_FULL_CATALOG=1</code>.</small></div></div><p class=\"diagram-muted note\"><code>tool-search</code> reaches any full-tier tool on demand &mdash; so the compact default keeps context small without hiding capability.</p>",
+  "css": ".xa-tiers{display:flex;align-items:stretch;gap:14px;flex-wrap:wrap}.xa-tiers .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;flex:1;min-width:240px}.xa-tiers .diagram-arrow{align-self:center;font-size:24px;line-height:1}.xa-tiers .note{flex-basis:100%;margin:4px 0 0;font-size:.85em}.xa-tiers code{font-size:.85em}"
+}
+```
+
+### コンパクト / コネクタ層 (デフォルト) {#connector-tier}
+
+デフォルトでは、接続されているすべてのエージェントに、厳選された小規模なカタログが表示されます (ツールが最大 20 ～ 30 個であるのに対し、全画面では最大 105 個)。
+
+- **テンプレートで宣言されたアプリ actions** — 安全なアプリレベルの許可リスト。プランの場合は、`create-visual-plan`、`get-visual-plan`、`share-resource`、`navigate`、`tool-search` などです。
+- **組み込みクロスアプリ ツール** — `list_apps`、`open_app`、`ask_app`、`create_embed_session`。
+- **`tool-search`** は常に存在するため、リストの外にあるものはすべてオンデマンドでアクセス可能です (以下を参照)。
+
+リスト外のツール (`db-exec`、`seed-*`、拡張スイート、ブラウザ セッション ツール、コンテキスト Xray ツールなど) はアドバタイズされず、呼び出し元が完全なカタログを選択していない限り、それらへの呼び出しは「不明なツール」として拒否されます。これにより、接続されている各エージェントのコンテキスト ウィンドウが小さく保たれ、シングル テナントのローカル開発でのみ安全なフットガンが削除されます。コネクタ層は、**テンプレートが `connectorCatalog` を宣言するときは常に**、環境変数の背後でゲートされません。
+
+`tool-search` は 2 つの方法で動作します。ツール名の完全なメニューと 1 行の説明 (安価、スキーマなし) を取得する **クエリなし** で呼び出すか、パラメータの概要を使用したランク付けされた一致のクエリを使用して呼び出します。このようにして、圧縮されたクライアントは、必要なときにフルサーフェス ツールを検出してロードします。
+
+### フルティア (明示的なオプトインのみ) {#full-tier}
+
+完全な ~105 ツールのアクション サーフェスは、明示的なオプトインでのみ、次の 2 つの方法で提供されます。
+
+- **トークンごと** — JWT に `catalog_scope: "full"` クレームを埋め込む `--full-catalog` でミントします。後続のリクエストは、そのトークンのコンパクト フィルターをバイパスします。
+
+  ```bash
+  npx @agent-native/core@latest 接続 https://plan.agent-native.com --client codex --full-catalog
+  ```
+
+- **デプロイメントごと** — すべての呼び出し元に全面的にサービスを提供するように `AGENT_NATIVE_MCP_FULL_CATALOG=1` (サーバー プロセス環境) を設定します。トークンごとのオプトアップを行わずに全サーフェスを必要とするシングルテナントでホストされるインスタンスに使用します。
+
+### テンプレート宣言 {#catalog-declaration}
+
+テンプレートは、`createAgentChatPlugin` オプションでコネクタ カタログを宣言します。
+
+```ts
+export default createAgentChatPlugin({
+  appId: "plan",
+  actions: loadActionsFromStaticRegistry(actionsRegistry),
+  connectorCatalog: [
+    "create-visual-plan",
+    "get-visual-plan",
+    "list-visual-plans",
+    "update-visual-plan",
+    // … other safe app-level actions
+    "set-resource-visibility",
+    "share-resource",
+    "upload-image",
+    "navigate",
+    "view-screen",
+    "manage-automations",
+    "tool-search",
+  ],
+});
+```
+
+組み込みのクロスアプリ ツール (`list_apps`、`open_app`、`ask_app`)
+`create_embed_session`、`create_workspace_app`、`list_templates`) は常に
+宣言されたリストに関係なく含まれます。
+
+## 接続後にできること {#what-you-can-do}
+
+エージェントが接続されると、すべての発信者はデフォルトでコンパクト カタログを取得します
+([Catalog tiers](#catalog-tiers) を参照) — コード/stdio 開発者クライアント、ローカル
+CLI プロキシ、および Claude や ChatGPT などのチャット ホスト。その表面は
+テンプレートで宣言されたアプリ actions と組み込みのクロスアプリ動詞 (`list_apps`、
+`open_app`、`ask_app`、およびアプリ専用の埋め込みヘルパー)。 `ask_app` を使用して
+アプリ エージェントを介した自然言語タスク (同じアプリ間エントリ ポイント
+[A2A](/docs/a2a-protocol) が使用します)。 `tool-search` は常に存在するため、どのツールでも
+コンパクト リストの外には、オンデマンドでアクセス可能な状態が維持されます。完全な ~105-tool
+事前に表示し、`--full-catalog` で明示的にオプトインするか、
+`AGENT_NATIVE_MCP_FULL_CATALOG=1`。いずれの場合も、エージェントに実際の作業を依頼してください
+実行中のアプリにリンクを直接返します。
+
+```
+> draft an email to John about the Q3 report
+
+Claude Code calls: manage-draft(to: "john@example.com", subject: "Q3 Report", body: "…")
+→ Open draft in Mail → https://mail.agent-native.com/_agent-native/open?app=mail&view=inbox&compose=…
+```
+
+そのリンクをクリックすると、メールが開き、下書きが復元され、ログイン ユーザーのいる場所に正確にフォーカスされます。エージェントはあなたのセッションを知る必要はありませんでした。アーティファクトを生成しただけです。
+
+### MCP アプリの互換性 {#mcp-apps-compatibility}
+
+エージェント ネイティブ アプリは、公式の MCP アプリ拡張機能も話します。何らかのアクションが発生したとき
+`mcpApp` を宣言し、サーバーがアドバタイズします
+`extensions["io.modelcontextprotocol/ui"]`、`_meta.ui.resourceUri` を含む /
+`tools/list` の `_meta["ui/resourceUri"]`、および HTML UI を介してサービスを提供します
+`resources/list` + `resources/read` として `text/html;profile=mcp-app`。リソース
+CSP やサンドボックス権限などのセキュリティ メタデータはリソース上に存在します
+エントリと `resources/read` コンテンツ。ツール記述子にはありません。
+
+ChatGPT/Claude スタイルの OAuth アプリ ホストの場合、検出サーフェスはデフォルトでコンパクトです。`tools/list` および `resources/list` は、アクション固有のすべての MCP アプリ リソースではなく、汎用の `open_app` 埋め込みパスをアドバタイズします ([Catalog tiers](#catalog-tiers) を参照)。個々のアクションを `mcpApp.compactCatalog: true` でマークするのは、チャットホスト検出で本当に表示し続ける必要がある場合のみです。
+
+これにより、クライアントごとに shim を構築するのではなく、互換性のあるすべてのホストで同じアプリ サーフェスを利用できるようになります。 MCP アプリをインラインでレンダリングするホスト (およびメタデータ変更後のコネクタ キャッシュの問題点) は [MCP Apps → Client support and caching](/docs/mcp-apps#client-support) にあります。そのページはクライアント マトリックスの単一のホームです。
+
+実際には、すべてのエージェント ネイティブ アプリは、対応ホストでのインライン レビュー/編集用の MCP アプリと、完全なアプリへのユニバーサル ラウンドトリップ用の `link` の両方を使用して作成する必要があります。 iframe をレンダリングしない CLI/コードエディター クライアントは、ディープ リンクにフォールバックします。人間による選択ツールは、そのフォールバックにペーストバック ステップを追加できます。たとえば、アセット ピッカーがフォールバック リンクから開き、ユーザーがブラウザでメディアを選択できるようにして、ユーザーがチャットに貼り付けるハンドオフの概要をコピーします。
+
+### ファーストクラス MCP アプリ ブリッジ {#mcp-app-bridge}
+
+`embedApp()` は、アクションの `link` ターゲットから開始され、短期間の埋め込みセッションを作成し、署名されたアプリ ルートを起動します。 Claude Web は単一フレーム移植パスを使用します。 ChatGPT は、`window.openai` ホスト API で制御されたルート iframe を取得します。すべてのパスは通常の React ルートをレンダリングします。直接ハイドレートされたルートは、ホスト ブリッジを通じて `ui/update-model-context`、`ui/message`、`ui/open-link`、および `ui/request-display-mode` を呼び出します。 ChatGPT パスは、`agentNative.mcpHost.*` postMessage 経由で同じリクエストを中継します。 `embedApp({ height })` のデフォルトは `560px` で、`320-900px` に固定されます。
+
+ブリッジの完全な詳細については、[MCP Apps](/docs/mcp-apps) を参照してください。移植と制御フレーム、埋め込みモード、`ui/*` テーブルと postMessage テーブル、`embedStartUrl`、CSP ルール、拡張機能 `srcDoc` 埋め込み、高さクランプ、完全なホスト ブリッジ クライアント API です。
+
+### 一般的なクロスアプリ動詞 {#cross-app}
+
+アクションごとのツールに加えて、MCP サーバーは安定した動詞セットを公開するため、外部エージェントはアプリごとのアクション名を推測することなく予測可能な表面を持ちます。
+
+| ツール                                             | 副作用              | 返品                                                                                                                        |
+| -------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `list_apps`                                        | なし                | ワークスペース アプリ + その URL / 実行状態                                                                                 |
+| `open_app({ app, view?, path?, params?, embed? })` | なし                | ディープリンクまたは同一発信元ルート。 `embed: true` は、サポートされている場合、アプリ全体をインラインでレンダリングします |
+| `ask_app({ app, message })`                        | エージェント ループ | 自然言語タスクをそのアプリのアプリ内エージェント (`ask-agent` に委任) にルーティングします                                  |
+| `create_workspace_app({ name, template })`         | 足場                | ワークスペース パス経由で起動された新しいアプリと、実行中の URL + ディープ リンク                                           |
+| `list_templates`                                   | なし                | 許可リストに登録されたテンプレートのみ                                                                                      |
+
+`create_workspace_app` は、許可リストに登録されていないテンプレートを拒否します。`packages/shared-app-config/templates.ts` のパブリック テンプレートの許可リストは権限があり、CI で保護されています。外部エージェントがそれを広げることはできません。同じ名前のテンプレート アクションは、組み込みをオーバーライドします (コアよりテンプレートが優先されます)。 `MCPConfig.builtinCrossAppTools: false` でセット全体を無効にします。
+
+アプリ ホストのツール カタログとリソース カタログは、デフォルトではコンパクトです。[Catalog tiers](#catalog-tiers) を参照してください。 `publicAgent.expose` は、コンパクト カタログ外の安全な読み取り/取り込みツールのオプトインのままです。チャットホスト検出に表示する必要がある actions のまれな例外としてのみ、`mcpApp.compactCatalog: true` を設定します。
+
+高速 ChatGPT/Claude ハンドオフの場合、理想的なパスは直接パスです。アーティファクトを作成または開くアクションを呼び出してから、MCP アプリにルートを起動させます。 Mail リクエストは `manage_draft` を呼び出し、実際の作成ルートをレンダリングする必要があります。ダッシュボード リクエストでは、`open_app({ path, embed: true })` を呼び出すか、`mcpApp` を使用してダッシュボード アクションを呼び出し、完全な Analytics ルートをレンダリングする必要があります。カレンダー、フォーム、コンテンツ、スライド、デザイン、クリップは、下書き/作成/検索 actions と同じパターンに従う必要があります。 `list_apps` は、モデルが許可されたアプリの中から選択する必要がある場合に便利です。広範な `resources/list`、フルカタログ検出、または `ask_app` 委任は、明らかな UI ハンドオフの通常のルートであってはなりません。
+
+### アプリごとのツアー {#tour}
+
+ナビゲート可能なリソースを生成またはリストする許可リストに登録されたすべてのテンプレートには `link` ビルダーが同梱されており、取り込みが多いテンプレートには GET + `publicAgent` アクションが同梱されているため、接続されたエージェントはライブ状態を取得できます。
+
+- **Mail** — `manage-draft` は、`compose` でエンコードされたディープ リンクを返します。それをクリックすると、`compose-<id>` に復元されたドラフトを含む受信トレイが開きます。 `list-emails` / `search-emails` はフィルタリングされた受信トレイ ビューを指します。
+- **Calendar** — `manage-event-draft` は、`calendarDraft` + `eventDraftId` ディープ リンクを返します。これをクリックすると、レビュー/送信用のネイティブ イベント エディターを備えたカレンダー上に表示される下書きプレースホルダーが開きます。 `create-event` は依然として `buildDeepLink({ app: "calendar", view: "calendar", params: { eventId, date } })` を返します。クリックするとカレンダー上にそのイベントが表示され、その日付にフォーカスが当てられます。
+- **分析** — `update-dashboard` / `save-analysis` は `buildDeepLink({ app: "analytics", view: "adhoc", params: { dashboardId } })` を返します。エージェントは MCP 上にダッシュボードを構築し、「Analytics でダッシュボードを開く」を返します。
+- **デザイン** — `get-design-snapshot` は、GET + `publicAgent` 取り込みアクションです。**ライブ** Yjs ファイルの内容と解決された調整値を返すため、エージェントは元のトークンではなく、調整されたデザインから続行します。 `apply-tweaks` は、「オープン デザイン」エディター リンクを使用して往復します。
+- **コンテンツ** — `pull-document` は、GET + `publicAgent` 取り込みアクションです。最初に開いているライブ共同作業セッションを SQL にフラッシュし、外部エージェントがユーザーに表示されているものを正確に取り込み、次にドキュメントへのディープ リンクを表示します。
+- **Brain** — `ask-brain` / `search-everything` は、引用された回答と基礎となる知識/キャプチャへのディープ リンクを返すため、ターミナル エージェントのルックアップは実行中のアプリのソースに直接リンクされます。
+
+## オーサリング (テンプレート作成者向け) {#authoring}
+
+上記の内容はすべて、アプリに接続して使用する **エンド ユーザー**向けです。このページの残りの部分は、**テンプレート作成者**向けで、アプリを外部エージェントの善良な市民になるように接続します。`link` ビルダー、オプションの MCP アプリ UI、`/_agent-native/open` ルート内部、および actions の取り込みです。
+
+### `link` ビルダー {#link-builder}
+
+`defineAction` は、オプションの `link` ビルダーを受け入れます。設定すると、そのツールのすべての MCP/A2A 結果に、マークダウン `[label →](absoluteUrl)` ブロックと構造化 `_meta["agent-native/openLink"] = { label, view, webUrl, desktopUrl, vscodeUrl }` が自動的に追加されます。 `tools/list` は、`annotations["agent-native/producesOpenLink"]` と説明サフィックスを追加するため、外部エージェントはツールが開くことができるリンクを生成し、それを表示する必要があることを認識します。
+
+`buildDeepLink(...)` を使用して URL を構築します。これは、オープンルート フォーマットの信頼できる唯一の情報源です。 `/_agent-native/open` URL を手動でフォーマットしないでください。
+
+実際の例 — メールの `manage-draft` (`templates/mail/actions/manage-draft.ts`):
+
+```ts
+import { buildDeepLink } from "@agent-native/core/server";
+
+function composeDeepLink(draft: Record<string, string>): string {
+  return buildDeepLink({
+    app: "mail",
+    view: "inbox",
+    compose: encodeComposeDraft(draft), // base64url JSON → compose-<id> draft
+  });
+}
+
+export default defineAction({
+  // ...schema, run...
+  link: ({ result }) => {
+    if (!result || typeof result !== "object") return null;
+    const draft = (result as { draft?: Record<string, string> }).draft;
+    const id = (result as { id?: string }).id;
+    if (!draft || !id) return null;
+    return {
+      url: composeDeepLink(draft),
+      label: "Open draft in Mail",
+      view: "inbox",
+    };
+  },
+});
+```
+
+リスト/検索 actions は、同じ方法でレコード中心のビューをポイントします — 例:カレンダーの `create-event` は、ラベル `"Open event in Calendar"` を持つ `buildDeepLink({ app: "calendar", view: "calendar", params: { eventId, date } })` を返します。カレンダーのドラフト actions も同じパターンを使用します。`manage-event-draft` は、ラベル `"Review invite in Calendar"` を持つ `buildDeepLink({ app: "calendar", view: "calendar", to: "/", params: { eventDraftId, calendarDraft, date } })` を返すため、外部エージェントは最初にイベントを作成しなくても、ドラフトとレビューの直接リンクを返すことができます。
+
+### オプションの MCP アプリ UI {#mcp-apps}
+
+Actions は、MCP アプリ拡張機能をサポートするホストに対して、`mcpApp` を使用してインライン UI リソースをアドバタイズできます。 `embedRoute({ title, openLabel, path })` をコンビニエンス ラッパーとして使用するか、`embedApp(...)` を `mcpApp.resource` に直接割り当てます。すべての MCP アプリは、別個のプレーン HTML ウィジェットではなく、実際の React ルートです。 `link` ビルダーは常に保持してください。CLI のみのホスト、古いクライアント、および MCP アプリ以外のホストは、これをフォールバックとして使用します。
+
+完全なオーサリング ガイドについては、[MCP Apps](/docs/mcp-apps) を参照してください。`embedRoute` と `embedApp`、`mcpApp` 構成形状、CSP、高さ、`sendToAgentChat()` 埋め込みパス、およびホスト ブリッジ クライアント ヘルパー。
+
+### `link` 契約 {#link-contract}
+
+`link` ビルダーは **純粋で同期的です。I/O や待機はありません**。ベストエフォートで実行されます。スロー、`null`、または `undefined` は飲み込まれ、ツール呼び出しは**決して**失敗しません。呼び出しの `args` および `result` のみを読み取ります。 DB のクエリ、アプリ状態の読み取り、または他の actions の呼び出しを行ってはなりません。開くものが何もない場合は、`null` を返します。
+
+`buildDeepLink({ app, view, params?, to?, compose? })` は、アプリの相対パス `/_agent-native/open?app=…&view=…&<recordId>=…` を返します。 MCP レイヤーは、これを絶対ウェブ URL (`toAbsoluteOpenUrl`、リクエスト起点を使用)、デスクトップ `agentnative://open?…` URL (`toDesktopOpenUrl`)、および `vscode://builder.agent-native/open?url=…` の VS Code 拡張機能 URL (`toVsCodeOpenUrl`) に変換します。クライアントが `target: "desktop"` を通知すると、マークダウン リンクはデスクトップ URL を使用します。
+
+### `/_agent-native/open` ルート {#open-route}
+
+ユーザーがブラウザまたはインライン Web ビューでリンクをクリックすると、`GET /_agent-native/open` (コア ルート プラグインによってマウントされた `createOpenRouteHandler`) が以下の手順を実行します。
+
+```an-api
+{
+  "method": "GET",
+  "path": "/_agent-native/open",
+  "summary": "Deep-link open route — focuses the browser UI on a record",
+  "description": "Resolves the browser session, writes a one-shot `navigate` application-state command scoped to that session, and 302-redirects to a safe same-origin path. Always build the URL with `buildDeepLink(...)`; never hand-format it. Can be disabled per app with `disableOpenRoute`.",
+  "auth": "Browser session via `getSession`. The auth guard bypasses this exact path; if unauthenticated it serves login HTML at the same URL, and the form reload re-enters authenticated (no `?next=` plumbing).",
+  "params": [
+    { "name": "app", "in": "query", "type": "string", "description": "Target app id (e.g. `mail`)." },
+    { "name": "view", "in": "query", "type": "string", "description": "View to focus; also folded into the `navigate` payload." },
+    { "name": "to", "in": "query", "type": "string", "description": "Optional explicit same-origin relative redirect target. Falls back to `/<view>`, then a per-template `resolveOpenPath`." },
+    { "name": "compose", "in": "query", "type": "string", "description": "base64url-encoded draft, decoded into a `compose-<id>` application-state key." },
+    { "name": "f_*", "in": "query", "type": "string", "description": "Filter params forwarded to the redirect so lists/dashboards open pre-filtered." }
+  ],
+  "responses": [
+    { "status": "302", "description": "Redirect to a safe same-origin relative path. Cross-origin, scheme-relative `//host`, and control-char redirects are rejected (open-redirect guard)." },
+    { "status": "200", "description": "Login HTML served at the same URL when the browser session is unauthenticated." }
+  ]
+}
+```
+
+1. `getSession` 経由で **ブラウザ** セッションを解決します (認証ガードは正確なパス `/_agent-native/open` をバイパスします)。
+2. 認証されていない場合は、構成されたログイン HTML を **同じ URL** で提供します。フォームの成功ハンドラーは `window.location` をリロードし、認証されたルートに再度入ります (`?next=` 配管はありません)。
+3. ブラウザ セッションの電子メールをスコープとする既存のワンショット `navigate` アプリケーション状態コマンド (ペイロード = すべての予約されていないクエリ パラメーター + `view`) を `requestSource: "deep-link"` で書き込み、`compose` の Base64url ドラフトを `compose-<id>` キーにデコードします。
+4. 302 は、安全な同一オリジンの相対パス (`to=`、そうでない場合は `/<view>`、それ以外の場合はテンプレートごとの `resolveOpenPath`) にリダイレクトし、`f_*` フィルター パラメーターを転送するため、`navigate` コマンドが実行される前に事前にフィルターされた状態でリスト/ダッシュボードが開きます。
+
+クロスオリジン、スキーム相対 `//host`、および control-char リダイレクトは拒否されます (オープンリダイレクト ガード)。ルートは、`disableOpenRoute` 経由でアプリごとに無効にできます。
+
+#### ブラウザ セッション ID ルール {#identity-rule}
+
+リンクには **特権状態はありません**。それは単なる `view` + レコード ID + フィルターです。レコードに焦点を当てた `navigate` 書き込みは、**ブラウザ**にログインしているユーザーにスコープされ、外部エージェントの MCP トークンにはスコープされません。したがって、1 つの ID として認証されたエージェントはユーザーにリンクを渡すことができ、そのユーザーがリンクをクリックすると、そのユーザーがログインしているレコードが開きます。これにより、ディープ リンクが端末やチャットの記録に安全に表示されるようになります。このブリッジ先の `navigate` / `application_state` 契約については、[Context Awareness](/docs/context-awareness) を参照してください。
+
+### actions を取り込む {#ingest}
+
+外部エージェントがライブ アプリの状態を独自のコンテキストに取り込むために読み取るアクションは、次のとおりである必要があります。
+
+```ts
+export default defineAction({
+  description: "…",
+  schema: z.object({ id: z.string() }),
+  http: { method: "GET" },
+  readOnly: true,
+  publicAgent: { expose: true, readOnly: true, requiresAuth: true },
+  run: async ({ id }) => {
+    /* read LIVE state, not the stale DB snapshot column */
+  },
+});
+```
+
+`GET` + `readOnly` は、アクションの副作用を発生させず、画面更新変更イベントの対象外に保ちます。 `publicAgent` は **明示的なオプトイン** です。パブリック Web ルートは、MCP/A2A への公開を決して意味しません。 [Actions](/docs/actions)を参照してください。デザイン/コンテンツの取り込み actions MUST は **ライブ** 状態 (古い DB スナップショット列ではなく、Yjs 共同ドキュメント) を読み取るため、外部エージェントはユーザーが実際に画面上に表示しているものを確認します。コンテンツの `pull-document` は、開いているライブ コラボ セッションを最初に SQL にフラッシュします。デザインの `get-design-snapshot` は、ライブ Yjs ファイルの内容とユーザーが解決した調整値を返します。
+
+## 上級: ローカル開発と手動セットアップ {#advanced}
+
+上記のホストされた `connect` フローが推奨パスです。以下のオプションは、ローカル開発および手動セットアップ用です。
+
+### ローカル開発 {#local-dev}
+
+アプリをローカルで実行し (`pnpm dev` / `npx @agent-native/core@latest dev`)、1 つのコマンドでローカル エージェントを指定します。
+
+```bash
+npx @agent-native/core@latest mcp install --client claude-code|claude-code-cli|codex|cowork \
+  [--app <id>] [--scope user|project]
+```
+
+トークン (ローカル開発用のワークスペース `.env` へのランダムな `ACCESS_TOKEN`、またはホストされたオリジンを検出した場合は署名された JWT) をプロビジョニングし、冪等の stdio サーバー エントリを書き込みます。
+
+- **claude-code / claude-code-cli** — `.mcp.json` (プロジェクト スコープ、デフォルト) または `~/.claude.json` (`--scope user`) 内の `mcpServers` エントリ。
+- **cowork** — `~/.cowork/mcp.json` 内の同じ Claude コード JSON 形状。
+- **codex** — `~/.codex/config.toml` 内の `[mcp_servers.<name>]` ブロック。
+
+このエントリは `npx @agent-native/core@latest mcp serve --app <id>` を実行します。これはデフォルトで、実行中のローカル アプリの `/_agent-native/mcp` への **シン stdio プロキシ**です。そのため、ライブ アクション レジストリ、HMR、および正しいディープ リンクが唯一の信頼できる情報源のままになります。代わりに `--standalone` を渡して、インプロセスでレジストリを構築します。 `npx @agent-native/core@latest mcp install` がホストされたオリジン (ワークスペース `.env` 内の非ローカルホスト `APP_URL` / `BETTER_AUTH_URL` / `AGENT_NATIVE_MCP_URL`) を検出すると、stdio エントリの代わりに、`Bearer` JWT を持つ `<origin>/_agent-native/mcp` を指す `http` クライアント エントリを書き込みます。
+
+コンパニオンサブコマンド:
+
+| コマンド                                                   | その機能                                                                                |
+| ---------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `npx @agent-native/core@latest mcp serve [--app <id>]`     | MCP stdio トランスポートを実行します (クライアント構成が生成するもの)。                 |
+| `npx @agent-native/core@latest mcp install --client <c>`   | トークンをプロビジョニングし、クライアントの MCP 構成を書き込みます (冪等)。            |
+| `npx @agent-native/core@latest mcp uninstall --client <c>` | 指定された MCP エントリをクライアントの構成から削除します (冪等)。                      |
+| `npx @agent-native/core@latest mcp status`                 | 解決された MCP URL/ポート、トークン状態、およびクライアントごとのエントリを表示します。 |
+| `npx @agent-native/core@latest mcp token [--rotate]`       | ワークスペース `.env` 内のローカル `ACCESS_TOKEN` を印刷 (または回転) します。          |
+
+`install` の後にクライアントを再起動して、新しい MCP サーバーを選択します。
+
+### 手動 `.mcp.json` HTTP エントリ {#manual-entry}
+
+自分で指定したトークン (`ACCESS_TOKEN`、または呼び出し元の `sub` + `org_domain` を保持する `A2A_SECRET` 署名付き JWT を使用して、ツールの実行がテナント スコープのままになるように) を使用して、デプロイされたエンドポイントに対して MCP クライアント構成を手動で記述することもできます。
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "analytics": {
+      "type": "http",
+      "url": "https://analytics.agent-native.com/_agent-native/mcp",
+      "headers": { "Authorization": "Bearer <ACCESS_TOKEN-or-JWT>" },
+    },
+  },
+}
+```
+
+これは、`connect` が書き込むものと同等のアンマネージドです。完全な認証環境変数マトリックスについては、[MCP Protocol](/docs/mcp-protocol) を参照してください。
+
+### 開発ツールと運用ツールのサーフェス {#dev-vs-prod}
+
+プレーンなローカル開発 (`NODE_ENV=development` および `AGENT_MODE !== "production"`) では、MCP `tools/list` は、汎用ビルトインと actions および `publicAgent.requiresAuth === false` のみを意図的に公開します。アプリごとの取り込み actions (`requiresAuth: true`) と変更 actions (いいえ) `publicAgent`) はフィルターで除外されます (`filterPublicAgentActions`)。コンパクト カタログは、認証後のすべての呼び出し元 (`agent-native` プロキシを使用する stdio/code クライアント、ローカル CLI、およびチャット スタイルのリモート HTTP 呼び出し元も同様) のデフォルトであるため、ChatGPT/Claude (または任意のクライアント) は、巨大な完全なアクション カタログを会話にダンプできません。完全な開発者カタログは、明示的なオプトイン (`--full-catalog` トークンまたは `AGENT_NATIVE_MCP_FULL_CATALOG=1`) でのみ提供されます。 `tool-search` はその間、すべてのツールにアクセスできるようにします。
+
+### 製品版と開発版の間でのファーストパーティ アプリの切り替え {#dev-switch}
+
+すでにファーストパーティのホスト型アプリが接続されており、`pnpm dev:lazy` を通じてローカル フレームワークの変更をテストしたい場合は、開発者スイッチャーを使用します。
+
+```bash
+pnpm dev:lazy -- --apps mail,calendar,analytics
+
+npx @agent-native/core@latest connect dev --apps mail,calendar,analytics --client codex
+```
+
+`connect dev` は、同じ安定した MCP サーバー名 (`agent-native-mail`、`agent-native-calendar` など) をローカルの dev-lazy ゲートウェイに書き換えるため、ツール名は変わりません。開発エントリを書き込む前に、`~/.agent-native/connect-profiles.json` の現在の運用エントリをバックアップします。デフォルト ゲートウェイは `http://127.0.0.1:8080` です。ゲートウェイが移動した場合は、`--gateway <url>` または `--port <n>` を使用してください。
+
+次のように切り替えてください:
+
+```bash
+npx @agent-native/core@latest connect prod --apps mail,calendar,analytics --client codex
+```
+
+`connect dev` が既存の接続された JWT からローカル所有者の ID を推測できない場合は、`--owner-email you@example.com` を渡します。これにより、ローカル開発ツールは、疎な非認証開発サーフェスではなく、完全に認証された MCP サーフェスに保持されます。
+
+## 仕組みとセキュリティ {#how-it-works}
+
+標準の OAuth パスは、トークンを MCP アプリに公開することはありません。ホストは、OAuth アクセス/リフレッシュ トークンを保存し、認証された MCP 接続を介してツール呼び出しと `resources/read` を仲介します。埋め込み iframe は、ベアラー シークレットではなく、アプリ データとツールの結果を受け取ります。
+
+フルアプリの埋め込みでは、MCP ベアラー トークンをブラウザーに渡すことも回避されます。 MCP 呼び出し元は、SQL に 1 回限りの埋め込みチケットを作成します。 iframe 起動ルートはそれを消費し、有効期間が短い iframe セーフなブラウザ セッション Cookie を設定します。ランディング URL は、サードパーティ Cookie がブロックされている場合に、クライアントがそれをキャプチャし、アドレス バーから削除し、同じオリジンの `fetch` 呼び出しに添付するのに十分な長さの一時的な `__an_embed_token` クエリ パラメーターを伝送します。埋め込みセッションはルートスコープです。アプリのフェッチには現在の埋め込みターゲットが含まれており、サーバーはミントされたルート外でのトークンの再利用を拒否します。アプリ ページは意図的に `X-Frame-Options` または CSP `frame-ancestors` を出力しないため、Builder、デザイン、および MCP アプリ ホストはそれらを iframe できます。ブラウザ iframe ナビゲーションは、クロスオリジン分離ホストに必要な場合、COEP/CORP もオプトインします。
+
+フォールバック ホスト型 `connect` フローは、展開の共有秘密をコピーしません。代わりに:
+
+- ログインしたブラウザ セッションは、**ユーザーごとのスコープ指定された取り消し可能な** トークン (呼び出し元の `sub` + `org_domain` および一意の `jti` を保持する `A2A_SECRET` 署名付き JWT) を生成するため、すべてのツールの実行は `runWithRequestContext` を介してテナント スコープのままになります。
+- 既存の `/_agent-native/mcp` エンドポイントは、他のベアラーと同様にそのトークンを受け入れます ([MCP Protocol](/docs/mcp-protocol) を参照)。新しいエンドポイントや新しいトランスポートはありません。
+- 同じ接続ページには、作成したすべてのトークンがリストされ、`jti` によってそれらのトークンを**取り消す**ことができます。それらを個人用アクセス トークンのように扱います。エージェント クライアントごとに 1 つ、マシンが廃止されると取り消されます。
+- エージェントが返すディープリンクには特権状態はありません。レコードに焦点を当てた `navigate` 書き込みは常に **ブラウザ** セッションにスコープされ、エージェントのトークンにはスコープされません。そのため、リンクをターミナルまたはチャット記録に安全に貼り付けることができます。
+
+## する / しない {#do-dont}
+
+**実行してください**
+
+- `npx @agent-native/core@latest connect https://dispatch.agent-native.com` を使用して独自のエージェントを Dispatch に接続します。直接アプリ URL は、1 つの独立したアプリが必要な場合にのみ使用してください。
+- ナビゲート可能なリソース (ドラフト、イベント、ダッシュボード、ドキュメント) を生成またはリストするアクションに `link` ビルダーを追加します。
+- `buildDeepLink(...)` を使用して URL を構築します。オープンルート フォーマットの信頼できる唯一の情報源です。
+- `link` を純粋かつ同期的に保ちます。開くものが何もない場合は、`null` を返します。
+- 外部エージェントが actions GET + `readOnly` + `publicAgent` を取り込み、古い DB 列ではなくライブ (Yjs) 状態を読み取るようにします。
+- オープンルートでブラウザセッションを解決させます。レコード ID をディープリンク パラメータとして渡し、ポーリングされた `navigate` コマンドを介して UI がそれらにフォーカスできるようにします。
+- エージェント クライアントが廃止されるときに、`jti` によってミントされた接続トークンを取り消します。
+- `embedApp()` 周辺の軽量フィクスチャを使用して MCP アプリをテストし、
+  `McpAppRenderer`; CSP、ホスト コンテキスト、アプリの起動、ブリッジをカバーします
+  実際の外部ホストを必要としないメッセージの動作。
+- ChatGPT または Claude Web を検証する場合、シェルの後に新しいツール呼び出しをトリガーします
+  変更し、表示される iframe を測定します。
+  同じ会話でも、キャッシュされた高さまたは起動動作が表示される場合があります。
+- ChatGPT/Claude アプリホスト カタログをコンパクトに保ちます。ディスパッチを使用して
+  `open_app({ embed: true })` (フルアプリのプレビュー用)。特定の
+  アクション `mcpApp.compactCatalog: true` を直接指定する必要がある場合
+  コンパクトなホスト検出面。
+
+**しないでください**
+
+- `connect` がユーザーごとの取り消し可能なトークンを作成できる場合は、展開の共有 `ACCESS_TOKEN` / `A2A_SECRET` をクライアント構成にコピーします。
+- `/_agent-native/open` URL を手動でフォーマットします — 常に `buildDeepLink` を通過します。
+- `link` ビルダー内で I/O、待機、DB 読み取り、またはアプリ状態読み取りを実行します。
+- `navigate` 書き込みのスコープをエージェント トークンに設定するか、ディープ リンク経由で特権状態を渡します。これは純粋なポインタです。
+- 新しいナビゲーション メカニズムを発明します。既存の `navigate` / `application_state` 契約へのブリッジ。
+- 外部エージェントからアプリをスキャフォールディングする場合は、パブリック テンプレートのホワイトリストを拡張します。ホワイトリストは権限があり、保護されています。
+
+## 関連 {#related}
+
+- [MCP Apps](/docs/mcp-apps) — MCP アプリ UI、埋め込みブリッジ、およびホスト ブリッジ API をオーサリングします。
+- [MCP Protocol](/docs/mcp-protocol) — 自動マウントされる MCP サーバーと `ask-agent` メタツール。
+- [MCP Clients](/docs/mcp-clients) — 対称方向: アプリはローカル/リモート MCP サーバーを消費します。
+- [A2A Protocol](/docs/a2a-protocol) — `ask-agent` メタツールおよび JSON-RPC ピア呼び出し。
+- [Actions](/docs/actions) — actions、`publicAgent`、GET / `readOnly` を定義します。
+- [Context Awareness](/docs/context-awareness) — オープン ルート ブリッジを契約する `navigate` / `application_state`。