---
title: "Windsurf MCP Setup: Add ToolPiper for 300+ Local Tools on Mac"
description: "Connect Windsurf (Codeium) to ToolPiper's local MCP server. JSON config in ~/.codeium/windsurf/, over 300 local tools added to every Cascade session."
date: 2026-05-11
author: "Ben Racicot"
tags: ["Windsurf", "Codeium", "MCP", "Model Context Protocol", "Setup Guide", "Privacy", "macOS"]
type: "article"
canonical: "https://modelpiper.com/blog/windsurf-mcp-setup-toolpiper/"
---

# Windsurf MCP Setup: Add ToolPiper for 300+ Local Tools on Mac

> Connect Windsurf (Codeium) to ToolPiper's local MCP server. JSON config in ~/.codeium/windsurf/, over 300 local tools added to every Cascade session.

## TL;DR

Edit ~/.codeium/windsurf/mcp_config.json, add a toolpiper entry pointing at http://127.0.0.1:9998/mcp with type http, restart Windsurf. Cascade in every chat sees over 300 ToolPiper tools alongside built-in capabilities.

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](/blog/mcp-setup-guide-mac).

## FAQ

### Is Windsurf's MCP config the same as Cursor's?

The JSON shape is identical (`mcpServers` object with named entries containing `type` and `url`). The file location is different: `~/.codeium/windsurf/mcp_config.json` for Windsurf vs `~/.cursor/mcp.json` for Cursor. The same ToolPiper snippet works in both.

### Does Cascade call ToolPiper tools without me asking?

Yes. Cascade evaluates registered tools at each agentic step and calls them when the conversation calls for it. You don't have to name a tool explicitly, though you can to force a specific choice.

### Can I use ToolPiper alongside other MCP servers in Windsurf?

Yes. Add multiple entries under `mcpServers`. Cascade sees the combined tool catalog. The server names must be unique, but otherwise there's no conflict.

### How do I remove ToolPiper from Windsurf?

Delete the `toolpiper` entry from `mcp_config.json` and restart Windsurf. ToolPiper keeps running for any other clients.

### Does Windsurf support stdio MCP servers?

Yes, alongside HTTP. The config shape for stdio is different: `command` and `args` instead of `url`. ToolPiper supports both transports, but HTTP is simpler and recommended.