fx - Stagehand

The fx integration connects the fx coding agent 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.

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.

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

Quickstart

Clone and build Stagehand

git clone https://github.com/browserbase/stagehand.git
cd stagehand
pnpm install --frozen-lockfile
pnpm exec turbo run build \
  --filter @browserbasehq/stagehand-integrations

Install and authenticate fx

Pin the tested version because fx is experimental:

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.

Configure the Stagehand MCP server

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:

{
  "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
    }
  }
}

Start a new fx session after saving the file, or run /mcp reload in an open session.

Choose the browser

The facade uses local Chrome by default. To use a disposable Browserbase browser instead:

export STAGEHAND_BROWSER="browserbase"
export BROWSERBASE_API_KEY="your-browserbase-api-key"

Run a browser task

Start fx from the integration directory so it loads the included limits, project instructions, and Stagehand skill:

cd packages/integrations/fx
fx

At the prompt, enter:

Use the Stagehand browser tools to open https://example.com, take a snapshot,
and report the heading with its snapshot ID.

Tool discovery

fx prefixes MCP tool names with the server name. The Stagehand tools appear as:

mcp_stagehand_run
mcp_stagehand_snapshot
mcp_stagehand_screenshot

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. There is no separate navigate or start tool. Navigate with mcp_stagehand_run and page.goto:

{
  "code": "await page.goto('https://example.com'); return { url: await page.url(), title: await page.title() };"
}

The first browser tool call launches the browser lazily. Later calls reuse the same session.

Keep screenshots within fx’s frame limit

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. 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. Use an explicit viewport JPEG when you do not need full-page detail:

{
  "type": "jpeg",
  "quality": 40,
  "fullPage": false
}

Permissions

Interactive fx sessions can approve tool calls when prompted. For non-interactive browser tasks, pre-allow the three Stagehand tools in ~/.fx/settings.json:

{
  "permission": {
    "mcp_stagehand_run": "allow",
    "mcp_stagehand_snapshot": "allow",
    "mcp_stagehand_screenshot": "allow",
    "run_command": "deny"
  }
}

Denying run_command prevents a browser-only task from falling back to shell exploration if tool discovery fails.

Configuration

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`.

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.

run executes model-authored JavaScript in the browser. Use Browserbase for untrusted tasks and review the integration security boundary.

fx integration source

Read the MCP config template, project limits, and Stagehand tool guidance.

First steps

The basics

Configuration

Integrations

Best practices

Migration guide

SDK reference

fx

Prerequisites

Quickstart

Tool discovery

Keep screenshots within fx’s frame limit

Permissions

Configuration

fx integration source

​Prerequisites

​Quickstart

​Tool discovery

​Keep screenshots within fx’s frame limit

​Permissions

​Configuration

fx integration source

Prerequisites

Quickstart

Tool discovery

Keep screenshots within fx’s frame limit

Permissions

Configuration