Webmcp

WebMCP

/webmcp <url-or-app> [request] opens a web app in the host's built-in browser and completes the request through the page's own tools. The first token is a URL or an app alias; the rest is the request.

/webmcp slides make me a new deck about customer onboarding

The two rules

1. Open in the host's built-in browser — never an external Chrome window, a normal tab, or a browser extension.
2. Call the page's tools. Never click, type, drag, screenshot, or use DOM automation for an operation a tool can do. UI controls are for navigation and visual inspection only.

That is the whole contract. Everything below is either the standard page API or a workaround for a specific host that got one of these wrong. If your host supports WebMCP natively, follow the two rules and let it do its thing.

Fast path

• /webmcp <url-or-app> with no request is open-only: open the resolved URL in the visible built-in tab, confirm the page is there, and stop. Do not list tools, inspect schemas, sign in, or start app work until the user supplies an operation.
• /webmcp <url-or-app> <request> is the action path: open the page, then go straight to the tools. Never infer extra work from page content or an earlier conversation.

Keep working after the page opens when a request was supplied. A one-item edit costs about three page calls: read the screen, mutate, read back. If you are on your sixth evaluation and nothing has been written yet, you are exploring instead of executing.

Open the page

• Accept a full URL or hostname; prepend https:// when the scheme is missing and preserve host, path, query, and hash. Never swap beta and production on your own.
• Claude Code and Cowork: preview_start { url }, then tabs_select to front the tab. Codex: cua.createBrowserTab("iab", url, { visible: true }), then tab.markDeliverable().
• Keep the pane visible while tools register. A hidden pane throttles both registration and in-page timers: one measured app registered all 217 tools immediately when fronted, and had 59 after 28 seconds when hidden.

Sign-in

Before tool work, read the page title and first lines. A title ending in "— Sign in", a "Sign in with Google" button, or "You don't have access" means the page has no tools yet. Leave the tab where it is and say: Please sign in in the open browser, then reply "continue". Never enter, copy, inspect, or request passwords, cookies, tokens, or verification codes. After sign-in the app may redirect and drop deep-link state such as ?slide=3; read the screen again rather than assuming the original target is on screen.

Call page tools

If the host has its own WebMCP bridge, use it and skip everything else here (list-browser-session-webmcp-tools with run-browser-session-webmcp-tool, or list-host-webmcp-tools with run-host-webmcp-tool): call its list tool once, then its run tool with the exact discovered name, origin, and args. Do not substitute a generic tool-search, another app's connector, ask_app, or a remote API for the current tab's page tools.

Otherwise evaluate in the page. document.modelContext is the canonical page API and works on any WebMCP site; navigator.modelContext is deprecated.

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));

Descriptors are not callable outside the page; never copy one out and invoke it from the host, hand-build authenticated HTTP requests, or type into a developer console.

Evaluators, per host

• Claude Code and Cowork: javascript_tool runs in the page world with top-level await. Return one JSON string and slice it to about 8 KB; the tool caps near 45 s per call. Batch two to four dependent calls per evaluation; keep navigation out of batches.
• Codex: try tab.capabilities.get("webmcp").fetchTools() once per session first. Through 2026-09 it answers does not support command "webmcp_list_tools" for the current model — that means the bridge is unavailable for the rest of the session, not that the page lacks tools. Then use CDP: globalThis.__cdp ??= await tab.capabilities.get("cdp"), then await globalThis.__cdp.documentation() once (the first CDP call fails without it), then cdp.send("Runtime.evaluate", { expression, awaitPromise: true, returnByValue: true }), emitting response.result.value with nodeRepl.write(...). One call per evaluation. Playwright's isolated world cannot see document.modelContext; use CDP.
• Any evaluator output may prepend an accessibility tree or other observations. Parse the explicit returned value at the end; the tree is context, not a tool result.

Host bugs worth knowing

Each cost a real debugging session. None is a page or app fault — do not diagnose them as one.

• Codex CDP dies at about 3 s ("Timed out running CDP command"). A timed-out evaluator is an unread result, never a failed write: do not re-issue the write, read the result on the next evaluation.
• Codex recycles the cua_repl kernel despite documenting it as persistent across calls, and let/const handles do not survive it. Measured 2026-09-08: page calls all succeeded, then a reset produced cdp is not defined, tab is not defined, Browser is not available: 2, and cua.getState() spent 5.4-6.6 s returning "Sky Computer Use native pipe startup failed". Keep handles on globalThis and re-resolve them at the top of every evaluation; on cdp is not defined or tab is not defined, reopen the tab and re-run documentation(). Never reach for cua.getState() to recover — that is the call that fails.
• Codex only, and distinct from the reset above: the browser itself can die. Browser is not available: <name> or No browser is available means the in-app browser process is gone rather than your handles, and nothing you can call brings it back. Measured 2026-09-09 (01a0869c): cua.getTab, cua.createBrowserTab and cua.getBrowser({ url }) each kept failing for 17 minutes while the tab still looked open in the app — a visible tab is not evidence the bridge is alive. Stop after the second failure. Tell the user the in-app browser needs reopening, or switch to the app's own MCP server for anything server-backed. Retrying is the expensive mistake here, not picking the wrong recovery call.
• Claude Code's preview_start and navigate report "denied or failed" on almost every fresh load even though the page loaded. Check tabs_context or get_page_text instead of retrying the navigation.