Get Started

Integrating the Pieces MCP with Claude Code brings your workflow context directly into the Claude Code CLI and VS Code extension. Claude Code is Anthropic's developer-focused AI tool for coding tasks. Setup is simple: add Pieces via the CLI, and it's automatically available in the extension.

Prerequisites

There are two prerequisites for integrating Pieces with Claude Code 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. 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.

Setting Up Claude Code

There are two ways to set up Pieces MCP for Claude Code: use the Pieces CLI for automatic configuration, or add the server manually via the Claude CLI.

Method 1: CLI Install (Recommended)

The Pieces CLI can automatically configure Pieces MCP for Claude Code—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 *Claude Code*, then press `return` (macOS) or `enter` (Windows/Linux) to auto-install.

Method 2: Manual Setup via Claude CLI

Claude Code supports adding MCP servers via the CLI. Servers added via claude mcp add are automatically available in the Claude Code VS Code extension—no additional setup needed.

Local Setup (Streamable HTTP — recommended)

Run in your terminal:

claude mcp add --transport http pieces http://localhost:39300/model_context_protocol/2025-03-26/mcp

Local Setup (SSE)

claude mcp add --transport sse pieces http://localhost:39300/model_context_protocol/2024-11-05/sse

Project-Scoped Setup

To make Pieces MCP available only for the current project (stored in .mcp.json at project root):

claude mcp add --transport http --scope project pieces http://localhost:39300/model_context_protocol/2025-03-26/mcp

Managing Servers

# List all configured servers
claude mcp list

# Remove a server
claude mcp remove pieces

# Show server details
claude mcp get pieces

Using Pieces MCP Server in Claude Code

Once integrated, you can utilize Pieces LTM directly in Claude Code.

Run `claude` in your terminal, or open a project in the Claude Code VS Code extension. Ask: *"What MCP tools do you have from Pieces?"* Pieces LTM tools should be listed. Ask context-rich questions about your workflow. For example: *"What patterns did I use in my last React component?"* or *"Show me the authentication flow I implemented yesterday."* 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

To update the URL, remove and re-add the server:

claude mcp remove pieces
claude mcp add --transport http pieces https://NEW_URL/model_context_protocol/2025-03-26/mcp

Troubleshooting

If you're experiencing issues integrating Pieces MCP with Claude Code:

  1. Verify PiecesOS Status: Ensure PiecesOS is actively running on your system. Test with: curl http://localhost:39300/.well-known/version

  2. Transport Error: Try switching between --transport http and --transport sse.

  3. VS Code Extension Not Seeing Tools: Restart VS Code after adding via CLI.

  4. Config Location: User scope uses ~/.claude.json; project scope uses .mcp.json at project root.

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