Browserbase MCP Server for Windsurf: Setup & Config

What you can do with Browserbase in Windsurf

Use a compact browser toolset with a hosted starting point and configurable self-hosted alternative.

• Navigate and act on live pages using instructions.
• Extract page data through Stagehand-backed automation.

Before you start: Browserbase in Windsurf

• An MCP-compatible client
• npx for local npm execution
• Browserbase credentials and a model key for self-hosted execution

The command is the self-hosted stdio option. The remote URL uses Streamable HTTP and is the README's recommended setup. Self-hosted custom models use --modelName and --modelApiKey.

Browserbase Windsurf configuration

1. Choose Windsurf configuration scope

   For Browserbase MCP Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add Browserbase MCP Server to Windsurf

   Use the mcp-server-browserbase entry below in mcpServers. Keep Browserbase MCP Server's documented stdio connection fields and your other Windsurf entries.

3. Check Browserbase MCP Server in Windsurf

   Browserbase MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "mcp-server-browserbase": {
      "command": "npx",
      "args": [
        "@browserbasehq/mcp"
      ],
      "env": {
        "BROWSERBASE_API_KEY": "<your Browserbase API key>",
        "BROWSERBASE_PROJECT_ID": "<your Browserbase project ID>",
        "GEMINI_API_KEY": "<your Gemini API key for the default model>"
      }
    }
  }
}

Browserbase tools available to Windsurf

Browserbase's stored tool list documents 6 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

start

After refreshing Browserbase in Windsurf settings, check Cascade's tool list for start.

end

After refreshing Browserbase in Windsurf settings, check Cascade's tool list for end.

navigate

After refreshing Browserbase in Windsurf settings, check Cascade's tool list for navigate.

Open a URL in the session browser.

act

After refreshing Browserbase in Windsurf settings, check Cascade's tool list for act.

observe

After refreshing Browserbase in Windsurf settings, check Cascade's tool list for observe.

Identify page elements relevant to an interaction instruction.

extract

After refreshing Browserbase in Windsurf settings, check Cascade's tool list for extract.

Retrieve page data, optionally guided by an instruction.

Browserbase: full stored tool descriptions

Troubleshooting Browserbase in Windsurf

• Check npx @browserbasehq/mcp (Node.js/npm) on the machine running Windsurf's MCP integration for Browserbase MCP Server; refresh MCP and inspect Cascade's tools.
• Check BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID, GEMINI_API_KEY for Browserbase MCP Server; do not bypass a Windsurf permission error with a broad administrator token.
• Browserbase MCP Server uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Self-hosted setup requires Browserbase credentials and model authentication.
• Known limitation: Custom models require a separate provider key.
• Known limitation: Verified Identity is restricted to Scale plan users.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions