From ae9f0969e020e30784de4e1d7a43a61e33aa8265 Mon Sep 17 00:00:00 2001 From: Shrey Pandya Date: Thu, 17 Sep 2026 22:30:37 +0000 Subject: [PATCH 1/2] docs(fx): lead with the supported built-in MCP management setup --- packages/docs/v4/integrations/fx.mdx | 168 +++++++++------------------ packages/integrations/fx/README.md | 12 ++ packages/integrations/fx/mcp.json | 9 +- 3 files changed, 76 insertions(+), 113 deletions(-) diff --git a/packages/docs/v4/integrations/fx.mdx b/packages/docs/v4/integrations/fx.mdx index aab39643e..74fb28618 100644 --- a/packages/docs/v4/integrations/fx.mdx +++ b/packages/docs/v4/integrations/fx.mdx @@ -1,162 +1,110 @@ --- title: "fx" -description: "Give the fx coding agent persistent Stagehand browser tools over MCP/stdio." +description: "Connect fx to a persistent Stagehand browser using its built-in MCP configuration." --- -The fx integration connects the [fx coding agent](https://fx.sh) to the Stagehand facade MCP server over MCP/stdio. One MCP server process owns the browser, so navigation, authentication, and page state survive across tool calls. +fx’s supported integration mechanism is its [built-in MCP client](https://fx.sh/docs/capabilities/mcp). Register the Stagehand server with `/mcp add`; no separate fx marketplace plugin is needed. -Stagehand ships this experimental integration from the repository rather than publishing it as a standalone adapter. The example is verified against fx v0.0.3. +The package command below requires the first `@browserbasehq/stagehand-mcp@0.1.0` release. Until it is published, use the source server described below. The current fx MCP commands replace the manual, checkout-specific setup from the older v0.0.3 example. ## Prerequisites - Node.js 24 or newer -- pnpm 11.10.0 -- fx v0.0.3 -- A Vercel AI Gateway login or API key for fx -- A current Google Chrome installation for local browser mode +- A current [fx installation](https://fx.sh/docs/getting-started/installation), with `fx login` completed +- Local Chrome, or a Browserbase API key exported before starting fx -## Quickstart +## Add the server - - -```bash -git clone https://github.com/browserbase/stagehand.git -cd stagehand -pnpm install --frozen-lockfile -pnpm exec turbo run build \ - --filter @browserbasehq/stagehand-integrations -``` - - -Pin the tested version because fx is experimental: - -```bash -curl -fsSL https://fx.sh/setup.sh | bash -s -- v0.0.3 -fx login -``` - -You can export `AI_GATEWAY_API_KEY` instead of using `fx login`. See the [fx authentication guide](https://fx.sh/docs/getting-started/authentication). - - -fx reads MCP servers from `~/.fx/mcp.json`, not from the repository. Merge this entry into that file and replace the placeholder with the absolute path to your checkout: +At the fx prompt: -```json -{ - "mcp": { - "stagehand": { - "type": "stdio", - "command": [ - "node", - "/absolute/path/to/stagehand/packages/integrations/core/dist/facade/stdio-server.mjs", - "--max-screenshot-base64-bytes=60000" - ], - "required": true - } - } -} +```text +/mcp add stagehand npx -y @browserbasehq/stagehand-mcp@0.1.0 --max-screenshot-base64-bytes=60000 +/mcp list ``` -Start a new fx session after saving the file, or run `/mcp reload` in an open session. - - -The facade uses local Chrome by default. To use a disposable Browserbase browser instead: +`/mcp add` saves the server in your private MCP profile and reloads it. You can also run the equivalent command from your shell: ```bash -export STAGEHAND_BROWSER="browserbase" -export BROWSERBASE_API_KEY="your-browserbase-api-key" +fx mcp add stagehand npx -y @browserbasehq/stagehand-mcp@0.1.0 --max-screenshot-base64-bytes=60000 ``` - - -Start fx from the integration directory so it loads the included limits, project instructions, and Stagehand skill: -```bash -cd packages/integrations/fx -fx -``` - -At the prompt, enter: +Ask fx: ```text Use the Stagehand browser tools to open https://example.com, take a snapshot, -and report the heading with its snapshot ID. +and report the page title. ``` - - -## Tool discovery +The browser launches on the first tool call and persists across subsequent calls. fx can discover the tools through `capability_search`; direct tool selection remains available for the exact names `mcp_stagehand_run`, `mcp_stagehand_snapshot`, and `mcp_stagehand_screenshot`. -fx prefixes MCP tool names with the server name. The Stagehand tools appear as: +## Browser configuration -- `mcp_stagehand_run` -- `mcp_stagehand_snapshot` -- `mcp_stagehand_screenshot` +Local Chrome is the default. To use Browserbase, export its credential before starting fx: -fx v0.0.3 may return no matches for this server from `mcp_search_tools`. The integration's `AGENTS.md` and Stagehand skill tell fx to select these exact names directly. Run fx from `packages/integrations/fx` so it loads that guidance. +```bash +export STAGEHAND_BROWSER="browserbase" +export BROWSERBASE_API_KEY="your-browserbase-api-key" +fx +``` -There is no separate navigate or start tool. Navigate with `mcp_stagehand_run` and `page.goto`: +Keep credentials in the environment. Current fx versions inherit the parent environment and merge configured `environment` values into it. Older v0.0.3 builds replaced the environment; omit that object when using the older version. + +For manual profile configuration, merge this into `~/.fx/mcp.json`: ```json { - "code": "await page.goto('https://example.com'); return { url: await page.url(), title: await page.title() };" + "mcp": { + "stagehand": { + "type": "stdio", + "command": [ + "npx", + "-y", + "@browserbasehq/stagehand-mcp@0.1.0", + "--max-screenshot-base64-bytes=60000" + ], + "required": true, + "startup_timeout_ms": 120000, + "operation_timeout_ms": 120000 + } + } } ``` -The first browser tool call launches the browser lazily. Later calls reuse the same session. - -## Keep screenshots within fx's frame limit +Run `/mcp reload` after editing the profile. Current fx also supports project `.mcp.json` files; those servers remain disconnected until the user approves them through fx’s project trust flow. See [fx project configuration](https://fx.sh/docs/capabilities/mcp#project-configuration-and-trust). -MCP screenshots contain inline base64 image data. fx enforces its raw response-frame limit before it can parse or truncate a tool result, so a full-page PNG can close the MCP connection. +## Screenshot size -The configured `--max-screenshot-base64-bytes=60000` mode defaults screenshots to a viewport JPEG at quality 40. If a requested image is still too large, the facade retries progressively smaller viewport JPEGs. When no image fits, it returns a small tool error and keeps the MCP session alive. +Keep `--max-screenshot-base64-bytes=60000` in the command. It bounds inline screenshots to avoid response-frame failures on older fx builds, with progressively smaller JPEGs when necessary. If no image fits, the tool returns an error while preserving the connection. -Use an explicit viewport JPEG when you do not need full-page detail: +Prefer a viewport screenshot when full-page detail is unnecessary: ```json -{ - "type": "jpeg", - "quality": 40, - "fullPage": false -} +{ "type": "jpeg", "quality": 40, "fullPage": false } ``` -## Permissions +## Use an unreleased source build -Interactive fx sessions can approve tool calls when prompted. For non-interactive browser tasks, pre-allow the three Stagehand tools in `~/.fx/settings.json`: - -```json -{ - "permission": { - "mcp_stagehand_run": "allow", - "mcp_stagehand_snapshot": "allow", - "mcp_stagehand_screenshot": "allow", - "run_command": "deny" - } -} +```bash +git clone https://github.com/browserbase/stagehand.git +cd stagehand +pnpm install --frozen-lockfile +pnpm exec turbo run build --filter @browserbasehq/stagehand-integrations ``` -Denying `run_command` prevents a browser-only task from falling back to shell exploration if tool discovery fails. +Register the built server using an absolute path: -## Configuration +```text +/mcp add stagehand node /absolute/path/to/stagehand/packages/integrations/core/dist/facade/stdio-server.mjs --max-screenshot-base64-bytes=60000 +``` -| Variable or file | Purpose | -| --- | --- | -| `~/.fx/mcp.json` | User-global MCP server configuration. Repository-local MCP configuration is not loaded. | -| `packages/integrations/fx/.fx.json` | Raises fx's tool-result and agent-step limits for browser work. | -| `AI_GATEWAY_API_KEY` | Alternative to an interactive `fx login`. | -| `STAGEHAND_BROWSER` | Select `local` or `browserbase`. | -| `BROWSERBASE_API_KEY` | Required for Browserbase. | -| `BROWSERBASE_PROJECT_ID` | Optional Browserbase project ID. | -| `STAGEHAND_MODEL_NAME` | Optional model for Stagehand AI methods called inside `run`. | -| `STAGEHAND_MODEL_API_KEY` | Credential for `STAGEHAND_MODEL_NAME`. | +For fx v0.0.3, use the manual profile form with this same `node` command and server path. Run fx from `packages/integrations/fx` to load its legacy tool-selection guidance and limits. -Leave the MCP entry's `environment` field unset to inherit exported variables. If you add an `environment` object, fx replaces the child environment rather than merging it, so include `PATH` and every variable the facade needs. +## Manage the integration - -`run` executes model-authored JavaScript in the browser. Use Browserbase for untrusted tasks and review the [integration security boundary](/v4/integrations/overview#security-boundary). - +Use `/mcp list` to inspect connection status, `/mcp reload` to apply changes, and `/mcp remove stagehand` to remove the server. Keep the server connected for the full task; restarting it resets the browser and snapshot IDs. - Read the MCP config template, project limits, and Stagehand tool guidance. + Read the MCP profile template and source-example guidance. diff --git a/packages/integrations/fx/README.md b/packages/integrations/fx/README.md index 808e7b2e4..4a4a361e2 100644 --- a/packages/integrations/fx/README.md +++ b/packages/integrations/fx/README.md @@ -1,5 +1,17 @@ # fx + Stagehand facade over MCP/stdio +## Current fx setup + +fx has a built-in MCP client. After the first `@browserbasehq/stagehand-mcp@0.1.0` release, register Stagehand from the fx prompt: + +```text +/mcp add stagehand npx -y @browserbasehq/stagehand-mcp@0.1.0 --max-screenshot-base64-bytes=60000 +/mcp list +``` + +This uses [fx’s supported MCP management flow](https://fx.sh/docs/capabilities/mcp), with no separate marketplace plugin. The included `mcp.json` is a current profile template. The older v0.0.3 source workflow below is retained for development before the npm release; substitute its built server path when using that workflow. + + [fx](https://fx.sh) consumes the Stagehand facade as a standard MCP server — no integration code, just an entry in fx's user-global MCP config. This directory ships the config template, a project config that sizes fx's limits for browser work, and project instructions plus a skill diff --git a/packages/integrations/fx/mcp.json b/packages/integrations/fx/mcp.json index be1b5bdfc..1b21fe4be 100644 --- a/packages/integrations/fx/mcp.json +++ b/packages/integrations/fx/mcp.json @@ -3,11 +3,14 @@ "stagehand": { "type": "stdio", "command": [ - "node", - "/absolute/path/to/stagehand/packages/integrations/core/dist/facade/stdio-server.mjs", + "npx", + "-y", + "@browserbasehq/stagehand-mcp@0.1.0", "--max-screenshot-base64-bytes=60000" ], - "required": true + "required": true, + "startup_timeout_ms": 120000, + "operation_timeout_ms": 120000 } } } From c0a4f843ce99729b0aead977e120495bba4e8778 Mon Sep 17 00:00:00 2001 From: Shrey Pandya Date: Thu, 17 Sep 2026 22:33:39 +0000 Subject: [PATCH 2/2] style: format integration documentation and configuration --- packages/integrations/fx/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/integrations/fx/README.md b/packages/integrations/fx/README.md index 4a4a361e2..5c838c9bb 100644 --- a/packages/integrations/fx/README.md +++ b/packages/integrations/fx/README.md @@ -11,7 +11,6 @@ fx has a built-in MCP client. After the first `@browserbasehq/stagehand-mcp@0.1. This uses [fx’s supported MCP management flow](https://fx.sh/docs/capabilities/mcp), with no separate marketplace plugin. The included `mcp.json` is a current profile template. The older v0.0.3 source workflow below is retained for development before the npm release; substitute its built server path when using that workflow. - [fx](https://fx.sh) consumes the Stagehand facade as a standard MCP server — no integration code, just an entry in fx's user-global MCP config. This directory ships the config template, a project config that sizes fx's limits for browser work, and project instructions plus a skill