Advanced MCP Configuration | Pieces Docs

Manual setup for apps that need a helper connection to PiecesOS. Step-by-step for Raycast, Zed, OpenClaw, and remote setups.

MCP Bridge

Some apps, including Raycast, Zed, and OpenClaw, need a small helper to talk to Pieces. This page covers that advanced, manual setup. Use it when your app is not available in one-click Connect.

**Claude Desktop** does not need this page for the usual setup. Use one-click `Connect` in Pieces Desktop (`Settings` → `MCP`), where Pieces includes the connection helper and saves the settings for you. See [Claude Desktop](/products/mcp/claude-desktop). For other apps, the easiest path is often the Pieces CLI: run `pieces mcp setup` and select your platform. Use the manual steps below only when your app is not listed or you need a custom address (for example, a remote URL).

Easiest Option: Pieces CLI

The Pieces CLI automatically configures MCP for supported platforms—no manual config editing required.

In your terminal, run `pieces mcp setup`. Use the arrow keys to select your MCP client (VS Code, Cursor, Claude Desktop, Windsurf, Claude Code, Raycast, or Warp) and press Enter. The CLI updates the platform's config file and confirms when Pieces MCP is enabled. Ensure PiecesOS is running and LTM is enabled. Run `pieces mcp status` to verify your setup.

Manual Setup

Use manual setup when your client isn't supported by the CLI (e.g Zed and OpenClaw) or when you need to point at a remote PiecesOS URL (see Tunneling).

Prerequisites

PiecesOS must be installed and running. 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). 
<pos-download-guide />
`mcp-remote` requires Node.js 18+. Ensure Node.js and `npm` are in your PATH. Install `mcp-remote` globally with a pinned version so your MCP client runs a known, verified binary instead of fetching from the registry at runtime: 
```bash
npm install -g mcp-remote@0.1.38
```

<Callout type="alert">
  Using `npx` to run `mcp-remote` downloads the package from npm each time. For better security, use a locally installed, version-pinned binary as shown above.
</Callout>

Pieces MCP Endpoints

PiecesOS exposes two endpoints. For mcp-remote, use the SSE endpoint—it works reliably across all stdio clients:

Endpoint URL Use for
SSE http://localhost:39300/model_context_protocol/2024-11-05/sse mcp-remote, stdio clients
Streamable HTTP http://localhost:39300/model_context_protocol/2025-03-26/mcp Clients that support HTTP natively
The port may vary. Find yours in the PiecesOS Quick Menu under **Model Context Protocol (MCP) Servers**, or in Pieces Desktop under **Settings** → **Model Context Protocol (MCP)**.

Configuring Your Client

Edit `mcp-config.json` (open via **Manage MCP Servers** → **Show Config File in Finder**): 
```json
{
  "mcpServers": {
    "pieces": {
      "command": "mcp-remote",
      "args": [
        "http://localhost:39300/model_context_protocol/2024-11-05/sse"
      ]
    }
  }
}
```

See [Raycast integration](/products/mcp/raycast) for full setup.
Zed uses `context_servers` (not `mcpServers`). Edit your Zed `settings.json`: 
```json
{
  "context_servers": {
    "pieces": {
      "command": {
        "path": "mcp-remote",
        "args": [
          "http://localhost:39300/model_context_protocol/2024-11-05/sse"
        ],
        "env": {}
      },
      "settings": {}
    }
  }
}
```

See [Zed integration](/products/mcp/zed) for full setup.
Prefer one-click `Connect` for [Claude Desktop](/products/mcp/claude-desktop), since Cowork shares that setup. Use the steps below only for advanced manual configuration. 
```json
{
  "mcpServers": {
    "pieces": {
      "command": "mcp-remote",
      "args": [
        "http://localhost:39300/model_context_protocol/2024-11-05/sse"
      ]
    }
  }
}
```

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows). See [Claude Cowork](/products/mcp/claude-cowork) for full setup.
Edit `~/.openclaw/workspace/config/mcporter.json`: 
```json
{
  "mcpServers": {
    "pieces": {
      "command": "mcp-remote",
      "args": [
        "http://localhost:39300/model_context_protocol/2024-11-05/sse"
      ]
    }
  }
}
```

See [OpenClaw integration](/products/mcp/openclaw) for full setup.

For remote setups, use the ngrok URL instead of localhost. See Tunneling.

Useful Flags

Flag Purpose
--allow-http Allow HTTP URLs; use only in trusted private networks
--debug Write verbose logs to ~/.mcp-auth/{hash}_debug.log
--silent Suppress default logs

Tips & Troubleshooting

Ensure PiecesOS is running. Test the endpoint: curl http://localhost:39300/.well-known/version. Restart your MCP client after changing config, then ask: "What tools do you have from Pieces?" or "What did I work on yesterday?"

Troubleshooting

  1. mcp-remote: command not found — Run npm install -g mcp-remote@0.1.38 and ensure the global npm bin directory is in your PATH.

  2. Bridge not connecting — Verify PiecesOS is running and the port is correct. Test with curl http://localhost:39300/.well-known/version.

  3. Wrong config key — Zed uses context_servers; Raycast, Claude Cowork, and OpenClaw use mcpServers.

  4. Port mismatch — Check the PiecesOS Quick Menu or Settings → Model Context Protocol (MCP) for the current endpoint.

  5. Stale credentials — If you have persistent issues, try rm -rf ~/.mcp-auth and restart the client.

Next Steps

  • Raycast — macOS launcher with Pieces LTM
  • Zed — Zed editor with Pieces LTM
  • Claude Cowork — Claude Cowork with Pieces LTM
  • OpenClaw — OpenClaw with Pieces LTM
  • Tunneling — Expose PiecesOS for remote MCP access