@pastepile/mcp

@pastepile/mcp

The persistent memory layer for AI coding assistants. A Model Context Protocol server that lets Claude, Cursor, Windsurf, and any MCP client save knowledge to Pastepile and retrieve it later by a stable URL.

Your assistant saves its own work as it goes, and can find it again next session. Zero dependencies, so it adds no supply-chain surface of its own.

The one tool that matters

pastepile_remember takes a session name the assistant chooses and can always reproduce from what it can see: a repository path, a conversation id, a branch name. The first call under a session creates the memory. Every call after updates that same memory and keeps the previous content as a version. A call whose content has not changed does nothing at all.

That last property is the whole design. Because an unchanged save is free and silent, the assistant can save after every meaningful step without being asked and without filling your account with near-identical copies. And because the session is a name rather than a slug, nothing has to survive a compacted conversation.

Tools

Memory (session-keyed; a subscription is required from September 8, 2026)

Tool	What it does
pastepile_remember	Create or update a memory by session. Deduplicates. No slug to keep.
pastepile_recall	Search your own memory by words, tags, and kind.
pastepile_timeline	One memory's version history plus related memories.
pastepile_restore	Put an earlier version back without losing the current one.

Trial memory is being retired on September 8, 2026. Until then, without PASTEPILE_API_KEY the memory tools work out of the box: each memory is an unlisted paste that expires one month after its last save (a save in its final week renews it for another month, so memory in active use stays alive), the session index lives on this device (~/.pastepile, or PASTEPILE_STATE_DIR), and restore reaches back one save.

The index is local; the memory is not. Each one is a real paste on Pastepile's servers, and because every save pushed the expiry out, an actively used trial memory never expired. That is hosted storage with no subscription behind it, and from September 8, 2026 saving memory without a key answers payment_required.

Nothing is deleted and reads are unaffected. Every memory already saved stays readable at its link, before and after that date, so it can be exported or saved again under a key. Pasting in the browser at pastepile.com stays free with no key and no account. What needs a subscription is writing to Pastepile programmatically, which covers this server and plain curl alike.

The tools keep working without a key: local demonstration mode. From that date, with no PASTEPILE_API_KEY set, pastepile_remember, pastepile_recall, pastepile_timeline and pastepile_restore run against a store on your own machine so you can see the workflow before paying. It is deliberately small and deliberately not cloud storage:

	Local demonstration	With a Pro API key
Where it lives	This machine, one file	Pastepile, your key's namespace
Has a link	No	Yes, a stable URL
Another machine	No	Yes
How many	3	No fixed limit
Size each	16 KB	Up to your plan's ceiling
Survives this machine	No	Yes

Every response says so and carries storage: "local_demo", so an assistant cannot report a demonstration memory as saved. Clear one with pastepile_forget and its session name. This is a demonstration, not a free subscription trial: there is no free trial.

An API key, issued with Pastepile Pro, makes memory permanent, searchable from any machine, with full version history.

Pastes (slug-keyed, no key required)

Tool	What it does
pastepile_save	Save text/code and get back a stable url, slug, and edit_key.
pastepile_checkpoint	Update one paste and preserve its previous revision in history.
pastepile_get	Retrieve a paste by slug or full Pastepile URL.
pastepile_search	Search your private memory (with an API key) or the public corpus.
pastepile_list	List your saved pastes (with an API key) or the public feed.
pastepile_forget	Permanently delete a paste that your API key saved.

Sharing a snippet by URL is a different job from keeping memory, so both families exist. Reach for the memory tools unless you specifically want a link to hand someone.

Private memory: when PASTEPILE_API_KEY is set, every paste your assistant saves is associated with that key, and pastepile_search / pastepile_list default to that private namespace (including unlisted pastes), searching titles, filenames, and contents. Pass scope: "public" to reach the public corpus instead. Without a key, both tools cover the public corpus only, and nothing is associated. One key can never see another key's pastes.

Conversation checkpoints: pastepile_checkpoint updates one paste at the same stable URL and preserves the content it replaces in Pastepile's existing version history. With an API key configured, the same key that saved a paste can checkpoint it in a later session without the one-time edit_key. The server instructions tell assistants to checkpoint after significant context growth, code generation, debugging or architecture work, and before likely context compaction, so saving does not depend on you remembering.

