MCP.so
Sign In

flatten-mcp

@shayaShav

Repository

About flatten-mcp

An MCP server that flattens Claude Code sessions — keeping every prompt and event verbatim while reclaiming context tokens, so you resume the exact same raw conversation at a lower token count instead of compacting it into a lossy summary. It moves bulky tool output (large file r

#mcp#model-context-protocol#claude#claude-code#context-window#tokens#session#history#flatten#compaction

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "flatten": {
      "command": "npx",
      "args": [
        "-y",
        "flatten-mcp@latest"
      ]
    }
  }
}

Tools

3

Flatten a Claude Code or OpenAI Codex CLI session: move bulky tool results (large text output and, for Claude, base64 image/screenshot blocks) out of the session JSONL into a backup copy, leaving a compact [FLATTENED ...] marker. The conversation reads identically — every prompt and event stays verbatim — but resumes with far fewer context tokens. Crash-safe (atomic rewrite + a single backup holding the complete session) and reversible via unflatten_session. Choose the store with agent ("claude" default, or "codex"). Reports diskBytesSaved and contextTokensSaved out of contextTokensTotal. For claude these are estimated locally, or exact when FLATTEN_COUNT_EXACT=1 and ANTHROPIC_API_KEY are both set; for codex the token savings are ALWAYS a local estimate (Anthropic count_tokens does not measure the GPT-5 tokenizer) and contextTokensTotal comes from Codex's own token_count events. With no session_id, flattens the current live session (claude); under codex "current" falls back to "last" (Codex has no live-session linkage). Also accepts a UUID, "last", "last N", or "current"; under codex a UUID reaches any rollout in the tree, while "last"/"last N"/keyword are scoped to the project dir. After flattening, /resume the session (claude) or codex resume the rollout (codex) to load the lighter copy.

Retrieve original tool result content from a flattened session, read straight from its backup. When you see [FLATTENED id=XXX tool=Read ... | text NNNB/NNL | session=YYY | ...] in the conversation, call this with the value after "id=" as tool_use_id and the value after "session=" as session_id, and set agent to match the session ("claude" default, or "codex"). Returns the original text output, or — for flattened screenshots (claude) — the actual image so you can view it again.

Reverse a flatten: re-inline every flattened tool result back into the session JSONL from the backup, restoring the session to its pre-flatten state, then delete the backup so nothing is left behind. Choose the store with agent ("claude" default, or "codex"). Under codex a UUID reaches any rollout in the tree; "last"/"current" are scoped to the project dir ("current" falls back to "last").

Overview

What is flatten-mcp?

flatten-mcp is a Model Context Protocol server for Claude Code that reduces a session's token footprint by moving bulky tool output (large file reads, command logs, base64 screenshots) into a sidecar file, leaving a lightweight retrievable reference in its place. It preserves the exact chronological flow and all user prompts verbatim.

How to use flatten-mcp?

Requires Node.js ≥ 18 and Claude Code. Install user-wide via claude mcp add flatten -s user -- npx -y flatten-mcp@latest. To flatten a session, exit it with Ctrl‑C, then in a new Claude Code window use the /flatten latest or /flatten <session-id> command, or ask the model directly. Resume the original session afterward. Dry runs and unflatten are supported.

Key features of flatten-mcp

  • Lossless and reversible – unflatten restores every block to its exact original value
  • Idempotent – re‑running skips already‑flattened blocks
  • Crash‑safe – originals are persisted to sidecar before removal, with atomic file writes
  • Reports both disk bytes saved and context tokens saved
  • Provides compact [FLATTENED …] markers with retrieval instructions
  • Includes tools for preview, retrieval, unflatten, and artifact cleanup

Use cases of flatten-mcp

  • Reclaim context window space in token‑heavy sessions (around 200k–300k tokens)
  • Preserve verbatim conversation history without lossy compaction
  • Retrieve original block content on demand via retrieve_flattened
  • Run a dedicated inexpensive model window as a flatten‑only station

FAQ from flatten-mcp

How does flatten differ from compaction?

Compaction rewrites the entire history into a lossy summary. Flatten instead moves only the bulky tool output to a sidecar while keeping every user and assistant message untouched, making it lossless.

Is flatten reversible?

Yes. unflatten_session re‑inlines every block from the sidecar, restoring each flattened result to its exact original value.

What are the system requirements?

Node.js ≥ 18 and Claude Code. The server is installed from npm and registered as a Claude Code MCP server.

Does flatten work with agents other than Claude Code?

No. flatten-mcp reads Claude Code’s session store at ~/.claude/projects/*.jsonl and is tested exclusively with Claude Code. The paths and JSONL schema are specific to it.

How does the server handle interruptions or crashes?

The session file is rewritten atomically via temp‑file‑and‑rename, and originals are written to the sidecar before removal from the session. An interrupted run never leaves a half‑written session file.

Frequently asked questions

How does flatten differ from compaction?

Compaction rewrites the entire history into a lossy summary. Flatten instead moves only the bulky tool output to a sidecar while keeping every user and assistant message untouched, making it lossless.

Is flatten reversible?

Yes. `unflatten_session` re‑inlines every block from the sidecar, restoring each flattened result to its exact original value.

What are the system requirements?

Node.js ≥ 18 and Claude Code. The server is installed from npm and registered as a Claude Code MCP server.

Does flatten work with agents other than Claude Code?

No. flatten-mcp reads Claude Code’s session store at `~/.claude/projects/*.jsonl` and is tested exclusively with Claude Code. The paths and JSONL schema are specific to it.

How does the server handle interruptions or crashes?

The session file is rewritten atomically via temp‑file‑and‑rename, and originals are written to the sidecar before removal from the session. An interrupted run never leaves a half‑written session file.

Comments

Basic information

Category

AI & Agents

Transports

stdio

Author

shayaShav

Submitted by

Shaya Shaviv

More AI & Agents MCP servers

Magic Hour

Magic Hour MCP lets AI agents create and edit images, videos, and audio using Magic Hour’s hosted generation tools.

BlazingCDN MCP - Content Delivery for Video, Software & Static Files

BlazingCDN

Official MCP server for BlazingCDN - AI agents (Claude, Cursor, Windsurf) manage CDN resources, purge cache, query metrics, domains, Anycast CDN, Video CDN and Media CDN

1

1Panel

1Panel-dev

🔥 1Panel is a modern, open-source VPS control panel — and the only one with native AI agent support. Run Ollama models, deploy OpenClaw agents, and manage your entire server stack from one clean web interface.

36.1K

Agentery

ntlgnc

Free MCP for live and historical pricing for 13,000+ agents and MCPs. Never knowingly pay too much... or charge too little. Know the going rate. https://agentery.com.

Hypnothera

La-Salida

Agent skill: turn what your AI assistant knows about you into a personalized hypnosis session on hypnothera.ai