Windsurf's Cascade agent is one of the most aggressive MCP consumers around. It treats every registered tool as fair game during a conversation, which makes a 300+ tool server like ToolPiper a significant capability bump. The setup is a single JSON edit, structurally identical to Cursor's.

Why connect Windsurf to ToolPiper?

Windsurf's Cascade agent can already edit your codebase. ToolPiper adds the rest of your Mac: screen capture, audio transcription, browser automation, system control, web scraping, local LLM chat. Cascade gets to call any of those during an agent task, all running on your hardware.

The combination is unusually capable. Cascade can write code, then run a browser test against the result via browser_launch, capture a screenshot of the failure with vision_screenshot, OCR the error text, and patch the code. End to end in one task without leaving the editor.

How do I add ToolPiper to Windsurf?

Edit ~/.codeium/windsurf/mcp_config.json. Add a toolpiper entry under mcpServers with type: "http" and url: "http://127.0.0.1:9998/mcp". Restart Windsurf.

The JSON, identical in shape to Cursor's config:

{
  "mcpServers": {
    "toolpiper": {
      "type": "http",
      "url": "http://127.0.0.1:9998/mcp"
    }
  }
}

Steps:

  1. Locate the config file. ~/.codeium/windsurf/mcp_config.json. The .codeium/windsurf directory exists once you've launched Windsurf at least once. If mcp_config.json isn't there, create it with the JSON above.
  2. Add the entry. If other MCP servers are already registered, add toolpiper alongside them.
  3. Restart Windsurf. Quit and relaunch. Windsurf reads MCP config at startup.

How does Windsurf decide when to call ToolPiper tools?

Cascade picks tools based on the conversation and the tool descriptions. ToolPiper's tools have descriptive names like vision_screenshot, browser_action, and audio_transcribe that map cleanly to natural-language requests. Cascade rarely needs explicit prompting once the registration is live.

If Cascade is hesitant to call a tool you'd expect it to use, name the tool in your prompt directly: "use vision_screenshot to capture my screen". After one or two explicit calls, Cascade tends to discover the tool's usefulness for related prompts.

How do I verify Windsurf sees ToolPiper?

Open Windsurf's MCP settings (Settings -> MCP). ToolPiper should appear with a connection indicator. Or start a Cascade session and prompt it to do something only ToolPiper can do.

Windsurf's settings UI lists registered MCP servers with their connection status. Green or check means the handshake worked. Red means Windsurf couldn't reach the server (usually ToolPiper isn't running).

End-to-end test from Cascade: "take a screenshot of my screen and describe what's open." If Cascade invokes vision_screenshot and responds with content, the setup is correct.

What if Windsurf can't see ToolPiper?

Four checks. ToolPiper is running. JSON is valid. Windsurf was restarted. The endpoint actually responds. The order matters because each later check assumes the earlier ones passed.

  1. ToolPiper running. Menu bar icon visible, or curl http://127.0.0.1:9998/health returns JSON with "status": "ok".
  2. JSON valid. Validate mcp_config.json through python3 -m json.tool. Trailing commas and stray quotes are the usual culprits.
  3. Windsurf restarted. Full quit, then relaunch. Window close isn't enough.
  4. Endpoint reachable. curl http://127.0.0.1:9998/mcp. If the response is connection refused, ToolPiper isn't actually running.

If all four pass and Cascade still doesn't see ToolPiper, check Windsurf's developer console for MCP discovery errors. The settings UI sometimes shows a server as connected before tool discovery completes, which can mask edge cases.

For setup on other editors, see MCP Setup on Mac.