webmcp

WebMCP

/webmcp <url-or-app> [request] は、ホスト内蔵ブラウザーでウェブアプリを開き、ページ独自のツールを使ってリクエストを完了します。最初のトークンは URL またはアプリのエイリアスで、それ以降はリクエストです。

/webmcp slides make me a new deck about customer onboarding

2 つのルール

1. ホスト内蔵ブラウザーで開く — 外部の Chrome ウィンドウ、通常のタブ、ブラウザー拡張機能は決して使わないでください。
2. ページのツールを呼び出す。 ツールで実行できる操作に対して、クリック、入力、ドラッグ、スクリーンショット撮影、DOM の自動操作は決して行わないでください。UI コントロールは、ナビゲーションと目視での確認にのみ使います。

以上がすべての約束事です。以下はすべて標準のページ API、またはこのルールのいずれかを誤って実装した特定のホスト向けの回避策です。ホストが WebMCP をネイティブにサポートしている場合は、2 つのルールに従い、そのまま実行させてください。

クイックスタート

• /webmcp <url-or-app> はリクエストがない場合、ページを開くだけです。解決した URL を表示中の内蔵タブで開き、ページが表示されたことを確認して終了します。ユーザーが操作を指定するまでは、ツールの一覧表示、スキーマの確認、サインイン、アプリでの作業開始を行わないでください。
• /webmcp <url-or-app> <request> は操作を実行します。ページを開いたら、すぐにツールを使います。ページの内容や以前の会話から、追加の作業を推測しないでください。

リクエストが指定されている場合は、ページを開いた後も作業を続けてください。1 件の編集には、画面の読み取り、変更、変更後の読み取りという約 3 回のページ呼び出しが必要です。6 回目の評価に入ってもまだ何も書き込まれていない場合は、実行するのではなく、探索を続けています。

ページを開く

• 完全な URL またはホスト名を受け付けます。スキームがない場合は https:// を付け、ホスト、パス、クエリ、ハッシュはそのまま保持してください。独断でベータ版と本番環境を切り替えないでください。
• Claude Code と Cowork：preview_start { url } を実行し、次に tabs_select でタブを前面に表示します。Codex：cua.createBrowserTab("iab", url, { visible: true }) を実行し、次に tab.markDeliverable() を呼び出します。
• ツールが登録される間は、ペインを表示したままにしてください。ペインが非表示だと、ツールの登録とページ内タイマーの両方が抑制されます。あるアプリでは、前面に表示すると 217 個すべてのツールが即座に登録された一方、非表示の場合は 28 秒後でも 59 個しか登録されませんでした。

サインイン

ツールを使う前に、ページタイトルと冒頭の行を確認してください。タイトルが「— Sign in」で終わる、「Sign in with Google」ボタンがある、または「You don't have access」と表示されている場合、ページにはまだツールがありません。タブはそのままにして、次のように伝えてください。 Please sign in in the open browser, then reply "continue". パスワード、Cookie、トークン、確認コードを入力、コピー、確認したり、要求したりしないでください。サインイン後にアプリがリダイレクトし、?slide=3 のようなディープリンクの状態が失われることがあります。元の画面が表示されていると思い込まず、画面を読み直してください。

ページのツールを呼び出す

ホストに独自の WebMCP ブリッジがある場合は、それを使い、ここにある他の手順はすべて省略してください （list-browser-session-webmcp-tools と run-browser-session-webmcp-tool、または list-host-webmcp-tools と run-host-webmcp-tool）。一覧取得ツールを 1 回呼び出し、次に発見した正確な名前、オリジン、引数を指定して実行ツールを呼び出してください。現在のタブのページツールの代わりに、汎用の tool-search、別アプリのコネクター、ask_app、リモート API を使わないでください。

それ以外の場合は、ページ内で評価します。document.modelContext が正式なページ API で、あらゆる WebMCP サイトで動作します。navigator.modelContext は非推奨です。

const ctx = document.modelContext;
const tool = (await ctx.getTools()).find((t) => t.name === NAME);
const codex =
  typeof ctx.codexExecuteTool === "function" ||
  typeof ctx.codexGetTools === "function";
const raw = await ctx.executeTool(tool, codex ? ARGS : JSON.stringify(ARGS));

ディスクリプターはページ外では呼び出せません。ページからコピーしてホスト側で呼び出したり、認証済み HTTP リクエストを独自に組み立てたり、開発者コンソールに入力したりしないでください。

ホストごとの評価方法

