Windsurf

Windsurf Integration

Give Cascade, Windsurf's agent, live web access with CrawlForge MCP. One mcpServers entry in ~/.codeium/windsurf/mcp_config.json adds the server.

Prerequisites

Windsurf

Download from windsurf.com

Required

Node.js 18+

Install from nodejs.org

Required

API Key

Get from dashboard

Free

Get a CrawlForge API Key

The config below starts the server through npx, so nothing needs a global install—only a key.

Sign in from the terminal: the CLI opens a browser page where you approve a new key, then saves it to ~/.crawlforge/config.json.

Bash

npm install -g crawlforge-mcp-server
crawlforge login        # opens the browser approval page

Or copy a key from the dashboard and paste it into the config in the next step.

Tip: The CLI guide covers crawlforge login and the other ways to authenticate.

Configure Windsurf

Choose your preferred configuration method:

AOption A: Edit mcp_config.json

Open ~/.codeium/windsurf/mcp_config.json (%USERPROFILE%\.codeium\windsurf\mcp_config.json on Windows) and add the server:

~/.codeium/windsurf/mcp_config.jsonJson

{
  "mcpServers": {
    "crawlforge": {
      "command": "npx",
      "args": [
        "-y",
        "crawlforge-mcp-server@latest",
        "mcp"
      ],
      "env": {
        "CRAWLFORGE_API_KEY": "cf_live_your_api_key_here"
      }
    }
  }
}

Save the file, then press Refresh in the MCPs panel so Cascade picks up the change.

BOption B: Cascade panel

Click the MCPs icon in the Cascade toolbar and choose Configure to open the same file in the editor; paste the entry there and save.

Tip: Windsurf caps the number of MCP tools active at once, so trim the list with CRAWLFORGE_TOOL_GROUPS if you run several servers.

Set Your API Key

Replace cf_live_your_api_key_here with your key, or let the configurator fill it in.

Generate this config with your key: The MCP configurator fills in your key and outputs the exact JSON for Windsurf.

Limit the tool list (optional)

CrawlForge ships 31 tools. Set CRAWLFORGE_TOOL_GROUPS in the same env block to load only the groups you need, for example basic,search:

Json

"env": {
  "CRAWLFORGE_API_KEY": "cf_live_your_api_key_here",
  "CRAWLFORGE_TOOL_GROUPS": "basic,search"
}

Groups: basic, search, crawl, extract, batch, research, tracking, llmstxt, stealth, templates, scrape, agent.

Security: Never commit your API key to version control. Use environment variables or the config file.

Test the Integration

Open Cascade and confirm the server is running.

Open Cascade — press Cmd+L / Ctrl+L
Check the server — the MCPs panel lists crawlforge with its tools once it starts
Test a prompt — try one of the examples below; Cascade picks the CrawlForge tool itself

Example Prompts

"Search for the latest AI news"

"Extract all links from example.com"

"Crawl the documentation site and summarize it"

"Extract product prices from this e-commerce site"

See the full API reference for all 31 tools and their parameters.

Troubleshooting

Server not loading?

Check mcp_config.json is valid JSON
Ensure Node.js 18+ is installed: node --version
Press Refresh in the MCPs panel and read the error shown next to the server
Restart Windsurf completely

Authentication Errors?

Check the API key starts with cf_live_
Run crawlforge login to save a fresh key
Generate a new API key from the dashboard

Tools not appearing in Cascade?

Make sure the server toggle is enabled in the MCPs panel
Disable servers you are not using—Windsurf limits how many MCP tools can be active
Start a new Cascade conversation

Still having issues? Contact simon@crawlforge.dev with your Windsurf version, Node.js version, and the error shown in the MCPs panel.

Successfully integrated?

Explore all available tools, or follow the step-by-step walkthrough for Windsurf.

View All Tools Windsurf Walkthrough

{ "mcpServers": { "crawlforge": { "command": "npx", "args": [ "-y", "crawlforge-mcp-server@latest", "mcp" ], "env": { "CRAWLFORGE_API_KEY": "cf_live_your_api_key_here" } } } }