terse MCP server
Commit Nov 15, 2026Shrinks AI agent tool outputs by stripping structural overhead to reduce token consumption without changing the underlying data values.
Also known as inth3shadows/terse
- Stars
- 3
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is terse MCP?
terse shrinks AI agent tool outputs by stripping structural overhead to reduce token consumption without changing the underlying data values.
Summary generated from the project's README
About terse MCP server
terse acts as a drop-in proxy for any MCP server to reduce the token consumption of AI agents. It works by stripping structural overhead such as repeated keys, nested shapes, and whitespace from tool outputs. Because it functions as a transparent proxy, it is compatible with existing MCP clients without requiring them to reformat data. The server ensures that the underlying data values remain unchanged, providing a lossless transformation where every change has an exact inverse.
Developers can use this tool to manage costs and context limits during long sessions. It offers selective compression, meaning it can be applied on a per-tool basis rather than blindly compressing every response. The server includes built-in monitoring through the terse stats command, which allows users to see exactly how many tokens were saved. It is designed for environments where agents frequently re-read large, repetitive JSON payloads, such as GitHub API responses or complex code structures.
What you can do with it
- 1Reduce repetitive JSON token costsAn AI agent can process large GitHub API payloads with significantly fewer tokens by stripping structural overhead.
- 2Monitor token savings in real-timeA developer can check the efficiency of their MCP setup by viewing a live ledger of saved tokens.
- 3Minimize costs for repeated tool callsWhen an agent re-polls a list or re-reads a file, the server can emit a lossless delta to save space.
- 4Apply compression to specific toolsYou can choose to only compress large, repetitive outputs while letting smaller tools pass through unchanged.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableinth3shadows/terse is public and reachablegithub.com/inth3shadows/terse ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/inth3shadows/terse ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubterse
Cut the tokens your AI agent spends reading tool output, without changing a single value it reads. terse is a drop-in proxy for any MCP server. It strips structural overhead from each result (repeated keys, repeated values, repeated nested shapes) and hands the model the same data, value for value, in a denser form. No decode step, no model in the loop.
Five GitHub-style issues cost 436 tokens (cl100k) as a server pretty-prints them, and 232 minified. What the model gets instead costs 181:
{"__terse_dict__":1,"legend":{"~0":[{"name":"bug","color":"d73a4a"}]},
"data":{"__terse_table__":1,"n":5,"cols":["number","state","title","user","labels","repo"],
"rows":[[101,"open","Crash on empty cart",["ana","User"],"~0","acme/widgets"],
[102,"open","Timeout on checkout",["ben","User"],"~0","acme/widgets"], ...],
"subcols":{"user":{"cols":["login","type"]}}}}
- Lossless, and checked. Every transform has an exact inverse, and a round-trip gate
asserts
decompress(compress(x)) == x. Other tools in this space drop rows or old results to save tokens; terse only removes repetition. - Measured against the alternatives, on its best case. On real GitHub API payloads: 59.1% fewer tokens, against −6.5% for TOON and 4.5% for compressmcp on the same corpus (Benchmarks).
- Measured on real sessions, priced at the billed rate. A replay of the maintainer's own Claude Code sessions: terse saves 23.5% of what the MCP results it handled would have cost, and 0.77% of the whole bill of the sessions that used it (What it is worth in real sessions).
- Selective. It works per tool and passes through anything it can't shrink, so a
result's body never grows. The one-time format primer (and its typed wrapper, #463) and
fetch-backs of dropped values are extra costs; in the replay below they shrink the saving
in short sessions without erasing it.
terse statsshows what it saved.
What it is worth in real sessions
The 59.1% above is the codec on large, repetitive JSON. What it saves on a bill is smaller,
and this section is the number to judge terse by. scripts/bench/replay_sessions.py matches
every result terse changed to the Claude Code session it landed in, then prices the removed
tokens on each later API call that re-read them at that call's billed rate (cache write
first, cache read after, write again on a cache rebuild, nothing after compaction), and
charges every terse.retrieve fetch-back to terse. No model calls; it reads the ledger and
the transcripts already on disk.
Run on 2026-11-04 over transcripts from 2026-07-14 to 2026-11-04: 6,309 not under /tmp,
720 of them with a terse result. Test servers were removed from a copy of the ledger first,
and transcripts under /tmp (the test harness: 16 with a terse result) are left out of the
summary; see #577. Some scripted claude -p probes run elsewhere are still in it (35
sessions with a terse result); without them the 1-5-call band is +13.1%. The join rate,
96.4% of the results terse changed, is measured over all transcripts.
| measure | value |
|---|---|
| saved, share of what the joined MCP results would have cost | 23.5% of 119.0M input-equivalent tokens, after fetch-backs (26.7% before) |
| share of the whole bill, sessions that used terse | 0.77% (Opus 5.5 0.80%, Sonnet 5 0.98%, Opus 5 0.73%) |
| share of the whole bill, every real-work session scanned | 0.43% |
saving from secret.list_credentials + codegraph_explore, before fetch-backs |
92% |
| sessions over 100 calls | +24.1% of their MCP cost |
| sessions of 1-5 calls | +6.4% (an earlier −15.5% came from the 16 test-harness sessions; #577) |
| fetch-backs of dropped code blocks | 3.8M, about a third of what that rule saved; since keep_first and retract_after went live (2026-09-26, #252), sessions over 100 calls fetched back once, 2% of the rule's saving there |
| the model repeated the same call within 3 calls (a possible sign it could not use the result): changed vs unchanged results | 0.1% vs 2.77% |
Why it is smaller than 59.1%:
- Cache pricing. 96.9% of input tokens in the maintainer's sessions are cache reads, billed at a tenth of input price (measured 2026-09-22, 1,093 sessions). A removed token is mostly one that would have been re-read cheaply.
- MCP results are a small share of a session. The MCP results that went through terse were about 1.8% of what all scanned sessions cost. In the 2026-10-07 shell replay (6,776 transcripts), shell output was 16.1% and file reads 7.1% of the whole bill, and no MCP proxy sees either.
- The client already moves big results out. Claude Code saves an MCP result over 25,000 tokens (by default) or 50,000 characters to a file, showing the model a path and a preview; it also compacts long sessions. A result it saves to a file saves nothing through terse (72 in this replay), and terse keeps its primer out of it (#496).
So the value is narrow: a few large, repetitive results re-read across long sessions, with a lossless guarantee, and a replay that prices any change to what the agent reads.
Design: What Carries The Savings
terse reduces tokens two ways: one that carries the day-to-day value, and one that is harder for a competitor to copy. Keeping those straight is the whole positioning.
1. The lossless codec — the value. This is the lever that does the work. terse
removes only structural overhead: pretty-print whitespace, keys repeated once per
record, repeated values, repeated nested schema. The transformed bytes are the
model's input — a denser but still legible representation, not an offload. There is no
decode step, no ML model in the loop, and every transform has an exact inverse (a
round-trip gate asserts decompress(compress(x)) == x over the whole corpus). This is
the guarantee most tools in this space decline to make: headroom's JSON path is lossless
on uniform arrays but falls back to dropping rows on larger/irregular record sets,
recoverable only via a retrieve round-trip against a cache that expires (verified,
v0.34.0; default 30-min TTL); Anthropic/OpenAI context-editing drops old tool results
server-side. terse never silently mutates what the model sees — and "lossless" is the
category, not the token count. In the session replay the one lossy rule, code blocks
dropped from codegraph_explore behind a fetch handle, nets about a quarter of the saving
after fetch-backs; this codec carries the rest, most of it on the credentials list. Its one honest caveat: the
tabularization primitive is public (formats like TOON publish
it standalone, MIT-licensed, ~40% on flat arrays), so a motivated competitor could clone
the codec in a weekend.
2. The stateful cross-call diff — the axis nobody else can reach. It does not pay as shipped, but the reason is not what it looks like. When the same tool is called again — poll a list, re-read a file — terse emits a lossless delta against the prior result instead of the whole payload (~73% smaller on the repeated call in the model below). This is the one axis a stateless encoder architecturally cannot reach: TOON, headroom's stateless per-call compressor, and server-side history-pruning all pay the full column every call because none of them remember the last result — terse can only do it because it lives in the session as a transparent proxy.
That is an architectural claim, and it survives. The economic one does not, at this workload.
Re-derived 2026-09-22 over the full all-time ledger (4,461 blocks), superseding the 14-day #250 window that reported 1.9% / 3.7%:
decisions: compressed=3356 passthrough=659 unchanged=416 diff=30
diff reasons: diff_off=1387 joined=587 multiblock=444 no_prior=318
not_smaller_diff_args=251 emitted=26 not_smaller_same_args=4
The tier fires on 0.67% of blocks (30 of 4,461; 26 emitted diffs), while the live
router's primer cost 502 tokens every turn at the time — re-read as cache_read on
each one (the router primes lazily since #212: once per session, on its first terse result).
diff_off=1387 is the largest single reason and is expected: #170 made diffing opt-in
precisely because the primer paragraph costs more per turn than this hit rate returns.
But segment the attempts by whether the diff BASE had matching arguments, and the picture inverts (#419):
base args MATCH emitted 26 not_smaller_same_args 4 -> 87% win rate
base args DIFFER emitted 0 not_smaller_diff_args 251 -> 0% win rate
never re-called no_prior 318
When the diff gets a same-args base it wins 87% of the time. It almost never gets one.
proxy.py:345 keeps one base slot per tool (self.last: dict[str, Any] # tool -> previous result object), so any interleaved call to that tool with different arguments
evicts the base that would have paid. 251 attempts diffed against the wrong base.
So the tier is starved rather than weak, and an earlier edition of this section — which
called the remaining exclusions "the workload" and said "no codec change reaches that" — is
withdrawn. no_prior (318) is genuinely workload; the 251 are a data-structure choice.
But most of those 251 are not recoverable, and the probe says so. Classifying them by whether that tool's arguments can recur at all within a session:
115 (45.5%) WRITE kb.propose.merge_or_create / extend / delete — payload differs every call
60 (23.7%) QUERY kb.read.search — a different query string nearly every time
69 (27.3%) RE-READ runecho structure (36), kb.read.get (32) — args CAN recur
9 ( 3.6%) other
Arg-keying moves the writes and queries from not_smaller_diff_args to no_prior — the
same non-win, relabelled. Only ~69 are addressable, worth at most ~60 extra diffs at the
measured 87%: roughly 26 → 86, a ~3.3x on a tier that fires on 0.67% of blocks, which
had to clear the 502 tok/turn router primer (once per session since #212). Real and cheap, but small. #419 carries it at
that reduced size. The drop tier is where the measured tokens are (#252, #271, #273):
codegraph_explore's single rule accounts for 604,892 saved tokens in the 2026-09-22
ledger, 22.2% of all savings.
It remains opt-in and not the headline (#170). When a loop really does re-fetch
mostly-unchanged results it compounds hard; short sessions with wide tool variety never
exercise it. How often your loop repeats a call is yours to measure (terse stats).
Around those two sits the bundle that turns a byte filter into a control plane you
don't want to rip out: MCP-native proxy packaging (transparent to any downstream
server, no client-side reformatting), a live savings ledger (terse stats), a
fluency-gated lossy escape hatch, and self-installing ops tooling (install-mcp,
mcp-status) — each diff/lossy tier validated by a behavioral eval before it was ever
shipped.
It is selective by design. Measurement on real tool output showed the win is strongly per-tool (0–30%): large on record/symbol-shaped verbose output, near-zero on already-minified or already-projected tools. So terse applies per-tool policy rather than compressing everything blindly.
How It Works
terse transforms a tool's JSON output through a tiered, fully-lossless pipeline, then (optionally) serves it through a per-tool policy that decides which tiers run.
- Tier 0 — minify: strip insignificant whitespace.
- Tier 0 — tabularize: a list of uniform records becomes one header + value rows (keys written once, not once per record), recursively hoisting nested uniform-dict columns into a shared header.
- Tier 0.5 — dictionary code: repeated string values and repeated whole subtrees
are folded into an inline legend (
~0,~1, …) proven disjoint from every literal in the payload. Committed only when it actually saves tokens, so it never regresses. - Tier 0.6 — embedded JSON (opt-in,
"embedded"): a string field that is itself a JSON document ({"response_text": json.dumps(body)}) is folded so the tiers above can reach it. Only when the original string can be rebuilt byte for byte. - Tier 0.65 — Python literal (opt-in,
"pyliteral"): a text result that is a Pythonreprof data rather than JSON (str(rows)frommcp-server-sqlite) is read as that data and compressed. Only whenreprof what was read is the original text exactly. - Tier 0.7 — cross-call diff (stateful, OPT-IN —
"diff": true): when the same tool is called repeatedly, the proxy emits a lossless delta against the prior result instead of the full payload (the 91%-overlap headroom). Self-describing, verified to reconstruct exactly, and emitted only when smaller — falls back to the full form otherwise. Its validation program completed (fluency, nested-record coverage, and the drift soak — see Status), but the tier stays OFF by default since #170; opt in withproxy --diff/install-mcp --diffor a policy-file"diff": true. Record-shaped JSON gets a row/key diff; non-JSON results (file reads, source excerpts, log tails) get a separate content-defined-chunking (CDC) diff — a rolling hash cuts chunk boundaries by content, not position, so an edit anywhere only perturbs the chunk(s) it overlaps and the rest is sent as references to the prior result. Each shape keeps its own diff base per tool. - Cross-block join (ON by default): some MCP servers return one record per content
block, so each block is a lone object the codec above can barely fold and the diff tier
skips entirely (it reasons about one logical payload). When every text block of a result
is a JSON object, the proxy joins them into one record array before compressing — so
tabularize/dictionaryfold across records and the whole result becomes diff-eligible. This changes the number of content blocks the client sees (N → 1), which the MCP spec permits (block count carries no meaning). Opt out withproxy --no-join-blocks/install-mcp --no-join-blocksor a policy-file"join_blocks": false; lossy field rules still resolve per block, before the join. - Tier 1 — lossy (opt-in, per field):
truncatecaps and annotates a field marked{"lossy":"truncate","max":N}, gated by an acceptable-loss check (only marked, non-criticalfields may differ, each only as a valid truncation).drop-to-retrievereplaces a marked field with a handle, stores the original per session, and serves it back via a syntheticterse.retrievetool the proxy injects — gated so a drop is accepted only if the handle resolves to the exact original.summarize(needs a model) is parsed but will not be built — it is closed permanently (#261), because a model in the proxy breaks terse's no-ML guarantee. It is warned and left lossless, and the schema keeps accepting it only so an existing policy does not fail to load. Off everywhere by default.
Every transform has an exact inverse, and a round-trip gate asserts
decompress(compress(x)) == x over the whole corpus. The transformed bytes are
the model's input — a denser but still-readable representation, not an offload.
The proxy also keeps a live savings ledger (on by default; --no-stats to opt
out): one payload-free JSONL record per result — sizes, tokens, and the decision
taken, never content — so terse stats can answer "how much did terse actually save
me this week?" from real sessions, not just the synthetic corpus.
Install
Needs Python 3.11+.
uv tool install terse-mcp # global `terse` CLI (or: pipx install terse-mcp)
Or pip install terse-mcp into a virtualenv for library/embedded use.
Docker
docker build -t terse .
docker run -i --rm terse # proxies the bundled demo server
docker run -i --rm terse uvx some-mcp-server # proxies a real one
-i is required — MCP stdio is stdin/stdout. Everything after the image name is the
downstream server command; terse has no tools of its own, so with no downstream there is
nothing to compress. The default is examples/demo_mcp_server.py, a stdlib-only server
whose demo_orders tool returns a 40-record order book — you get back terse's compressed
form of it (9,019 → 3,187 chars), which is the fastest way to see what the proxy does.
The image ships uv/uvx so uvx-launched servers work out of the box. Node is not
installed — for an npx-launched server, build FROM this image and add it.
The build reads the version from git describe, so build from a normal git clone. Any
context without a resolvable .git — a source tarball, or a git worktree whose .git is
a pointer file — needs --build-arg TERSE_VERSION=0.3.1 instead.
Quick Start (under a minute)
terse sits between your MCP client and a server and shrinks the server's tool results in flight. No config needed — the proxy is lossless-everywhere by default:
# 1. Wrap ANY stdio MCP server. Your agent talks to it exactly as before;
# terse compresses the results it returns, losslessly.
terse proxy -- uvx some-mcp-server --flags
# 2. See what it saved (the payload-free ledger is on by default):
terse stats
Want to eyeball the codec first, no server involved?
echo '[{"id":1,"state":"open","repo":"acme/widgets"},{"id":2,"state":"open","repo":"acme/widgets"},{"id":3,"state":"open","repo":"acme/widgets"},{"id":4,"state":"open","repo":"acme/widgets"},{"id":5,"state":"open","repo":"acme/widgets"},{"id":6,"state":"open","repo":"acme/widgets"}]' | terse gate -
# → round-trip lossless: PASS ; cl100k 87 -> 78 (10.3% saved)
(Savings grow with record count and repetition; on a single tiny object terse correctly declines and passes it through unchanged — it never inflates what it can't shrink.)
Does terse help my server?
The win is per-tool and terse only keeps what pays, so it never hurts — but it helps a lot
more on some shapes than others. Point it at a server and run terse stats to see for real;
as a rule of thumb:
| terse helps most | terse barely moves |
|---|---|
| record/array JSON (lists of objects) | already-minified or already-projected output |
| repeated values or nested repeated subtrees | free-text-dominated results (logs, prose, diffs) |
| verbose REST-ish payloads (GitHub, Jira, DB rows) | tiny single objects |
| tools you call repeatedly (cross-call diff) | binary / non-JSON blobs (passed through untouched) |
Wire it into your MCP client (permanent)
install-mcp rewrites your MCP config to launch a server through terse — reversible, and
transparent to the client. It needs a per-tool policy; the smallest useful one is:
echo '{"version":1,"defaults":{"tiers":["minify","tabularize","dictionary"]}}' > terse-policy.json
# Claude Code, user scope (~/.claude.json) — wrap a server you've already registered by name:
terse install-mcp --policy terse-policy.json <server-name>
# Project scope (a committed .mcp.json instead):
terse install-mcp --policy terse-policy.json --scope project --file .mcp.json <server-name>
terse mcp-status # confirm what's wrapped
terse uninstall-mcp <server-name> # cleanly restore the original entry
Other MCP clients (Cursor, etc.) read the same config shape — wherever a server is launched
as cmd --flags, launch it as terse proxy -- cmd --flags to get the same effect.
See USAGE.md for tuning a policy (terse tune) and reading terse stats.
From source (contributors): uv sync then uv run terse ...; uv run pytest is the
lossless gate.
Project Structure
src/terse/
transforms.py lossless tiers (minify, tabularize, dict coding) + round-trip gate
policy.py selective per-tool policy: load, match, apply
proxy.py MCP stdio middleware: compress a downstream server's tool results
multiproxy.py `proxy --config`: one process fronting several servers
transport.py the downstream link: a subprocess (stdio) or Streamable HTTP
lossy.py opt-in lossy primitives: truncate, drop-to-retrieve
text_diff.py cross-call diff for non-JSON text results
wirelog.py `--wire-log`: an exact record of every line through the proxy
policy_gen.py write a lossless policy from a captured corpus
droptune.py `tune --from-ledger`: verdicts for live drop rules
install_mcp.py wrap / unwrap Claude Code MCP servers
stats.py live savings ledger (payload-free) + the `terse stats` aggregation
capture.py corpus capture (shape-tagged envelopes) + shape classifier
measure.py per-payload + cross-tokenizer token measurement
probes.py value-redundancy + cross-call-overlap ceiling probes
fluency/ does a model read the compressed form as accurately as raw JSON?
(questions / scoring / answerers / harnesses / pack behind one facade)
tokenize.py cl100k / o200k token counting
report.py markdown reports (savings, per-tool, probes, tokenizer, fluency)
html_report.py charted HTML companion (inline SVG, no JS/CDN) for measure/verify
cli.py entrypoint: gate / policy / compress / capture / measure / probe / validate /
proxy / stats / fluency / tune / install-mcp / uninstall-mcp / mcp-status / verify
scripts/
gen_stress_corpus.py synthetic stress corpus for the fluency eval; `--fleet-shapes`
adds `synthetic.*` shapes a capture corpus cannot hold (#403)
bench/ terse-vs-TOON token benchmark on a real GitHub-API corpus
(fetch_corpus.sh, benchmark.py, diff_demo.py, toon_encode.mjs)
bench/mcp_servers/ what terse does, zero-config, to popular third-party MCP servers
(mcp_probe.py harness + pinned repo/web fixtures; BENCHMARKS §6)
examples/
demo_mcp_server.py stdlib-only stdio MCP server; the container's default downstream,
so `docker run` demonstrates the proxy without a real server
tests/ round-trip, measurement, probe, policy, and fluency tests
Dockerfile terse + the demo downstream, for registries and one-command trials
policy.example.json selective policy encoding the measured per-tool insight
corpus/ captured tool outputs (gitignored; may contain real data)
Verify it yourself
terse sits in your agent's critical path, so it earns trust by inspection. See VERIFY.md for the full walkthrough — or generate a self-contained report (lossless gate + per-tool token savings) in one command:
terse verify --out reports/verify-report.md # bundled sample, zero setup
terse verify --corpus corpus --out report.md # your own captured traffic
terse verify --html --out reports/verify-report.md # + a charted HTML report alongside it
terse verify --corpus corpus --json # machine-readable gate + savings (CI-checkable)
terse MCP questions
Is the compression lossless?
Yes, it is lossless by default. Every transform has an exact inverse, and a round-trip gate ensures the decompressed data matches the original.
How does it save tokens compared to other tools?
It removes structural overhead like repeated keys and nested shapes. On real GitHub API payloads, it achieved 59.1% fewer tokens.
Does it require a decode step for the AI to read the data?
No, there is no decode step or model in the loop; the transformed bytes are the model's input in a denser but still legible representation.
Can I see how much I am saving?
Yes, you can use the 'terse stats' command to see what it has saved.