min-mcp — fix the MCP servers you don't own, and minify them on the way through
A repair-and-minification proxy for Model Context Protocol
servers, written in Rust. You don't own the servers your agents depend on, and you
can't edit them — so today you fork them, or paper over their flaws in every
agent's prompt. min-mcp patches them : a versioned,
drift-checked you can prove with in CI. On the way
through it also minifies the surface, so a 17,000-operation API arrives as three
searchable tools instead of a context bill. And it runs where your agents run:
behind the gateway you already have, with a caller identity per request, scopes
and rate limits per caller, and an audit line per call.
Minifying proxy for MCP servers and OpenAPI specs: your agent sees three searchable tools instead of every upstream's full catalog, and overlays fix the tools you don't own.
Estrelas
2
Ferramentas
—
Disponibilidade
—
as they pass through
overlay
minmcp verify
┌─ overlay: patch schemas, rewrite errors, reshape responses
│ (drift-checked, verified in CI)
your gateway ──► minmcp ──► GitHub's MCP server (85 tools)
(bearer or │ │────► Stripe's OpenAPI spec (589 operations)
identity headers) │ └────► Microsoft Graph's OpenAPI spec (17,531 operations)
└─ per request: who → which tools → how many calls → audit line
Why
Two things break as teams adopt MCP at scale. One of them is now being solved for
you; the other isn't.
1. The tools you depend on are broken, and you can't edit them. The ecosystem
is rough — around half of registry servers are effectively dead,
descriptions routinely diverge from behavior, and by week two of production you
hit "errors the model can't act on… tools silently disappearing… responses
exceeding size limits." (StackOne)
Forking someone else's server means owning their release cadence forever; prompt
patches rot silently and can't be tested. Nothing in the platforms addresses this:
clients can now find tools well, but none of them can fix one.
2. The context tax — increasingly handled by your client. Tool definitions are
loaded into every request, and a typical 5–10 server stack burns 100,000–200,000
tokens before the user types a character.
Both major clients now defer loading and search on demand, so if you run a handful
of ordinary MCP servers, your client may already cover this — see
About tool search for what they do and where the
limits actually bite. min-mcp still matters at the top end: mounting an API that
has no MCP server at all, and catalogs past the size a client can defer.
min-mcp does both, in that order: it fixes the tools you don't own (patch
descriptions and schemas, rewrite unhelpful errors, reshape responses) as a
drift-checked binding instead of a fork, and it minifies the surface so every
tool stays reachable through a small searchable set.
→ Concepts
How it works
1. Fix — overlays. The tools you're proxying are often broken (undocumented
required params, unhelpful errors, bloated responses), and you can't edit someone
else's server. An overlay patches a tool as it passes through the proxy — you
name a tool id and override the parts you want:
overlays:
- tool: github.issues/create
description: "Create an issue. Requires owner, repo, and title."
fields:
body.title: { required: true, description: "issue title; ask the user, never invent" }
error_hints:
- contains: "404"
hint: "Repo not found — re-check owner/repo; don't retry with a guess."
Overlays can rewrite descriptions and errors, patch the input schema (mark params
required, add enums/examples, hide noise), inject request defaults/headers
(with {{uuid}}/{{hash}} generators), guard a flaky tool (timeout_s,
breaker), auto-follow pagination, and reshape responses — each a versioned,
drift-checked binding you can prove with minmcp verify, instead of forking the
server or patching every agent's prompt. → Overlays
2. Minify — the 3-tool surface. In the default three_tool mode the agent
sees exactly three tools, regardless of how big the upstreams are:
search_tools(query, k) — BM25 over every upstream tool → ranked ids + summaries
get_tool_details(tool_id) — the full schema on demand (the source map)
call_tool(tool_id, arguments, fields) — routes to the owning upstream, runs the
call, and — with the optional fields filter — projects the response down to
just the dotted paths you ask for (["data[].id", "data[].amount"]), GraphQL-style,
so a big result doesn't flood the context. Omit fields for the whole response.
It searches for the operation it needs, pulls that one schema, calls it, and keeps
only the fields it asked for. You point min-mcp at upstreams two ways — proxy
running MCP servers, or mount an OpenAPI spec directly — through one config
and one interface. Search is BM25 over the bm25
crate behind a convention-aware tokenizer: PostCheckoutSessions, read_file, and
list-pull-requests are all findable by their words.
3. Run it behind your gateway. One minmcp serve --http serves many callers.
Each request is identified on its own — a bearer validated here (HS256 / RS256 /
JWKS, with aud / iss checks), or identity headers from a gateway that already
did the work — and sees only what its scopes grant: hidden tools are never listed,
searched, or callable. Token-bucket rate limits per caller, per caller-and-tool,
and per tool across callers refuse with a retry-after the agent can act on. Every
search, lookup, and call writes an NDJSON audit line naming the caller, the
tool, its origin, the outcome, latency, and size — to a file or to stderr for your
log shipper. Credentials are references into the environment, mounted secret
files, or HashiCorp Vault, never values in the config. A dead upstream is
respawned, not fatal. → Transports & auth,
examples/enterprise.yaml
4. Also.
Minify responses too. Beyond the fields filter, overlays reshape any response
server-side (strip secrets/PII/noise, rename, project) — over any API, even ones
with no field-selection of their own.
Detect → verify.minmcp lint flags best-practice smells (thin descriptions,
undocumented-required params, confusable tools); minmcp verify proves a fix with
real calls and deterministic assertions — a CI / behavioural-drift gate.
Compose. A workflows: entry runs a fixed multi-step chain as one composite
tool — a measured composite cut a 3-step task 6.8× on tokens. Composites
Transports & auth. Serve over stdio or Streamable HTTP; proxy a local
subprocess, a remote MCP server over HTTP, or a spec — with per-upstream headers,
outbound OAuth, and JWT-derived caller scopes. Transports & auth
Gate visibility. Static filters: drop whole APIs or tool families for
everyone; per-caller scopes: hide what a caller's identity doesn't grant. A
passthrough mode federates tools directly when the surface is already small.
Security
Everything is off by default — min-mcp on loopback with no auth: is a
development tool. What you turn on when it becomes infrastructure:
Identity
Per-request caller over HTTP: a validated bearer, or identity headers from a gateway. Scopes are default-deny once any rule exists
Revocation
RFC 7662 introspection, so a validly-signed token can still be refused once revoked
Wire
TLS on the listener, and mutual TLS — which is what makes trusting a gateway's identity headers sound rather than assumed
Tool definitions checked for poisoning at startup; strict refuses to serve a flagged tool
Audit
Every call recorded with its caller, and optionally HMAC-chained so tampering is detectable (minmcp audit-verify), with a keyed fingerprint of its arguments that names the call without logging them
Rollout
minmcp access shows who can reach what and flags open defaults; scopes and rate limits can run report_only, logging what they would refuse before they do
Supply chain
cargo audit on every push and weekly — it has already caught a TLS advisory filed against a dependency nothing had touched
You need Rust (stable) and a clone; there's nothing else to
install and no service to run:
git clone https://github.com/andrewgoodchild/min-mcp && cd min-mcp
cargo build --release # a few minutes from cold; binary at ./target/release/minmcp
Prefer not to build? Prebuilt binaries for Linux, Apple Silicon macOS, and
Windows are on the Releases
page, or cargo install min-mcp puts minmcp on your PATH (Rust 1.91 or
newer).
Everything below runs from the repo root. See it work on the bundled
120-operation spec — no network, no credentials:
Explore that surface without an agent — the CLI mirrors the three tools:
./target/release/minmcp search --config bench/bigapi.yaml "create a widget"
./target/release/minmcp help --config bench/bigapi.yaml "big.widgets/create"
And see the headline feature — fixing a tool you don't own — on the bundled
demo config, annotated line by line (examples/demo-overlays.yaml):
./target/release/minmcp help --config examples/demo-overlays.yaml acme.widgets/create
# the schema the agent sees: overlay-patched — undocumented param now required,
# enum constrained, an env-injected field stripped so the agent can't fabricate it
./target/release/minmcp lint --config examples/demo-overlays.yaml # find what needs fixing
./target/release/minmcp map --config examples/demo-overlays.yaml # which tools an overlay touched
Or point it at a real public MCP server — GitHub's official one, all toolsets
enabled (needs Docker and a GitHub token):
Then point it at your own upstreams — MCP servers you already run, or a spec:
# a) Proxy MCP servers (copy the template and edit it for your server):
./target/release/minmcp serve --config examples/proxy-mcp-server.yaml
# b) Or mount an OpenAPI spec directly — every operation in Stripe's spec → 3 tools.
# Download it from github.com/stripe/openapi next to the config as stripe.json:
STRIPE_TEST_KEY=sk_test_... ./target/release/minmcp inspect --config examples/stripe-from-spec.yaml
And the deployment shape — behind a gateway, many callers, one process. The
bundled config trusts identity headers a gateway would set; a request without
them is refused, and two callers with different scopes see two different surfaces:
The minification claim is falsifiable, so it gets measured (the fixing side —
structured errors taking a weak agent 0%→100%, a composite cutting a task 6.8× —
is measured too; see Measurements):
85 tools → 3 proxying GitHub's official MCP server: ~20,822 tokens of
definitions → ~424 (49×). Add more upstreams and the 424 does not move.
A Stripe + GitHub stack (1,803 tools) is ~687K tokens — it does not fit a
context window; min-mcp serves it in ~424.
Behaviour preserved: proxying a 587-tool Stripe server reproduced its
task-success set exactly at 58× fewer tokens, verified against live API
state with no LLM judges.
Reproducible right here:./bench/compression.sh (offline, no key),
asserted in CI.
Full numbers, reproduction steps, and what is not measured →
Measurements.
stdio/HTTP, per-request caller identity (JWT or gateway headers), rate limits, the audit stream, secrets (env/file/Vault), upstream health, what is deliberately not built
read this first — what Claude and Codex do natively, Atlassian's peer proxy measured head-to-head, and when min-mcp fits alongside an agent with built-in catalog search
every number, how to reproduce it, and what isn't measured
License
Apache-2.0. Third-party material (the OpenAPI specs you mount, and the
Rust dependencies) is recorded in THIRD_PARTY_NOTICES.md.
M
Min
andrewgoodchild·2 estrelas·
Minifying proxy for MCP servers and OpenAPI specs: your agent sees three searchable tools instead of every upstream's full catalog, and overlays fix the tools you don't own.
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Min?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Min precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte Min usa?
Min roda localmente via stdio.
Quando Min foi verificado pela última vez?
Última verificação: 2026-11-05. Minifying proxy for MCP servers and OpenAPI specs: your agent sees three searchable tools instead of every upstream's full catalog, and overlays fix the tools you don't own.