Cap Shield

CAP-Shield MCP server

Context selection and compression for AI agents — with the recall measured, not claimed.

One file. No dependencies. No SDK required.

Why

More context makes agents worse. ETH Zurich found context files LOWER task success versus giving the agent no repository context at all, while raising inference cost by over 20 %. Around two thirds of production agent failures trace to context problems, not to the model being incapable.

So the question is not how much you cut. It is whether what you kept was enough — and that is measured here, on a benchmark we did not choose: LongMemEval-S, 500 questions. Recall@10 of 97.1 % against a lexical baseline of 51.9 % (measured 2026-09-28 — figures update as retrieval does; fetch .well-known/cap-shield.json for the current number rather than trusting this file).

Recall@10 is the strict measure: a question counts only when ALL gold sessions were found. Finding half the answer means the agent answers confidently on half a basis.

Two of the eight tools need no account. Measure first, decide after.

Install

curl -O https://cap-shield-robin.fly.dev/cap_mcp.py

{

"mcpServers": { "cap-shield": { "command": "python", "args": ["/absolute/path/to/cap_mcp.py"] } } }

Python 3.9+. Nothing else.

The optional SKILL.md tells an agent *when* to use these tools — and when not to.

Use it from Claude (Claude.ai, Claude Desktop, or Cowork) — no download

The server is also reachable directly over HTTP, so a hosted Claude client can connect to it without installing anything locally.

In Claude: Settings → Connectors → Add custom connector, and enter the server URL:

https://cap-shield-robin.fly.dev/mcp

Under Authentication, choose No sign-in — this server is authenticated with an API key, not OAuth (OAuth support is not built yet; see Status below). Claude will warn that anyone with the URL can use the connector without sign-in — that warning is accurate, and is exactly why the two free tools below need no key at all, while the rest do.

`measure_traffic` and `list_packages` work immediately, with no header and no account — nothing more to configure.

