From 8e0e073b36cce7892db0702e01ac49bd0008bfa4 Mon Sep 17 00:00:00 2001 From: Shrey Pandya Date: Thu, 17 Sep 2026 22:24:18 +0000 Subject: [PATCH 1/4] feat(codex): distribute Stagehand as a repository marketplace plugin --- .agents/plugins/marketplace.json | 20 +++++++++ packages/docs/v4/integrations/codex.mdx | 47 +++++++++++---------- packages/integrations/codex/README.md | 10 +++++ packages/integrations/codex/config.toml | 16 +++---- plugins/stagehand/.codex-plugin/plugin.json | 27 ++++++++++++ plugins/stagehand/.mcp.json | 20 +++++++++ plugins/stagehand/README.md | 10 +++++ 7 files changed, 117 insertions(+), 33 deletions(-) create mode 100644 .agents/plugins/marketplace.json create mode 100644 plugins/stagehand/.codex-plugin/plugin.json create mode 100644 plugins/stagehand/.mcp.json create mode 100644 plugins/stagehand/README.md diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 000000000..2120ece36 --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,20 @@ +{ + "name": "browserbase-stagehand", + "interface": { + "displayName": "Browserbase Stagehand" + }, + "plugins": [ + { + "name": "stagehand", + "source": { + "source": "local", + "path": "./plugins/stagehand" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + } + ] +} diff --git a/packages/docs/v4/integrations/codex.mdx b/packages/docs/v4/integrations/codex.mdx index d2b110baf..2c4d859b6 100644 --- a/packages/docs/v4/integrations/codex.mdx +++ b/packages/docs/v4/integrations/codex.mdx @@ -3,20 +3,35 @@ title: "Codex" description: "Give a Codex agent persistent Stagehand browser tools over MCP/stdio." --- -The Codex integration gives a Codex agent a persistent Stagehand browser it can drive with `run`, `snapshot`, and `screenshot`. A Codex SDK thread connects to the Stagehand facade MCP server over MCP/stdio, and one server process owns the browser, so page state survives across tool calls. +The Codex plugin gives a Codex agent a persistent Stagehand browser it can drive with `run`, `snapshot`, and `screenshot`. Codex connects to the Stagehand facade MCP server over MCP/stdio, and one server process owns the browser, so page state survives across tool calls. -Stagehand ships this experimental integration from the repository rather than publishing it as a standalone adapter. +The plugin requires the first `@browserbasehq/stagehand-mcp@0.1.0` npm release. Until it is published, use the source example below. -## Prerequisites +## Install the plugin + +```bash +codex plugin marketplace add browserbase/stagehand +codex plugin add stagehand@browserbase-stagehand +``` + +Restart Codex or open a new task after installing. The plugin uses Codex’s [repository marketplace format](https://developers.openai.com/plugins/build/plugins#add-a-marketplace-from-the-cli); it is not a listing in the universal public directory. + +Requires Node.js 24+, an existing Codex login, and local Chrome. To use Browserbase, export `BROWSERBASE_API_KEY` before starting Codex. The plugin passes browser configuration through `env_vars`, so credentials stay out of its manifest. It sets longer startup and tool timeouts for browser work. + +Ask Codex to open `https://example.com`, take a snapshot, and report its title. The plugin provides `run`, `snapshot`, and `screenshot` over one persistent MCP connection. + +The SDK example below is for embedding Codex in an application. + +## Source example prerequisites - Node.js 24 or newer - pnpm 11.10.0 - An OpenAI API key or an existing `codex login` for the example agent - A current Google Chrome installation for local browser mode -## Quickstart +## Run the SDK example from source @@ -74,32 +89,20 @@ The example starts one Codex thread against one facade MCP server, with raised M The MCP child receives only Stagehand and Browserbase configuration plus the process values required to launch Node. The host's model credential remains in the Codex process. -## Connect a running Codex CLI +## Connect the CLI without a plugin -The same server works from the Codex CLI. Merge the package's `config.toml` into `~/.codex/config.toml`, adjusting the path to your checkout: +For a locally built server, merge this into your Codex configuration and adjust the server path: ```toml [mcp_servers.stagehand] command = "node" args = ["/absolute/path/to/stagehand/packages/integrations/core/dist/facade/stdio-server.mjs"] - -[mcp_servers.stagehand.env] -STAGEHAND_BROWSER = "browserbase" -BROWSERBASE_API_KEY = "bb_live_..." -BROWSERBASE_PROJECT_ID = "..." -``` - -Codex does not expand shell variables in config values; paste the real keys or generate this file from your environment. For a one-off run, pass the same values as `codex exec` overrides: - -```bash -codex exec \ - -c mcp_servers.stagehand.command=node \ - -c 'mcp_servers.stagehand.args=["/absolute/path/to/packages/integrations/core/dist/facade/stdio-server.mjs"]' \ - -c 'mcp_servers.stagehand.env={ STAGEHAND_BROWSER = "browserbase", BROWSERBASE_API_KEY = "bb_live_..." }' \ - "your instruction" +env_vars = ["STAGEHAND_BROWSER", "BROWSERBASE_API_KEY", "BROWSERBASE_PROJECT_ID", "STAGEHAND_MODEL_NAME", "STAGEHAND_MODEL_API_KEY"] +startup_timeout_sec = 120 +tool_timeout_sec = 120 ``` -These overrides merge with any `[mcp_servers]` already in your `~/.codex/config.toml` rather than replacing them; set `CODEX_HOME` to a scratch directory if you need isolation. +Export credentials before starting Codex. Avoid keeping real keys in `config.toml` or command-line overrides. Do not enable both this server and the plugin for the same task; each starts its own browser. `run` executes model-authored JavaScript in the browser. Use Browserbase for untrusted tasks and review the [integration security boundary](/v4/integrations/overview#security-boundary). diff --git a/packages/integrations/codex/README.md b/packages/integrations/codex/README.md index 8b1dfc472..1bddb5f0a 100644 --- a/packages/integrations/codex/README.md +++ b/packages/integrations/codex/README.md @@ -1,5 +1,15 @@ # Codex SDK + Stagehand facade over MCP/stdio +## Install the Codex plugin + +```sh +codex plugin marketplace add browserbase/stagehand +codex plugin add stagehand@browserbase-stagehand +``` + +Requires the first `@browserbasehq/stagehand-mcp@0.1.0` release. The [repository plugin](../../../plugins/stagehand) supplies the MCP configuration, browser environment allowlist, and timeouts. Restart Codex after installing. Keep browser credentials in the environment. The SDK example below remains available for programmatic use. + + A runnable example embedding a Codex agent via `@openai/codex-sdk`, with the Stagehand facade (`run` / `snapshot` / `screenshot`) mounted as a stdio MCP server through the SDK's config override — install, export keys, one line to run. The SDK spawns the bundled Codex runtime; diff --git a/packages/integrations/codex/config.toml b/packages/integrations/codex/config.toml index 86c0b95f4..eac8eaf16 100644 --- a/packages/integrations/codex/config.toml +++ b/packages/integrations/codex/config.toml @@ -1,14 +1,8 @@ -# Codex CLI MCP server entry for the Stagehand facade. -# Merge this block into ~/.codex/config.toml (or pass per-invocation with -# `codex -c`), adjusting the absolute path to your checkout. - +# Optional direct CLI configuration; prefer the repository marketplace plugin. +# Adjust the server path and export credentials before starting Codex. [mcp_servers.stagehand] command = "node" args = ["/absolute/path/to/stagehand/packages/integrations/core/dist/facade/stdio-server.mjs"] - -[mcp_servers.stagehand.env] -STAGEHAND_BROWSER = "browserbase" -# Codex does not expand shell variables in config values; paste the real keys -# or generate this file from your environment. -BROWSERBASE_API_KEY = "bb_live_..." -BROWSERBASE_PROJECT_ID = "..." +env_vars = ["STAGEHAND_BROWSER", "BROWSERBASE_API_KEY", "BROWSERBASE_PROJECT_ID", "STAGEHAND_MODEL_NAME", "STAGEHAND_MODEL_API_KEY"] +startup_timeout_sec = 120 +tool_timeout_sec = 120 diff --git a/plugins/stagehand/.codex-plugin/plugin.json b/plugins/stagehand/.codex-plugin/plugin.json new file mode 100644 index 000000000..c12f9b7d7 --- /dev/null +++ b/plugins/stagehand/.codex-plugin/plugin.json @@ -0,0 +1,27 @@ +{ + "name": "stagehand", + "version": "0.1.0", + "description": "Give Codex a persistent Stagehand browser with run, snapshot, and screenshot tools.", + "author": { + "name": "Browserbase" + }, + "skills": "./skills/", + "interface": { + "displayName": "Stagehand", + "shortDescription": "Persistent browser tools for Codex", + "developerName": "Browserbase", + "category": "Developer Tools", + "longDescription": "Control a persistent browser using Stagehand run, snapshot, and screenshot tools.", + "defaultPrompt": [ + "Open https://example.com and report its title." + ], + "capabilities": [ + "Read", + "Write" + ] + }, + "mcpServers": "./.mcp.json", + "homepage": "https://docs.stagehand.dev/v4/integrations/codex", + "repository": "https://github.com/browserbase/stagehand", + "license": "MIT" +} diff --git a/plugins/stagehand/.mcp.json b/plugins/stagehand/.mcp.json new file mode 100644 index 000000000..6bd024b10 --- /dev/null +++ b/plugins/stagehand/.mcp.json @@ -0,0 +1,20 @@ +{ + "mcpServers": { + "stagehand": { + "command": "npx", + "args": [ + "-y", + "@browserbasehq/stagehand-mcp@0.1.0" + ], + "env_vars": [ + "STAGEHAND_BROWSER", + "BROWSERBASE_API_KEY", + "BROWSERBASE_PROJECT_ID", + "STAGEHAND_MODEL_NAME", + "STAGEHAND_MODEL_API_KEY" + ], + "startup_timeout_sec": 120, + "tool_timeout_sec": 120 + } + } +} diff --git a/plugins/stagehand/README.md b/plugins/stagehand/README.md new file mode 100644 index 000000000..07e4238be --- /dev/null +++ b/plugins/stagehand/README.md @@ -0,0 +1,10 @@ +# Stagehand for Codex + +```sh +codex plugin marketplace add browserbase/stagehand +codex plugin add stagehand@browserbase-stagehand +``` + +Restart Codex after installation, or open a new task. Requires Node.js 24+, local Chrome or an exported `BROWSERBASE_API_KEY`, and the initial `@browserbasehq/stagehand-mcp@0.1.0` release. This is a repository marketplace plugin, not a claim of listing in OpenAI’s public directory. + +The plugin bundles MCP configuration and forwards only the listed browser configuration variables. Keep credentials in your environment instead of the manifest. It preserves one browser across `run`, `snapshot`, and `screenshot` calls. From d87715b815a754fafaa89e1b1a7f8576d538ae15 Mon Sep 17 00:00:00 2001 From: Shrey Pandya Date: Thu, 17 Sep 2026 22:29:14 +0000 Subject: [PATCH 2/4] docs(integrations): classify supported host setup routes --- packages/docs/v4/integrations/overview.mdx | 18 +++++++++++++++++- plugins/stagehand/.codex-plugin/plugin.json | 1 - 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/packages/docs/v4/integrations/overview.mdx b/packages/docs/v4/integrations/overview.mdx index 9aaee8545..4446f58ed 100644 --- a/packages/docs/v4/integrations/overview.mdx +++ b/packages/docs/v4/integrations/overview.mdx @@ -7,9 +7,25 @@ description: "Connect Claude Code, Codex, CrewAI, Deep Agents, Eve, Mastra, fx, Each integration gives your agent one persistent browser and three tools: `run`, `snapshot`, and `screenshot`. Your agent decides how to navigate and interact while Stagehand manages the browser session. -Stagehand ships these experimental integrations from the monorepo and does not publish the adapters or shared integration package as standalone packages. +Distribution follows each host’s supported extension mechanism. Consult the host guide for release availability and source-testing instructions. The shared Core workspace package remains private. +## Supported setup routes + +| Host | Preferred integration mechanism | +| --- | --- | +| Claude Code | A Claude Code marketplace plugin that registers the Stagehand MCP server. | +| Codex | A Codex repository marketplace plugin that registers the Stagehand MCP server. | +| Pi | A native Pi extension installed with Pi’s package manager. | +| Eve | A native Eve extension mounted in the agent. | +| Mastra | Mastra’s official `MCPClient`, attached as agent tools. | +| Vercel AI SDK | The official `@ai-sdk/mcp` client, attached to the tool loop. | +| CrewAI | CrewAI’s official `MCPServerAdapter`; the source example adds screenshot-file handling. | +| Deep Agents | LangChain MCP adapters with a persistent session, or native tools for Managed Deep Agents. | +| fx | fx’s built-in MCP client and `/mcp add` configuration flow. | + +The first four hosts provide plugin or extension distribution. The remaining guides use the host’s supported tool APIs; they do not require a separate marketplace plugin. The portable MCP setups use the same server package and preserve the same browser tool contract. + ## Choose an integration diff --git a/plugins/stagehand/.codex-plugin/plugin.json b/plugins/stagehand/.codex-plugin/plugin.json index c12f9b7d7..f4f924df7 100644 --- a/plugins/stagehand/.codex-plugin/plugin.json +++ b/plugins/stagehand/.codex-plugin/plugin.json @@ -5,7 +5,6 @@ "author": { "name": "Browserbase" }, - "skills": "./skills/", "interface": { "displayName": "Stagehand", "shortDescription": "Persistent browser tools for Codex", From bf7f11181a63ab9d79bf44748f0c58c95bdbf720 Mon Sep 17 00:00:00 2001 From: Shrey Pandya Date: Thu, 17 Sep 2026 22:33:27 +0000 Subject: [PATCH 3/4] style: format integration documentation and configuration --- packages/integrations/codex/README.md | 1 - packages/integrations/codex/config.toml | 8 +++++++- plugins/stagehand/.codex-plugin/plugin.json | 9 ++------- plugins/stagehand/.mcp.json | 5 +---- 4 files changed, 10 insertions(+), 13 deletions(-) diff --git a/packages/integrations/codex/README.md b/packages/integrations/codex/README.md index 1bddb5f0a..4f790b17b 100644 --- a/packages/integrations/codex/README.md +++ b/packages/integrations/codex/README.md @@ -9,7 +9,6 @@ codex plugin add stagehand@browserbase-stagehand Requires the first `@browserbasehq/stagehand-mcp@0.1.0` release. The [repository plugin](../../../plugins/stagehand) supplies the MCP configuration, browser environment allowlist, and timeouts. Restart Codex after installing. Keep browser credentials in the environment. The SDK example below remains available for programmatic use. - A runnable example embedding a Codex agent via `@openai/codex-sdk`, with the Stagehand facade (`run` / `snapshot` / `screenshot`) mounted as a stdio MCP server through the SDK's config override — install, export keys, one line to run. The SDK spawns the bundled Codex runtime; diff --git a/packages/integrations/codex/config.toml b/packages/integrations/codex/config.toml index eac8eaf16..fc3905aec 100644 --- a/packages/integrations/codex/config.toml +++ b/packages/integrations/codex/config.toml @@ -3,6 +3,12 @@ [mcp_servers.stagehand] command = "node" args = ["/absolute/path/to/stagehand/packages/integrations/core/dist/facade/stdio-server.mjs"] -env_vars = ["STAGEHAND_BROWSER", "BROWSERBASE_API_KEY", "BROWSERBASE_PROJECT_ID", "STAGEHAND_MODEL_NAME", "STAGEHAND_MODEL_API_KEY"] +env_vars = [ + "STAGEHAND_BROWSER", + "BROWSERBASE_API_KEY", + "BROWSERBASE_PROJECT_ID", + "STAGEHAND_MODEL_NAME", + "STAGEHAND_MODEL_API_KEY", +] startup_timeout_sec = 120 tool_timeout_sec = 120 diff --git a/plugins/stagehand/.codex-plugin/plugin.json b/plugins/stagehand/.codex-plugin/plugin.json index f4f924df7..8a495cbde 100644 --- a/plugins/stagehand/.codex-plugin/plugin.json +++ b/plugins/stagehand/.codex-plugin/plugin.json @@ -11,13 +11,8 @@ "developerName": "Browserbase", "category": "Developer Tools", "longDescription": "Control a persistent browser using Stagehand run, snapshot, and screenshot tools.", - "defaultPrompt": [ - "Open https://example.com and report its title." - ], - "capabilities": [ - "Read", - "Write" - ] + "defaultPrompt": ["Open https://example.com and report its title."], + "capabilities": ["Read", "Write"] }, "mcpServers": "./.mcp.json", "homepage": "https://docs.stagehand.dev/v4/integrations/codex", diff --git a/plugins/stagehand/.mcp.json b/plugins/stagehand/.mcp.json index 6bd024b10..16297076f 100644 --- a/plugins/stagehand/.mcp.json +++ b/plugins/stagehand/.mcp.json @@ -2,10 +2,7 @@ "mcpServers": { "stagehand": { "command": "npx", - "args": [ - "-y", - "@browserbasehq/stagehand-mcp@0.1.0" - ], + "args": ["-y", "@browserbasehq/stagehand-mcp@0.1.0"], "env_vars": [ "STAGEHAND_BROWSER", "BROWSERBASE_API_KEY", From cfe1e201469ee733d4fdaa180ad7f477311e7b46 Mon Sep 17 00:00:00 2001 From: Shrey Pandya Date: Thu, 17 Sep 2026 22:37:34 +0000 Subject: [PATCH 4/4] docs(codex): clarify facade packaging and model configuration --- packages/docs/v4/integrations/overview.mdx | 8 ++++---- plugins/stagehand/README.md | 2 ++ 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/packages/docs/v4/integrations/overview.mdx b/packages/docs/v4/integrations/overview.mdx index 4446f58ed..9ccc5ce77 100644 --- a/packages/docs/v4/integrations/overview.mdx +++ b/packages/docs/v4/integrations/overview.mdx @@ -14,17 +14,17 @@ Distribution follows each host’s supported extension mechanism. Consult the ho | Host | Preferred integration mechanism | | --- | --- | -| Claude Code | A Claude Code marketplace plugin that registers the Stagehand MCP server. | -| Codex | A Codex repository marketplace plugin that registers the Stagehand MCP server. | +| Claude Code | A Claude Code marketplace plugin that registers the Stagehand facade MCP server. | +| Codex | A Codex repository marketplace plugin that registers the Stagehand facade MCP server. | | Pi | A native Pi extension installed with Pi’s package manager. | | Eve | A native Eve extension mounted in the agent. | | Mastra | Mastra’s official `MCPClient`, attached as agent tools. | | Vercel AI SDK | The official `@ai-sdk/mcp` client, attached to the tool loop. | -| CrewAI | CrewAI’s official `MCPServerAdapter`; the source example adds screenshot-file handling. | +| CrewAI | Official `MCPServerAdapter` for portable setup; `MCPAdapt` with `CrewAIToolAdapter` for the source example’s screenshot files. | | Deep Agents | LangChain MCP adapters with a persistent session, or native tools for Managed Deep Agents. | | fx | fx’s built-in MCP client and `/mcp add` configuration flow. | -The first four hosts provide plugin or extension distribution. The remaining guides use the host’s supported tool APIs; they do not require a separate marketplace plugin. The portable MCP setups use the same server package and preserve the same browser tool contract. +The first four hosts provide plugin or extension distribution. The remaining guides use the host’s supported tool APIs; they do not require a separate marketplace plugin. Packaging varies between the portable facade MCP server, source builds, and the Python-native Deep Agents server. They preserve the same browser tool contract. ## Choose an integration diff --git a/plugins/stagehand/README.md b/plugins/stagehand/README.md index 07e4238be..11f5fec4a 100644 --- a/plugins/stagehand/README.md +++ b/plugins/stagehand/README.md @@ -8,3 +8,5 @@ codex plugin add stagehand@browserbase-stagehand Restart Codex after installation, or open a new task. Requires Node.js 24+, local Chrome or an exported `BROWSERBASE_API_KEY`, and the initial `@browserbasehq/stagehand-mcp@0.1.0` release. This is a repository marketplace plugin, not a claim of listing in OpenAI’s public directory. The plugin bundles MCP configuration and forwards only the listed browser configuration variables. Keep credentials in your environment instead of the manifest. It preserves one browser across `run`, `snapshot`, and `screenshot` calls. + +The MCP child receives `STAGEHAND_MODEL_NAME` and `STAGEHAND_MODEL_API_KEY` when you configure them; it does not receive Codex’s provider credential. Plain navigation, snapshots, and screenshots do not require a separate Stagehand model. See the [configuration guide](https://docs.stagehand.dev/v4/integrations/codex#configuration) for optional Stagehand model settings.