Skip to content

docs(fx): use fx’s supported integration setup #2977

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
shrey150 wants to merge 3 commits into
base: integrations/claude-plugin
Choose a base branch
from
+75 −113
Open

docs(fx): use fx’s supported integration setup #2977

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ae9f096
docs(fx): lead with the supported built-in MCP management setup
shrey150 Sep 17, 2026
28593fe
Merge branch 'integrations/claude-plugin' into integrations/fx-setup
shrey150 Sep 17, 2026
c0a4f84
style: format integration documentation and configuration
shrey150 Sep 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
168 changes: 58 additions & 110 deletions packages/docs/v4/integrations/fx.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

@cubic-dev-ai cubic-dev-ai Bot Sep 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: Custom agent: Stagehand docs prose guide

Lead with what the reader can do before explaining fx's integration mechanism. Start with connecting fx to a persistent Stagehand browser, then describe the built-in MCP client and /mcp add setup.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v4/integrations/fx.mdx, line 6:

<comment>Lead with what the reader can do before explaining fx's integration mechanism. Start with connecting fx to a persistent Stagehand browser, then describe the built-in MCP client and `/mcp add` setup.</comment>

<file context>
@@ -1,162 +1,110 @@
 ---
 
-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.
 
 <Note>
</file context>
Suggested change
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.
Connect fx to a persistent Stagehand browser through 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.

@cubic-dev-ai cubic-dev-ai Bot Sep 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: Name the launched process the Stagehand facade MCP server so users can match this stdio runtime to its tools and diagnostics.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v4/integrations/fx.mdx, line 6:

<comment>Name the launched process the Stagehand facade MCP server so users can match this stdio runtime to its tools and diagnostics.</comment>

<file context>
@@ -1,162 +1,110 @@
 ---
 
-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.
 
 <Note>
</file context>
Suggested change
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.
fx’s supported integration mechanism is its [built-in MCP client](https://fx.sh/docs/capabilities/mcp). Register the Stagehand facade MCP server over stdio with `/mcp add`; no separate fx marketplace plugin is needed.


<Note>
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.
</Note>

## 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

<Steps>
<Step title="Clone and build Stagehand">
```bash
git clone https://github.com/browserbase/stagehand.git
cd stagehand
pnpm install --frozen-lockfile
pnpm exec turbo run build \
--filter @browserbasehq/stagehand-integrations
```
</Step>
<Step title="Install and authenticate fx">
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).
</Step>
<Step title="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:
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.
</Step>
<Step title="Choose the browser">
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
```
</Step>
<Step title="Run a browser task">
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.
```
</Step>
</Steps>

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

@cubic-dev-ai cubic-dev-ai Bot Sep 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: When fx uses mcp_stagehand_run, model-authored JavaScript runs in the browser, but this guide no longer warns about the local-browser security boundary. Restore the Browserbase warning and security-boundary link before users apply this setup to untrusted tasks.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v4/integrations/fx.mdx, line 40:

<comment>When fx uses `mcp_stagehand_run`, model-authored JavaScript runs in the browser, but this guide no longer warns about the local-browser security boundary. Restore the Browserbase warning and security-boundary link before users apply this setup to untrusted tasks.</comment>

<file context>
@@ -1,162 +1,110 @@
-</Steps>
 
-## 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:
</file context>
Suggested change
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`.
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`.
<Warning>
`mcp_stagehand_run` executes model-authored JavaScript in the browser. Use Browserbase for untrusted tasks and review the [integration security boundary](/v4/integrations/overview#security-boundary).
</Warning>


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:

@cubic-dev-ai cubic-dev-ai Bot Sep 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: When BROWSERBASE_API_KEY is exported without STAGEHAND_BROWSER, the facade selects Browserbase, so this default statement is incorrect. Describe local Chrome as the default only when the Browserbase key is unset.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v4/integrations/fx.mdx, line 44:

<comment>When `BROWSERBASE_API_KEY` is exported without `STAGEHAND_BROWSER`, the facade selects Browserbase, so this default statement is incorrect. Describe local Chrome as the default only when the Browserbase key is unset.</comment>

<file context>
@@ -1,162 +1,110 @@
-- `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.
</file context>
Suggested change
Local Chrome is the default. To use Browserbase, export its credential before starting fx:
Local Chrome is used when `BROWSERBASE_API_KEY` is unset. 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

@cubic-dev-ai cubic-dev-ai Bot Sep 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: When users choose the unreleased source build, this section invokes pnpm without requiring or installing it. Add the repository-pinned pnpm 11.10.0 prerequisite for the source path.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/v4/integrations/fx.mdx, line 92:

<comment>When users choose the unreleased source build, this section invokes `pnpm` without requiring or installing it. Add the repository-pinned `pnpm 11.10.0` prerequisite for the source path.</comment>

<file context>
@@ -1,162 +1,110 @@
+```bash
+git clone https://github.com/browserbase/stagehand.git
+cd stagehand
+pnpm install --frozen-lockfile
+pnpm exec turbo run build --filter @browserbasehq/stagehand-integrations

</file context>


</details>

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

<Warning>
`run` executes model-authored JavaScript in the browser. Use Browserbase for untrusted tasks and review the [integration security boundary](/v4/integrations/overview#security-boundary).
</Warning>
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.

<Card title="fx integration source" icon="github" href="https://github.com/browserbase/stagehand/tree/main/packages/integrations/fx">
Read the MCP config template, project limits, and Stagehand tool guidance.
Read the MCP profile template and source-example guidance.
</Card>
11 changes: 11 additions & 0 deletions packages/integrations/fx/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,16 @@
# 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
Expand Down
9 changes: 6 additions & 3 deletions packages/integrations/fx/mcp.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
}
}
Loading