To use the account tools (remember, assemble_context, pack_batch, unpack_batch, issue_pass): get a key first (get_account, or the console at https://cap-shield-console.lovable.app), then add it under Request headers in the same connector dialog:

The Bearer prefix is required — a bare key without it is rejected with NYCKEL_KRAVS. This is a standard bearer-token header, so the same two fields should work in any MCP client that lets you add a custom request header to a remote server, not just Claude — that is just the one this has actually been tested against.

Tools

measure_traffic · *no account*

Measure how much of your own agent traffic could be saved. NO ACCOUNT OR KEY NEEDED — use this first. Returns byte savings over the wire and, if a query is given, token savings from selective context retrieval. Nothing is stored: the text is compressed in memory and discarded. Rate limited to 20 calls per hour per IP.

list_packages · *no account*

List the available dictionaries with their MEASURED compression, including the ones that perform badly. Each entry says whether it works one message at a time or only batched, and how many messages came out LARGER. No key needed.

remember · *requires a key*

Store a memory entry for later retrieval. REQUIRES A KEY. This does not call any language model — it stores text in an isolated per-tenant archive. Use assemble_context to get relevant entries back.

assemble_context · *requires a key*

Retrieve the memory entries that answer a question, within a token budget. REQUIRES A KEY. Send the returned 'context' to your language model INSTEAD of the whole history. This does not call a model itself — it selects what to send. The budget is a ceiling, not a target: selection stops where relevance runs out, often well below it. The response says how many entries were left behind and why.

pack_batch · *requires a key*

Pack several messages into ONE compressed packet instead of packing them one at a time. REQUIRES A KEY. Worth it for many small/medium messages (the per-message header cost is paid once per batch, and zstd shares context across them) — for a single message this has no advantage. Returns packet_b64 (hand it to unpack_batch to get the messages back) plus the measured byte savings versus packing each message separately. SECURITY: only batch messages that already share the SAME trust boundary (same tenant/agent — nothing attacker-influenced mixed in with a secret). Batched messages share one compression context, which can leak size-based information between them (a CRIME/BREACH-style side channel). There is no padding mitigation on this endpoint today, so trust-boundary separation is the only protection — don't rely on padding.

unpack_batch · *requires a key*

Unpack a batch packet made by pack_batch (or by the /api/v1/pack-batch endpoint) back into the exact original list of messages, in order. REQUIRES A KEY. Not for a packet made by the single-message pack endpoint — that is a different format and this will reject it.

get_account

Get an account and an API key. Requires an email address. The key is returned ONCE and cannot be shown again — store it immediately. Beta quotas are low by design; they are hard stops, never overage billing.

issue_pass · *requires a key*

Agent identity / agent passport. Issue a short-lived (15 minute) signed credential (a JWT) stating who the caller acts for. REQUIRES A KEY. Anyone can verify it independently against /.well-known/jwks.json — without calling CAP-Shield again. 'acts_for' and 'scope' are NOT validated against reality: the pass only attests that the key holder claimed this, at this time, and that the claim is recorded in the audit chain. This is identity and claimed authorization, not a payment or access-control mechanism.

The descriptions above are copied verbatim from the server. If they ever differ from what tools/list returns, the server is right and this file is stale.

Optional: LLM escalation for the hardest questions

Retrieval and compression above never call a model. assemble_context also returns escalate_recommended: true on one specific category of question — multi-step counting ("how many times did I mention X?"), summing amounts spread across several memories, reconstructing chronological order across multiple events — where the answer is not sitting in any single entry and has to be assembled. Plain retrieval gets these right most of the time; this flag is for the rest.

What you do with that flag is yours to decide. CAP-Shield never spends your tokens or sees your model key.

cap_escalate_helper.py is a reference implementation of that one extra step: drop it into your own pipeline, call it with your own ANTHROPIC_API_KEY or OPENAI_API_KEY, only for the questions CAP-Shield flagged.

pip install anthropic   # or: pip install openai

export ANTHROPIC_API_KEY=...

from cap_escalate_helper import eskalera_om_behovs

cap_svar = assemble_context(...) # whatever CAP-Shield returned you svar = eskalera_om_behovs(cap_svar, fraga="How many times did I mention X?", modell="claude") # or modell="gpt-5-mini" print(svar["svar"])

If escalate_recommended is false, nothing is sent to any model — the function returns immediately, so it is safe to call unconditionally on every response; it only spends an API call when CAP-Shield actually asked for one.

python cap_escalate_helper.py --demo shows exactly what would be sent, no key required.

A more targeted entry point, eskalera_om_behovs_v5, asks the model to only extract the raw pieces (amounts, dates, event names) and lets plain Python do the counting, summing or sorting — removing an entire class of arithmetic/sequencing mistakes a model can make answering in free text. It is the version used in our own benchmark validation of this feature.

Reproducing a number we published against your own run requires the current version of this file — the prompts and matching logic behind it are still actively tuned, and an older local copy can score meaningfully differently.

What the numbers mean

Compression saves bytes over the wire. Selection saves tokens in the context. Two different mechanisms — adding them together produces a number that means nothing.

Compressed packets are decompressed before a model sees them, so this does not reduce inference cost. Saying otherwise is the easiest way to be wrong about this project.

Every figure is published live, including what has *not* been measured and which packages perform badly:

https://cap-shield-robin.fly.dev/.well-known/cap-shield.json

Fetch that rather than trusting this file. It goes stale; the document does not.

Measuring without MCP

pip install cap-shield

from cap_shield import measure, print_measurement

print_measurement(measure(texts=[...], query="..."))

No account, nothing stored. The response includes the degraded share — how many of your messages came out larger.

Batching has a security condition

Batching compresses several messages in the same context, which opens a CRIME/BREACH-style side channel: someone who can place chosen text in the same batch as a secret, and observe the batch size, learns something about the secret.

Only batch messages that already share a trust boundary. Optional padding closes the leak for under two bytes a message, and it is off by default — we say so rather than let you assume otherwise.

Individual packing does not have this problem at all.

Portability

Dictionary versions are never deleted, and the guarantee does not rest on us still being here: the archive export carries the dictionary binaries, and a standalone unpacker runs with no gateway, no network and no other part of the system.

https://cap-shield-robin.fly.dev/cap_unpack.py

It is served without a token, because whoever needs it most is whoever no longer has an account.

Status

Beta. Server version 0.5.0.

Docs: https://cap-shield-robin.fly.dev/docs/quickstart Console: https://cap-shield-console.lovable.app

Licence

MIT — see LICENSE.