Pieces MCP server
Local MCP endpoint in PiecesOS that lets an agent query Pieces Long-Term Memory: captured screen, clipboard and audio activity on one machine.
Pieces' MCP server is how a coding agent reaches Pieces Long-Term Memory, the activity record PiecesOS keeps on your machine. PiecesOS, the background service behind the Pieces desktop app, captures clipboard contents, OCR text from on-screen windows and audio transcriptions as workstream events, tagged with the application, window title and URL they came from. Its LTM-2 engine rolls those events into workstream summaries roughly every 20 minutes. The same local store holds Pieces Copilot conversations, saved websites, tags, annotations, code anchors and people, and all of it stays on the device.
There is nothing separate to install: PiecesOS serves MCP itself, over Streamable HTTP at localhost:39300/model_context_protocol/2025-03-26/mcp or over SSE at the 2024-11-05 path, and clients without HTTP support bridge through mcp-remote. Since PiecesOS 12.3.8 it exposes 39 tools. ask_pieces_ltm takes a plain question and lets Pieces pick the retrieval strategy, create_pieces_memory saves a memory, and the rest are 14 full-text and 5 vector searches over specific material types, an enumerator, a natural-language time-range parser and 16 batch fetchers by UUID. Pieces is proprietary, and Long-Term Memory with MCP comes with the paid Pro plan. The record belongs to one person on one machine; Pieces documents no way for a teammate's agent to query it.
Quick install
Copy-paste configs are provided for all 8 supported clients. Pick your client below.
Add to ~/.claude.json
{
"mcpServers": {
"pieces": {
"type": "http",
"url": "http://localhost:39300/model_context_protocol/2025-03-26/mcp"
}
}
}claude mcp add --transport http pieces http://localhost:39300/model_context_protocol/2025-03-26/mcpAvailable tools
| Tool | Description |
|---|---|
| ask_pieces_ltm | Ask a natural-language question about past work; Pieces chooses the retrieval and returns ranked workstream summaries and events with scores. |
| create_pieces_memory | Save a markdown memory with a title, optional project path and associated files, embedded for later keyword and semantic retrieval. |
| workstream_ | Keyword search over the AI-generated workstream summaries Pieces writes about every 20 minutes. |
| workstream_ | Keyword search over raw captured events (clipboard, OCR'd screen text, audio transcription), filterable by application, window title, URL and event type. |
| conversations_ | Find Pieces Copilot conversations by keyword, returning matched messages and annotations. |
| conversation_ | Find individual Copilot messages by keyword, with content and role. |
| tags_full_text_search | Find tags by keyword. |
| annotations_ | Find notes, summaries, descriptions, comments and git commit annotations by keyword, optionally filtered by annotation type. |
| persons_full_text_search | Find people by name, email or username. |
| anchors_full_text_search | Find code anchors (bookmarked files and locations) by name or path. |
| websites_ | Find saved or captured websites by URL or name. |
| hints_full_text_search | Find follow-up question suggestions Pieces generated, by keyword. |
| models_full_text_search | Find AI model configurations by name, provider or description. |
| wpe_ | Find the application sources detected during workflow capture. |
| wpe_ | Find captured application windows and browser tabs by title. |
| entities_ | Find organizations or teams by name. |
| materials_vector_search | Semantic similarity search over a chosen material type, returning identifiers with scores. |
| workstream_ | Semantic search over workstream summaries, returning UUIDs with similarity scores. |
| workstream_ | Semantic search over captured events, returning UUIDs with similarity scores. |
| hints_vector_search | Semantic search over generated follow-up suggestions. |
| tags_vector_search | Semantic search over tags to find conceptually related ones. |
| material_identifiers | List material UUIDs of a given type without a query, filtered by created or updated time range. |
| extract_temporal_range | Convert a phrase like "yesterday" or "last week" into UTC from/to ranges for the other tools' time filters. |
| workstream_ | Fetch up to 100 full workstream summaries by UUID. |
| workstream_ | Fetch up to 100 full captured events by UUID. |
| conversations_ | Fetch up to 100 full Copilot conversations by UUID. |
| conversation_ | Fetch up to 100 Copilot messages by UUID. |
| tags_batch_snapshot | Fetch up to 100 tags by UUID. |
| annotations_ | Fetch up to 100 annotations by UUID. |
| persons_batch_snapshot | Fetch up to 100 person records by UUID. |
| anchors_batch_snapshot | Fetch up to 100 code anchors by UUID. |
| anchor_ | Fetch up to 100 anchor points (individual file locations of an anchor) by UUID. |
| hints_batch_snapshot | Fetch up to 100 follow-up suggestions by UUID. |
| models_batch_snapshot | Fetch up to 100 model configurations by UUID. |
| ranges_batch_snapshot | Fetch up to 100 temporal range objects by UUID. |
| websites_batch_snapshot | Fetch up to 100 website records by UUID. |
| entities_batch_snapshot | Fetch up to 100 organization or team records by UUID. |
| wpe_ | Fetch up to 100 application source records by UUID. |
| wpe_ | Fetch up to 100 captured window records by UUID. |
What you can do with it
Find what you saw outside the editor
workstream_events_full_text_search filtered to the browser or a chat app returns the exact error text you copied or the OCR'd page you read, so the agent works from the real string instead of your paraphrase.
Draft yesterday's standup
The agent turns "yesterday" into a UTC range with extract_temporal_range, pulls the matching workstream summaries, and writes the update from what PiecesOS recorded.
Carry context between agents on one laptop
Save a debugging write-up with create_pieces_memory from Claude Code, then ask_pieces_ltm from Cursor a week later returns it, because both clients read the same local PiecesOS store.
FAQ
- Is it free?
- No. Long-Term Memory and MCP are part of Pieces Pro at $18.99 per user a month (25% less billed yearly), and Enterprise is $22.99. New users get a 7-day trial with a card on file; there is no free plan.
- Does it support remote or OAuth?
- No OAuth. The endpoint is served by PiecesOS on localhost with no authentication, so local clients connect directly. For a cloud IDE or hosted agent, Pieces documents exposing that port through an ngrok tunnel, which you then secure yourself.
- How does it compare to a team memory service like Glen?
- Pieces records one person's activity on one machine, including work that never happened in an agent session, and keeps it there. Glen records agent sessions, Slack, GitHub, tickets, docs and calls across an organization into one shared memory, and filters every recall to what the asking user is cleared to see.