Get Started

Integrating the Pieces MCP with Windsurf brings your workflow context directly into the Cascade AI panel. With this integration, Windsurf can access your past work, similar code, and historical debugging context to provide smarter, personalized assistance.

Prerequisites

There are two prerequisites for integrating Pieces with Windsurf as an MCP—an active instance of PiecesOS and the fully-enabled Long-Term Memory engine.

Make sure that PiecesOS is installed and running. This is *required* for the MCP server to communicate with your workflow data and pass context through to Windsurf. 
If you do not have PiecesOS, you can download it alongside the [Pieces Desktop App](/products/desktop/download) or [install it standalone](/products/core-dependencies/pieces-os/manual-installation#manual-download--installation) here.
For the MCP server to interact with your workflow context, you must enable the Long-Term Memory Engine (LTM-2.7) through the Pieces Desktop App or the [PiecesOS Quick Menu](/products/core-dependencies/pieces-os/quick-menu) in your toolbar.

Installing PiecesOS & Configuring Permissions

Follow the instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

Getting the MCP Endpoint for PiecesOS

To use Pieces MCP with Windsurf, you'll need the MCP endpoint from PiecesOS:

http://localhost:39300/model_context_protocol/2025-03-26/mcp
Keep in mind that the **specific port** (e.g., `39300`) PiecesOS is running on **may vary**. Windsurf uses **`serverUrl`** (not `url`) for HTTP/remote servers—this is a Windsurf-specific key name.

Setting Up Windsurf

There are two ways to set up Pieces MCP for Windsurf: use the Pieces CLI for automatic configuration, or configure manually.

Method 1: CLI Install (Recommended)

The Pieces CLI can automatically configure Pieces MCP for Windsurf—no manual config editing required.

Install the [Pieces CLI](/products/cli/get-started) if you haven't already. In your terminal, run: 
```bash
pieces mcp setup
```
A platform selection menu appears with options: *VS Code*, *Cursor*, *Claude Desktop*, *Windsurf*, *Claude Code*, *Raycast*, and *Warp*. Use the arrow keys to navigate to *Windsurf*, then press `return` (macOS) or `enter` (Windows/Linux) to auto-install.

Method 2: Manual Configuration

Windsurf stores its MCP configuration in a global config file. Edit ~/.codeium/windsurf/mcp_config.json:

Local Setup (Streamable HTTP — recommended)

{
  "mcpServers": {
    "pieces": {
      "serverUrl": "http://localhost:39300/model_context_protocol/2025-03-26/mcp"
    }
  }
}

Adding via MCP Marketplace

Open the Cascade panel in Windsurf. Click the `MCP icon` to open the MCP Marketplace. Search for Pieces, or click `Add custom` and enter your MCP URL.

Using Pieces MCP Server in Windsurf

Once integrated, you can utilize Pieces LTM directly in Windsurf through the Cascade panel.

Open the Cascade AI panel in Windsurf. Check the MCP tools section—Pieces LTM tools should appear. Ask Cascade: *"What Pieces tools are available?"* Ask context-rich questions about your workflow. For example: *"What was I working on yesterday?"* or *"Show me similar code snippets to this React component."* Check out this [MCP-specific prompting guide](/products/mcp/prompting) if you want to effectively utilize the Long-Term Memory Engine (LTM-2.7) with your new Pieces MCP server.

Updating

Edit ~/.codeium/windsurf/mcp_config.json, update the serverUrl, then restart Windsurf.

Troubleshooting

If you're experiencing issues integrating Pieces MCP with Windsurf:

  1. Verify PiecesOS Status: Ensure PiecesOS is actively running on your system.

  2. Confirm LTM Engine Activation: Make sure the Long-Term Memory Engine (LTM-2.7) is enabled in PiecesOS.

  3. Use serverUrl, Not url: Windsurf requires the serverUrl key—using url will not work.

  4. Restart Windsurf: After editing mcp_config.json, restart Windsurf for changes to take effect.

  5. Disable a Server: Add "disabled": true to the server config object if you need to temporarily disable Pieces MCP.

You're now set to enhance your Windsurf workflow with powerful context retrieval through Pieces MCP. Happy coding!