• Claude Code and Cowork: javascript_tool はページのワールドでトップレベルの await を使って実行されます。JSON 文字列を 1 つ返し、約 8 KB に切り詰めてください。このツールの呼び出し時間の上限は約 45 秒です。評価ごとに、依存する呼び出しを 2～4 件まとめて実行してください。ナビゲーションはまとめて実行しないでください。
• Codex: まずセッションごとに一度、tab.capabilities.get("webmcp").fetchTools() を試してください。2026-09 まで、現在のモデルでは does not support command "webmcp_list_tools" が返されます。これはブリッジがセッションの残りの間利用できないという意味であり、ページにツールがないという意味ではありません。その後は CDP を使います。globalThis.__cdp ??= await tab.capabilities.get("cdp") を実行し、次に await globalThis.__cdp.documentation() を一度実行してください（最初の CDP 呼び出しは、これを実行しないと失敗します）。続いて cdp.send("Runtime.evaluate", { expression, awaitPromise: true, returnByValue: true }) を実行し、response.result.value を nodeRepl.write(...) で出力します。評価ごとに呼び出しは 1 回です。Playwright の分離されたワールドからは document.modelContext を参照できません。CDP を使ってください。
• 評価結果の先頭に、アクセシビリティツリーやその他の観察結果が付加されることがあります。最後にある明示的な戻り値を解析してください。ツリーはコンテキストであり、ツールの結果ではありません。

知っておくべきホスト側の不具合

それぞれ、実際のデバッグ作業を費やす原因になりました。いずれもページやアプリの問題ではありません。これらをページやアプリの問題だと診断しないでください。

• Codex の CDP は約 3 秒でタイムアウトします（「Timed out running CDP command」）。タイムアウトした評価結果は未読の結果であり、書き込みに失敗したわけではありません。書き込みを再実行せず、次の評価で結果を読み取ってください。
• Codex は、呼び出し間で永続するとドキュメントに記載されているにもかかわらず、cua_repl カーネルを再起動します。let／const のハンドルは再起動後に保持されません。2026-09-08 の計測では、ページの呼び出しはすべて成功した後、リセットによって cdp is not defined、tab is not defined、Browser is not available: 2 が発生し、cua.getState() は「Sky Computer Use native pipe startup failed」を返すのに 5.4～6.6 秒かかりました。ハンドルは globalThis に保持し、各評価の先頭で再取得してください。cdp is not defined または tab is not defined が発生した場合は、タブを開き直して documentation() を再実行してください。復旧のために cua.getState() を呼び出さないでください。失敗するのはその呼び出しです。
• 上記のリセットとは別に、Codex ではブラウザー自体が停止する場合があります。 Browser is not available: <name> または No browser is available は、ハンドルではなくアプリ内ブラウザーのプロセスが停止したことを意味します。呼び出しで復旧させることはできません。2026-09-09（01a0869c）の計測では、アプリ上ではタブが開いているように見える状態で、cua.getTab、cua.createBrowserTab、cua.getBrowser({ url }) がいずれも 17 分間失敗し続けました。タブが表示されていても、ブリッジが動作している証拠にはなりません。2 回目の失敗後は中止してください。アプリ内ブラウザーを開き直す必要があることをユーザーに伝えるか、サーバー側の機能が必要な場合はアプリ独自の MCP サーバーに切り替えてください。ここで高くつく間違いは、再試行することであり、復旧方法を間違えることではありません。
• Claude Code の preview_start と navigate は、ページが読み込まれていても、ほぼすべての初回読み込みで「denied or failed」と報告します。ナビゲーションを再試行せず、tabs_context または get_page_text を確認してください。

リクエストを実行する

1. 状態に依存する作業では、現在のオブジェクト、その ID、選択範囲を確認するため、画面を一度読み取ります。リクエストにすでに ID が含まれている場合は省略します。
2. 名前でツールを選びます。ページのツール一覧とアプリ独自の MCP instructions が索引です。推測せず、それらを読みます。画面の読み取りでツール名と引数がすでに分かっている場合は、そのまま呼び出します。ツールの一覧表示や説明の確認は、使い慣れていないアプリや引数が確定していない場合に行うもので、編集のたびに儀式のように行うものではありません。
3. 正確な ID を指定して、最小限の変更を一度だけ実行します。テキストの場合は、選択された値を正確に使った文字列の置換を一度だけ行い、スキーマで指定できる場合は expectedMatches: 1 を設定します。関係のない内容は変更しません。
4. 変更した項目を読み戻すか、新しい内容が反映されているハッシュまたは ID が変更結果に含まれている場合は、それを信頼してから成功を報告します。書き込み後にページは自動で再描画されます。読み戻しで確認できた内容を確かめるために、再読み込み、スクリーンショットの撮影、待機を行わないでください。

結果に nextRequiredAction が含まれている場合、次に使うツールが指定されています。それに従ってください。

リクエスト全体を担うモデルとして対応してください。「スライドを作成して」「ToDo アプリを設計して」「ランディングページを作って」「フォームの草案を作って」という依頼では、自分で内容を作成し、アプリ独自の作成・更新ツールを使って保存します。作成をアプリ内蔵のエージェントに任せてはいけません。また、説明にアプリ内でユーザーの回答を待つよう記載されたツールは呼び出さないでください。その回答はアプリ内チャットに送られるものであり、あなたには届きません。名前付きのツールで作業できる場合は、汎用の ask_app を呼び出さないでください。判断が本当に必要な場合は、自分のチャットで質問し、明示したデフォルトを適用して作業を続けます。

