Scratchpad Mcp

What is Scratchpad Mcp?

Scratchpad Mcp is an MCP server that provides persistent, token-efficient storage for AI agents. It allows agents to store versioned files, append logs, and retrieve diffs or summaries instead of re-reading entire files, saving tokens and context space.

How to use Scratchpad Mcp?

Install Node.js 20+, clone the repository, run npm install and npm run build. Configure it as an MCP server in Claude Desktop by adding the server definition with the ANTHROPIC_API_KEY environment variable (required only for summarize_file). Invoke the eight tools (write_file, read_file, append_log, read_log, list_files, delete_file, summarize_file, get_usage_stats) with an agent_id parameter.

Key features of Scratchpad Mcp

• Versioned writes with automatic 10‑version retention per file.
• Line‑level diffs returned on read, not full content.
• Append‑only logs with cursor‑based pagination (100 entries per page).
• On‑demand file summarization via Claude Haiku, cached per version.
• Per‑agent namespacing prevents cross‑agent data leaks.
• SQLite backend with size caps and per‑agent quotas.

Use cases of Scratchpad Mcp

• An agent tracks changes to a working document across turns.
• An agent records its own action history and replays it efficiently.
• An agent summarizes a long file once and retrieves the cached summary later.
• Multiple agents share a server instance without reading each other's data.

FAQ from Scratchpad Mcp

What is the security model for Scratchpad Mcp?

agent_id is a plaintext tool parameter with no authentication; the server trusts the caller. It is safe for one‑user‑per‑server deployments (e.g., Claude Desktop), but not for multi‑tenant standby mode where untrusted callers share one SQLite file. Defense in depth includes SQL parameterization, path validation, size caps, and per‑agent quotas.

What are the runtime and dependency requirements?

Node.js 20+ and a SQLite backend (bundled). An Anthropic API key is required only for summarize_file; the other seven tools work without one. Optionally set SCRATCHPAD_DB_PATH to override the default SQLite file location.

How does storage work in Scratchpad Mcp?

All data lives in a single SQLite file with tables for files, versions, log entries, summaries, and agent usage. Each write_file stores the full content of the new version (not deltas); diffs are computed on read by comparing two versions. Older versions are pruned when the 10‑version cap is exceeded.

What are the operational limits?

1 MB per file write, 64 KB per log entry, 10 retained versions per file, 100 log entries per read_log page. Per‑agent quotas: 1000 files, 100k log entries, 100 MB total storage.

Who pays for summarize_file?

The caller always pays. In local installs, the user provides their own ANTHROPIC_API_KEY. In hosted deployments (e.g., Apify), each caller supplies their own API key per run. The other seven tools require no API key.