How to add Browserbase MCP (Stagehand) to Windsurf

Official Browserbase cloud-browser MCP built on Stagehand — natural-language act/extract/observe. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 15, 2026 · 3.0k★ · stdio · apikey · official

Windsurf config for Browserbase MCP (Stagehand)

npx -y @browserbasehq/mcp

{
  "mcpServers": {
    "browserbase-mcp-stagehand": {
      "command": "npx",
      "args": [
        "-y",
        "@browserbasehq/mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "<your-gemini-api-key>",
        "BROWSERBASE_API_KEY": "<your-browserbase-api-key>",
        "BROWSERBASE_PROJECT_ID": "<your-browserbase-project-id>"
      }
    }
  }
}

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Browserbase MCP (Stagehand) config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Browserbase MCP (Stagehand)'s tools become available to Cascade.

Before you start

Node.js 18+ (run via npx) — or use the hosted endpoint with no local runtime
A Browserbase API key and Project ID from your Browserbase dashboard (browserbase.com)
A model API key for Stagehand — defaults to Google Gemini (GEMINI_API_KEY); custom models (Claude, GPT-4o) need the matching key via --modelApiKey

What Browserbase MCP (Stagehand) can do in Windsurf

start

Create or reuse a Browserbase cloud session

navigate

Navigate the session's browser to a URL

act

Perform an action on the page described in natural language (Stagehand)

observe

Identify actionable elements on the page using a natural-language query

extract

Extract structured data from the current page, with optional instructions/schema

end

Close the current Browserbase session

multi_browserbase_stagehand_session_create

Create an additional independent session for parallel/multi-session automation

screenshot

Capture a screenshot of the cloud browser page

Security

Requires a Browserbase API key, project ID, and an LLM API key, all of which are billable cloud credentials — keep them in env, not in shared config. Natural-language actions run against live cloud sessions, so scope automation carefully when it touches authenticated or payment flows.

Browserbase MCP (Stagehand) + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Browserbase MCP (Stagehand) config there under the "mcpServers" key and restart the client.

Is Browserbase MCP (Stagehand) safe to use with Windsurf?

Is this the official Browserbase server?

Yes. It is maintained by Browserbase, Inc. and built on their Stagehand framework, licensed Apache-2.0.

What credentials do I need?

A Browserbase API key and Project ID (from your dashboard), plus a model API key for Stagehand — Gemini by default, or your own key for Claude/GPT models.

Do I have to self-host it?

No. Browserbase runs a hosted endpoint at https://mcp.browserbase.com/mcp where they cover the default Gemini model costs; self-hosting via `npx @browserbasehq/mcp` is the alternative.

View repo Full Browserbase MCP (Stagehand) page