# 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 six tools need no account.** Measure first, decide after.

## Install

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

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

Python 3.9+. Nothing else.

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

## 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.

### `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.

```bash
pip install anthropic   # or: pip install openai
export ANTHROPIC_API_KEY=...
```

```python
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

```bash
pip install cap-shield
```

```python
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](LICENSE).