Hyperbrowser MCP Server for Windsurf: Setup & Config

What you can do with Hyperbrowser in Windsurf

Pick it when an assistant needs both web extraction and a choice of cloud browser agents.

• Extract page content as Markdown or screenshots
• Crawl linked pages for content collection
• Create and manage persistent browser profiles

Before you start: Hyperbrowser in Windsurf

• npx
• A Hyperbrowser API key
• An MCP-compatible client

The README supplies client configurations for Cursor, Windsurf, and Claude Desktop. A source checkout can instead be built with npm and launched from dist/server.js.

Hyperbrowser Windsurf configuration

1. Choose Windsurf configuration scope

   For Hyperbrowser 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 Hyperbrowser MCP Server to Windsurf

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

3. Check Hyperbrowser MCP Server in Windsurf

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

{
  "mcpServers": {
    "mcp-hyperbrowserai": {
      "command": "npx",
      "args": [
        "-y",
        "hyperbrowser-mcp"
      ],
      "env": {
        "HYPERBROWSER_API_KEY": "<Hyperbrowser API key>"
      }
    }
  }
}

Hyperbrowser tools available to Windsurf

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

scrape_webpage

After refreshing Hyperbrowser in Windsurf settings, check Cascade's tool list for scrape_webpage.

crawl_webpages

After refreshing Hyperbrowser in Windsurf settings, check Cascade's tool list for crawl_webpages.

extract_structured_data

After refreshing Hyperbrowser in Windsurf settings, check Cascade's tool list for extract_structured_data.

browser_use_agent

After refreshing Hyperbrowser in Windsurf settings, check Cascade's tool list for browser_use_agent.

Run explicit browser tasks with the Browser Use cloud agent.

openai_computer_use_agent

After refreshing Hyperbrowser in Windsurf settings, check Cascade's tool list for openai_computer_use_agent.

Delegate general browser interactions to OpenAI computer use.

claude_computer_use_agent

After refreshing Hyperbrowser in Windsurf settings, check Cascade's tool list for claude_computer_use_agent.

search_with_bing

After refreshing Hyperbrowser in Windsurf settings, check Cascade's tool list for search_with_bing.

create_profile

After refreshing Hyperbrowser in Windsurf settings, check Cascade's tool list for create_profile.

Create a persistent Hyperbrowser profile.

delete_profile

After refreshing Hyperbrowser in Windsurf settings, check Cascade's tool list for delete_profile.

Remove a persistent Hyperbrowser profile.

list_profiles

After refreshing Hyperbrowser in Windsurf settings, check Cascade's tool list for list_profiles.

List persistent browser profiles with optional pagination.

Hyperbrowser: full stored tool descriptions

Troubleshooting Hyperbrowser in Windsurf

• Check npx hyperbrowser-mcp (Node.js/npm) on the machine running Windsurf's MCP integration for Hyperbrowser MCP Server; refresh MCP and inspect Cascade's tools.
• Check HYPERBROWSER_API_KEY for Hyperbrowser MCP Server; do not bypass a Windsurf permission error with a broad administrator token.
• Hyperbrowser MCP Server uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Requires a Hyperbrowser API key
• Known limitation: The MCP toolset exposes only a subset of Hyperbrowser API features
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions