Get Started

Integrating the Pieces MCP with Zed brings your workflow context directly into the Zed editor. Because Zed currently supports stdio only (not native HTTP), you'll use an stdio-to-HTTP bridge such as mcp-remote to connect to PiecesOS.

Prerequisites

There are three prerequisites for integrating Pieces with Zed:

Make sure that PiecesOS is installed and running. This is *required* for the MCP server to communicate with your workflow data. 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. The `mcp-remote` bridge requires Node.js. Ensure Node.js and `npm` are installed. Install `mcp-remote` globally with a pinned version for security: 
```bash
npm install -g mcp-remote@0.1.38
```

See [MCP Bridge](/products/mcp/mcp-remote) for why we recommend a locally installed binary over `npx`.

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.

Setting Up Zed with mcp-remote Bridge

Zed uses a custom context_servers key (not mcpServers or servers). Because Zed does not support HTTP MCP servers natively, you must use the mcp-remote bridge.

Config File Location

Scope Path
User settings ~/.config/zed/settings.json (Linux/macOS)
Project settings .zed/settings.json in your project root

Local Setup (same machine as PiecesOS)

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "pieces": {
      "command": {
        "path": "mcp-remote",
        "args": [
          "http://localhost:39300/model_context_protocol/2024-11-05/sse"
        ],
        "env": {}
      },
      "settings": {}
    }
  }
}
The port (e.g., `39300`) may vary. Find your current PiecesOS port in the PiecesOS Quick Menu under **Model Context Protocol (MCP) Servers**.

Alternative: supergateway Bridge

You can also use supergateway instead of mcp-remote. Install with npm install -g supergateway, then use "path": "supergateway" and "args": ["--sse", "http://localhost:39300/model_context_protocol/2024-11-05/sse"]. For security, prefer a locally installed binary over npx.

Using Pieces MCP Server in Zed

Once integrated, you can utilize Pieces LTM directly in Zed's AI assistant panel.

Open the AI assistant panel in Zed. Ask: *"What context tools do you have?"* Pieces LTM tools should be available. Ask context-rich questions about your workflow, such as: *"What was I working on yesterday?"*

Updating

Edit your settings.json, update the URL in the args array, and save. Zed reloads context servers on config change.

Troubleshooting

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

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

  2. Use context_servers: Zed uses context_servers, not mcpServers or servers.

  3. 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.

  4. Bridge process crashes: Check that PiecesOS is running and the SSE endpoint responds. You can test with: curl http://localhost:39300/.well-known/version

  5. No tools visible: Restart Zed; ensure mcp-remote is in your PATH.

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