MCP Help & Learning

Connect your AI tools to Pieces memory, verify PiecesOS, and troubleshoot local or remote MCP access.

Learn the requirements, local endpoint, and supported clients.

Add Pieces MCP to Cursor and verify the available tools.

Configure Pieces MCP for VS Code and GitHub Copilot.

Connect a remote client through the supported tunnel workflow.

Quick fixes

MCP tools are not available or returning errors

MCP clients require PiecesOS to be running and Long-Term Memory to be enabled before tools like ask_pieces_ltm will work.

Confirm PiecesOS is running. Look for the Pieces icon in your system tray or menu bar.
Open the PiecesOS Quick Menu and verify LTM-2 Engine is enabled.
Restart your MCP client (Cursor, VS Code, Claude Desktop, etc.) after PiecesOS starts.
If issues persist, restart PiecesOS and the client together.

Client cannot find or connect to PiecesOS

Most MCP clients connect to PiecesOS at http://localhost:1000. Firewalls, VPNs, or incorrect config paths can block the connection.

Verify PiecesOS is running and check for update prompts.
Check your client's MCP config file. The server command should point to the Pieces MCP executable or use the one-click connection in Desktop.
Temporarily disable firewalls or VPNs to rule out network blocks.
On macOS/Linux, confirm the config path uses the correct home directory expansion.

Setting up MCP for a remote or cloud client

Remote clients like cloud IDEs or hosted agents need a tunnel to reach PiecesOS on your local machine.

Install and configure ngrok or another tunnel service.
Start a tunnel to localhost:1000 and note the public URL.
Update your remote client's MCP config to point to the tunnel URL instead of localhost.
Keep the tunnel running while using the remote client.

Open the setup guide for the tool you want to connect.

Include your MCP client, operating system, and the connection error you see.