Pieces MCP integration with Cursor IDE

Get Started

Integrating the Pieces MCP with Cursor is a powerful and efficient way to bring your daily workflow context directly into your IDE.

With this integration, you'll have an in-IDE chatbot that knows more about your project than just the active file or project folder.

You can ask questions about additional workflow information, like whether a coworker fixed a bug in last week's PR, and then use that solution to fix a similar error in your code without having to look through old chat logs or GitHub commits.

Learn how to integrate the Pieces MCP into Cursor by following the steps below.

It is imperative that you download and/or update your version of Cursor to the **latest, most up-to-date version** to ensure compatibility with Pieces MCP.

Prerequisites

There are [2] primary prerequisites for integrating Pieces with Cursor 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 personal repository of workflow data and pass context through to the Cursor chat agent. 
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 Cursor, 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** (i.e., `39300`) PiecesOS is running on **may vary**.

To find the current MCP endpoint with the active instance of PiecesOS (including the current port number), open the PiecesOS Quick Menu and expand the Model Context Protocol (MCP) Servers tab.

There, you can click once to copy the MCP endpoint, which includes the active PiecesOS port number.

PiecesOS Quick Menu showing MCP servers section

You can also do this in the Pieces Desktop App by opening the Settings view and clicking Model Context Protocol (MCP).

Pieces Desktop App Model Context Protocol settings

Setting Up Cursor

There are three ways to set up Pieces MCP for Cursor: use the one-click setup in Pieces Desktop, use the Pieces CLI, or configure manually.

One-Click Setup via Pieces Desktop (Recommended)

The fastest way to connect Pieces MCP to Cursor is through the MCP Connections feature in Pieces Desktop.

In Pieces Desktop, click your `User Profile` in the top left, then hover over `Settings` and select `MCP`. Scroll down to the *MCP Connections* section. You'll see a list of supported clients with `Connect` buttons. Click the `Connect` button next to **Cursor**. Pieces automatically writes the MCP configuration to Cursor's global MCP config file. If Pieces detects missing dependencies, a dialog appears with installation instructions. Follow the steps shown (e.g., install Node.js), then click `Retry`. Restart Cursor for the configuration changes to take effect. Once connected, a green checkmark appears next to Cursor in the MCP Connections list. To disconnect later, click the `⋮` menu next to the connected client and select **Disconnect**, or click the red `✕` next to the connection entry.

One-Click Install Badge

Install Pieces MCP in Cursor with a single click. Ensure PiecesOS is running and Long-Term Memory is enabled before clicking.

Method 2: CLI Install

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

Method 3: Manual Configuration (Global MCP)

To set up the Pieces MCP, you can edit the .json settings configuration file from within Cursor Settings.

Navigate to **Cursor Settings**, then to the `MCP` section. 
<Image src="https://storage.googleapis.com/hashnode_product_documentation_assets/mcp_documentation/mcp_cursor/cursor_no_mcp.png" alt="Cursor Settings MCP section before configuration" align="center" fullwidth="true" />
Add a new global MCP server by clicking `Add new global MCP server` and inserting the following `.json` snippet (adjust port if necessary) in the `.json` file that opens: 
```json
{
  "mcpServers": {
    "Pieces": {
      "url": "http://localhost:39300/model_context_protocol/2025-03-26/mcp"
    }
  }
}
```
Save the configuration file. 
Make sure to refresh the MCP server window by clicking the **refresh icon** and ensure that there is a *green dot* indicating that the server is running and functioning without errors.

<Image src="https://storage.googleapis.com/hashnode_product_documentation_assets/mcp_documentation/mcp_cursor/cursor_green_dot_mcp.png" alt="Cursor MCP server running with green status indicator" align="center" fullwidth="true" />
Once the MCP server is set up, make sure to change the chat mode to *Agent* mode. This should automatically utilize the `ask_pieces_ltm` tool.

Using Pieces MCP Server in Cursor

Once integrated, you can utilize Pieces LTM directly in Cursor through the built-in chat agent.

Open the right-hand chat panel by toggling it at the top-right corner, or use the shortcut `⌘+i` (macOS) or `ctrl+i` (Windows/Linux). Make sure that you're using the *Cursor Agent* mode, not *Ask* or *Manual.* This is required to use the `ask_pieces_ltm` tool to access context from LTM. From this point, you can begin prompting. If PiecesOS was previously installed, try testing out the Pieces MCP integration with a prompt like, “What was I doing for work yesterday?” and click `Use Tool` when prompted. 
<Image src="https://storage.googleapis.com/hashnode_product_documentation_assets/mcp_documentation/mcp_cursor/example_pieces_mcp_cursor.gif" alt="Cursor Agent using Pieces MCP tool demonstration" align="center" fullwidth="true" />
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.

Configuring Rules

If you want to customize the specific output provided by the Cursor chatbot through working with the ask_pieces_ltm tool, you can manually adjust the rules for inside of Cursor Settings.

To do this, open up Cursor Settings, click Rules, then add new User Rules.

Here’s an example of a straightforward set of rules tailored to a specific use case and work flow:

Cursor custom rules configuration for Pieces MCP

Troubleshooting

If you’re experiencing issues integrating Pieces MCP with Cursor, follow these troubleshooting steps:

  1. Verify PiecesOS Status: Ensure PiecesOS is actively running on your system. MCP integration requires PiecesOS to be operational.

  2. Confirm LTM Engine Activation: Make sure the Long-Term Memory Engine (LTM-2.7) is enabled in PiecesOS, as this engine aggregates context necessary for Cursor to retrieve accurate results.

  3. Single MCP Instance: Make sure that you aren't testing multiple instances of the Pieces MCP server in different IDEs. This cross-contamination conflict with several MCP instances running on the same port can cause issues in different development environments.

  4. Use Agent Mode in Chat: Cursor must be in Agent Mode, not Ask Mode, to access the ask_pieces_ltm tool. Switch to Agent Mode to enable full MCP integration.

  5. Turn Off Auto-Select: If Cursor is having issues finding the Pieces tool, de-select auto-select and select an individual Agent, such as claude-3.5-sonnet.

  6. Check MCP Server Status: If you’re encountering messages such as “Sorry, I can’t do this,” your MCP server may not be properly configured or running.

  7. Go to settings.json in Cursor: Confirm the MCP server status shows "running" (it may say "start" or "pause" otherwise). Restart the server if necessary and inspect terminal outputs for error messages.

  8. Review Configuration Details: Double-check the MCP endpoint URL and the port number in Cursor settings to ensure accuracy. You can find the current MCP endpoint URL in the Pieces Desktop App under Settings → Model Context Protocol (MCP), or in the PiecesOS Quick Menu. It is usually formatted as:

http://localhost:{port_number}/model_context_protocol/2025-03-26/mcp
Ignore any red `.JSON` blobs in the MCP Settings view. The **Chat** pane is the source of truth—if your Pieces queries return formatted summaries there, the integration is functioning normally.

You’re now set to enhance your workflow with powerful context retrieval through Pieces MCP integrated seamlessly into Cursor. Happy coding!