「これ」「選択したテキスト」、カーソル、または単独で指定されたフィールドは、対象を絞った編集として扱います。画面を一度読み取り、変更を一度行い、対象を絞って読み戻します。対象範囲は選択範囲ではなく、ユーザーの言葉に従います。「このテキスト」は選択範囲を指しますが、「このスライド」「この画面」「このセクション」は、たまたまテキストが選択されていても、現在の項目全体を指します。

スタイルを変更する場合（ダークモード、新しいパレット、「ほかの項目に合わせる」など）、編集対象は複数ある項目のうちの一つであり、ユーザーはほかの項目と統一された見た目を期待しています。まず共通スタイルを読み取り、その値を再利用します。また、構造的なスタイル変更の前に隣接するソースファイルを開くのと同じように、実在する隣接項目を一つ読み取ります。色の集計で分かるのは色とフォントであり、間隔や要素の順序ではありません。ユーザーから求められた場合に限り、ドキュメントでまだ使われていない色やフォントを導入します。

エラー

• 登録中の場合：ページを離れて少し待ち、もう一度呼び出します。
• ページが準備完了と表示しているのにツールが見つからない場合：そのページには本当に存在しません。問題を報告する前に、その操作を担う複合ツールがないかツール一覧を確認します。
• 検証メッセージまたは契約エラーメッセージでフィールドや値が示された場合：引数を修正し、一度だけ再試行します。
• Internal server error はサーバー側の障害であり、引数の問題ではありません。最大一度だけ再試行し、その後はツール、引数、リクエスト ID があればそれも報告し、書き込みが反映されなかったことを伝えます。書き込みが失敗したのに完了したと報告してはいけません。また、ツールの失敗を理由に UI オートメーションへ切り替えてはいけません。
• 保留中の場合：次の評価で結果を読み取ります。書き込みを再送信してはいけません。

MCP が利用できない場合

検出を一度行い、独立した評価で一度確認した後もホストブリッジとページ API のどちらも利用できない場合は、状態を変更する UI 操作を行う前に中止します。ページが WebMCP を通知していたかどうか、またどのホスト機能が不足しているかを伝えます。/webmcp からクリック、入力、ドラッグ、キーボード操作へ切り替えてはいけません。この特定の操作で UI オートメーションを使うよう明示的に求められた場合に限り、例外とします。ツール一覧の取得失敗、ツールからの応答、またはキューに登録されたタスクは、編集が完了した証拠にはなりません。

Agent-Native の追加機能

これまでの内容はすべて汎用的です。このセクションは Agent-Native アプリ向けの便宜的な機能であり、ほかのサイトには適用されません。

エイリアス。 先頭のトークンが単独の場合、URL の処理前にこのリストを使って解決されます。明示的な URL とホスト名は変更されず、そのまま渡されます。calendar、content、 plan、slides、clips、brain、analytics、mail、dispatch、forms、 design、assets、crm、macros は <name>.agent-native.com に解決されます。factory は agent-native-factory.netlify.app に解決されます。chat は意図的に除外されています。

ページヘルパー。 Agent-Native のページでは、window.__agentNativeWebMcp も公開されます。これは document.modelContext をラップし、準備状態と部分的なレジストリ状態、ツールのフィルター、評価処理の終了後も継続する呼び出しを追加します。これは当社独自のもので、WebMCP の一部ではありません。ほかのサイトにはないため、依存する前に存在を確認し、存在しないことを「このページにはツールがない」という意味に決して解釈しないでください。

const an = window.__agentNativeWebMcp;
await an.ready();                              // { state, registered, total }
await an.tools("slide");                       // [{ name, description, required, readOnly }]
await an.describe("update-slide");
await an.call("view-screen", {}, { waitMs: 2000 });
an.result(id);                                 // for { state: "pending", id }

call は、waitMs 以内に処理が完了しない場合、{ state: "pending", id } を返します。呼び出しはページ内で実行され続けます。Codex の約 3 秒の CDP 上限内で読み取りやほとんどの書き込みを同じ評価内で完了させるには、{ waitMs: 2000 } を渡してください。デフォルトでは、すべての呼び出しに result() の読み取りを組み合わせないでください。

値が undefined の場合、登録はまだ開始されていません。ページからサインアウトしているか、読み込み中か、古いデプロイを使用しています。上記の document.modelContext を使用してください。

ネイティブコネクター。 ホストにアプリが独自の MCP サーバーとしてすでに設定されており、そのツールが利用できる場合は、サーバーを介する処理ではそれらを優先してください。このトランスポートは、ブラウザーまたはホストをリセットしても維持されます。url のみが設定され、Authorization ヘッダーがないエントリーでは、ツールは 1 つも登録されません。これは MCP を利用できないアプリなのではなく、agent-native connect <url> が不足している状態です。ホスト型アプリでは、デフォルトで簡易版のコネクターカタログが提供され、ページローカルのツールはページ内でのみ利用できます。そのため、これはページの機能を補うものであり、置き換えるものではありません。