Forgetting: pastepile_forget deletes a paste that the same API key created, from its slug alone. That matters because the edit_key is shown exactly once, in a transcript that gets compacted away, so it is not the credential a later session still has. A paste saved with no key, or with a different key, is untouched by yours; pass its edit_key explicitly to delete that one. Deletion is permanent, and the tool is annotated as destructive so clients can confirm before running it.

Saved pastes default to unlisted (retrievable by URL, never shown in public listings or search) and never expire, so stored knowledge persists. Both are adjustable per call. End-to-end encrypted, password-protected, and burn-after-read pastes cannot be read back through the API and are out of scope for pastepile_get.

Requirements

Node.js 18 or newer (the server uses the built-in global fetch). No install step, no build.

Configuration

The server is configured entirely by environment variables:

Variable	Default	Purpose
PASTEPILE_API	https://www.pastepile.com	Base URL. Point at a self-hosted or staging deploy.
PASTEPILE_API_KEY	(none)	Pastepile API key, sent as X-API-Key. Makes memory permanent and portable across machines (without it, memory runs as device-local trial memory) and raises rate limits. Keys are created at https://www.pastepile.com/keys and come with a Pastepile Pro subscription. Never logged.
PASTEPILE_AUTOSAVE	conservative	How hard the server asks the assistant to save without being told to. off removes every unprompted trigger and leaves the tools available on request. conservative saves at moments where losing the work would cost real time. eager prefers saving to not saving.
PASTEPILE_STATE_DIR	~/.pastepile	Where trial memory keeps its device-local session index (a private file holding sessions and their edit keys). Unused once an API key is configured.

Setup

Claude Code

claude mcp add pastepile -- npx -y @pastepile/mcp

Or add it to .mcp.json in your project (shared with your team):

{
  "mcpServers": {
    "pastepile": {
      "command": "npx",
      "args": ["-y", "@pastepile/mcp"],
      "env": { "PASTEPILE_API_KEY": "your-key-optional" }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "pastepile": {
      "command": "npx",
      "args": ["-y", "@pastepile/mcp"],
      "env": { "PASTEPILE_API_KEY": "your-key-optional" }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "pastepile": {
      "command": "npx",
      "args": ["-y", "@pastepile/mcp"],
      "env": { "PASTEPILE_API_KEY": "your-key-optional" }
    }
  }
}

Any other MCP client

The server speaks JSON-RPC 2.0 over stdio. Run it with:

npx -y @pastepile/mcp

Point your client at that command. The env block is optional; without it the server talks to https://pastepile.com anonymously.

Remote endpoint (no local process)

Clients that speak MCP's Streamable HTTP transport can skip the local process and use the hosted endpoint instead. It runs the same dispatcher as this package, so the tools are identical:

https://www.pastepile.com/api/mcp

Tool calls on the remote endpoint require an API key (https://pastepile.com/keys, issued with Pastepile Pro), sent as Authorization: Bearer <key> or X-API-Key: <key>. Full setup: https://pastepile.com/docs/mcp/remote

Example

Once configured, ask your assistant to use it in plain language:

"Save this migration plan to Pastepile so we can pick it up tomorrow."

"Pull up the paste at pastepile.com/p/abc123 and continue where we left off."

"Checkpoint our current decisions before the context window fills up."

"Forget that draft you saved earlier, it is wrong."

The assistant calls pastepile_save, pastepile_checkpoint, pastepile_get, or pastepile_forget for you and keeps the returned slug in context.

How it works

This server is a thin wrapper over the public Pastepile REST API (/api/public/pastes). With an API key it holds no state of its own: every tool call is one HTTPS request, tagged with a pastepile-mcp/<version> User-Agent. Trial memory (no key) keeps exactly one small local file, the session index under PASTEPILE_STATE_DIR, because without a key there is no server-side namespace to attach sessions to. Your content goes straight to Pastepile under the same privacy model as the web app and CLI. For end-to-end encryption, create the paste in the web app or CLI (the encryption key never leaves the client) and share the resulting link.

License

MIT. Part of the Pastepile project.