Repository navigation
Releases
v0.3.0
Added
- Upstreams speak MCP 2026-07-28. Each upstream is probed with
server/discover
and used statelessly if it answers: no handshake or session,_metaon every
request, andMcp-Method,Mcp-NameandMcp-Param-*headers over HTTP. A server
that doesn't falls back toinitialize, so existing upstreams keep working. Before
this, a modern-only upstream failed at startup, and withoptional: trueit was
skipped. The agent-facing side already spoke this revision through rmcp; tests now
pin that. - An upstream's
input_requiredresult is an error, not an empty success. - Spec tools from GET operations declare
readOnlyHintin passthrough. - Double-encoded arguments are decoded. A model that sends an object or array
parameter as a JSON string used to getmissing_required_fieldfor fields it had
supplied, and retried the same call. Such a string now becomes the declared type. - min-mcp logs an error when skipping
optionalupstreams leaves no tools at all.
Changed
- Passthrough keeps tool names. A tool is declared as
get_thing, not
upstream_get_thing; only a name two upstreams share is prefixed, on both sides.
This renames tools, so check any client permission rules written against the old
names. Tool ids (upstream.get_thing), and so scopes, overlays and audit, don't
change. - Passthrough keeps tool definitions.
title,annotations,outputSchema,
iconsand_metanow reach the client, and descriptions are no longer capped at
1,000 characters. An overlay that reshapes a tool's result withdraws its
outputSchema. - Passthrough results are capped at 64,000 bytes, not 8,000, and the truncation
notice no longer recommendsfields, which passthrough tools don't have. An answer
past the old cap was unreachable.three_toolkeeps its 8,000-byte budget. - Corrected the README and About tool search, which overstated what platforms can't
do, and added what a proxy costs.
What's Changed
- release: v0.3.0 (MCP 2026-07-28 upstreams, passthrough fidelity) by @andrewgoodchild in #37
Full Changelog: v0.2.3...v0.3.0
v0.2.3
Security
- rustls-webpki 0.103.15 → 0.103.16 for
RUSTSEC-2026-0382
(certificate verification may accept distrusted intermediates). It sits on the
TLS path of every outbound HTTPS connection, so upgrade from the 0.2.2 binaries. - webpki-root-certs 1.0.9 → 1.0.11 for
RUSTSEC-2026-0383
(bundled roots allow trust in distrusted emSign intermediates). - tokio 1.53.2 → 1.54.1 for
RUSTSEC-2026-0386
(AsyncFd::newand related constructors violate I/O safety).
Changed
- Dependencies: rmcp 3.5 → 3.8, hyper-rustls 0.27.9 → 0.27.10, serde_json
1.0.151 → 1.0.154, jaq-core 3.1.1 → 3.1.2, jaq-std 3.0.3 → 3.0.4, and a full
lockfile refresh of everything else.
What's Changed
- chore(deps): bump the minor-and-patch group across 1 directory with 5 updates by @dependabot[bot] in #35
- release: v0.2.3 (security patch) by @andrewgoodchild in #36
Full Changelog: v0.2.2...v0.2.3
v0.2.0
Security — rustls advisory
- rustls 0.23.44 → 0.23.45, for
RUSTSEC-2026-0285
(published 2026-09-14): TLS 1.3 handshake messages incorrectly accepted
across encryption level boundaries, 5.3 medium. rustls is min-mcp's TLS
everywhere — theserve --httplistener including mutual TLS, and every
outbound connection to an upstream, an IdP, or Vault.
Caught by thecargo auditjob, which is exactly the case it was added for:
an advisory published against a dependency that had not changed. Nothing in
this repo moved; the advisory came to us.
Added — token revocation
- Token revocation via RFC 7662 introspection (
auth.introspection). A
signature and an unexpiredexpprove a token was issued and has not
lapsed; neither can say it was revoked since. JWKS rotation withdraws a key,
killing every token it signed — this refuses one.active: falseis a 401. A response missingactiveis treated as not
live: it is the only field RFC 7662 requires, and defaulting the other way
would let a malformed response grant access.- Verdicts are cached (
cache_ttl_s, default 60), so the TTL is the
revocation latency — a revoked token works for at most that long. Never
cached past the token's ownexp, and the cache is bounded. fail_openis off by default: an unreachable endpoint refuses the
request. A revocation check that serves traffic when the authority is
unreachable is advisory, not a control. Turning it on trades revocation for
availability during an outage.- Cache keys are a hash of the token, never the token, since the map outlives
the request.
Changed — one HTTP stack, and the Origin check delegated
- reqwest 0.12 → 0.13, unifying the dependency tree. vaultrs already pulled
0.13, so both majors were being compiled into the binary. One HTTP stack now:
266 packages, down from 277 — reqwest 0.12 itself plus the ten crates only
it pulled, including thequinnHTTP/3 stack andwebpki-roots. Noaws-lc,
native-tlsoropensslanywhere in the tree, before or after.- The feature is
rustls-no-provider, notrustls: in 0.13rustlsimplies
aws-lc-rs, which needs NASM on Windows x86-64 — the C toolchain this
project pinsringto avoid. (formandqueryalso moved behind their
own features.) - "No provider" means the process default, and building a client panics
when there is none. That install now lives in one place
(crate::crypto::install_provider) and is called from every site that
builds a client. Putting it inmainis not sufficient and was tried: a
unit test never runsmain, so 19 tests panicked on the first client they
built. Three crates have now hit this exact failure — vaultrs, jsonwebtoken
11, and reqwest 0.13 — so the shared install replaces the Vault-only one. - Outbound TLS now verifies against the OS trust store
(rustls-platform-verifier) rather than a bundled root set. For an upstream
with a private CA this means the certificate must be trusted by the host,
which is usually what an operator already expects; it is a behaviour change
either way. Smoke-tested against a real HTTPS endpoint, since every upstream
fixture in the suite is deliberately offline and cannot exercise it.
- The feature is
Fixed — secrets
${vault:…}panicked the process instead of resolving a secret. vaultrs
is built withrustls-no-providerso it shares theringprovider already in
the tree rather than dragging in aws-lc; "no provider" means it takes the
process default, and reqwest panics while building its client when none is
installed. Nothing installed one, so every Vault reference aborted min-mcp —
the feature could not work at all, on any path that reached it. A provider is
now installed on the Vault path (once, and only when Vault is actually used).
Found by testing it: the credential path had no coverage precisely because it
needed a Vault to talk to.
Added — upstream concurrency and dependency auditing
max_concurrent_calls(default 256,0disables) — a ceiling on tool
calls in flight to upstreams at once, across every caller and both transports.
This closes the gaphttp.limits.max_in_flightwas documented as not
covering: that permit is released when the SSE stream is handed back, before
the tool runs, so it bounds request handling rather than upstream work.
Nothing previously bounded the connections, sockets and buffers a burst of
calls actually costs. The slot is held across the upstream call only — never
across caching, shaping or a pagination follow-up, which would let a call wait
on a slot its own parent holds.- Dependency advisories in CI (
.github/workflows/audit.yml) —cargo auditon dependency changes, on push tomain, and weekly, because
advisories are published against dependencies that have not changed. A yanked
chacha20reached this tree throughrmcp → randand was caught only because
cargo publish --dry-runhappened to warn; nothing in the gate would have
found it, and release binaries are built from that lockfile. Vulnerabilities
and yanked crates fail;unmaintainedstays a warning, since it is a
maintenance signal rather than an exploitable flaw and is usually not ours to
fix. Plus a Dependabot config for grouped weekly updates.
Added — caller identity and poisoning enforcement
-
Rate-limit buckets key on
Caller::rate_key(), not the audit label. The
two answer different questions for a caller nobody named:anonymousis the
right word for an audit line and the wrong key for a bucket, where it charged
every unnamed caller to one budget. The key is now the subject, else what the
connection knows (the client certificate's fingerprint under mutual TLS, else
the peer address), elseanonymous. The fallback is a bucket key only — it
never reaches an audit line and never grants a scope, because it names a
socket rather than a person.This is an improvement, not a cure, and it changes how limits are spent:
callers that previously shared oneanonymousbucket now get one each, so
aggregate throughput can rise where a deployment was relying on that shared
bucket as a global cap. It still does not separate callers behind one gateway
— they share a peer address — so the startup warning stays, now describing the
fallback rather than claiming a single shared bucket. -
poisoning_policydecides what the SERVER does about a tool whose name or
description trips a tool-poisoning rule, which until now was only ever
reported byminmcp lint:warn(default) names each flagged tool and
serves it,strictrefuses to start,offskips the check. The rules are
factored out oflint()so they resolve no schemas —minmcp lintis opt-in
precisely because resolving every schema is O(tools), and the startup check
reads names and descriptions only. One rule set, two callers, so a tool the
linter flags and a tool the server refuses can never disagree.
Added — transport hardening
- TLS on the listener.
http.tls.cert_file/key_fileterminate TLS in
serve --httpitself; the banner readshttps://. A certificate that cannot
be read, parsed, or matched to its key fails at startup, not per
connection. Paths resolve relative to the config file, likespec:. - Mutual TLS.
http.tls.client_ca_filerequires every connection to present
a client certificate chaining to that CA, closed during the handshake if not.
This authenticates the channel, not the caller: it is what makes
auth.trusted_headerssafe to believe, by enforcing that the gateway is the
only route to the port instead of assuming it from network policy. Being a
real authentication boundary, it also satisfies the non-loopback bind guard. - Request caps.
http.limits.max_body_bytes(default 1 MiB) refuses an
oversize body with 413 whether or not it declares a length, buffering nothing
past the cap (the value is handed to rmcp, whose own 4 MiB default would
otherwise silently override any larger setting);
http.limits.max_in_flight(default 256) bounds requests
the MCP service is inside at once across all connections, queueing rather than
failing past it. It bounds request handling, not concurrent upstream calls:
the permit is released when the response future resolves, and an SSE reply
resolves before the tool runs (measured — with a cap of 1, three concurrent 4s
calls still finish in ~4s). Upstream concurrency is governed by rate limits,
timeout_sandbreaker.
Both are validated at startup — 0 is rejected rather than accepted as "hang
every request forever". - Connection deadlines, so a client that opens sockets and sends nothing
cannot pin tasks and descriptors indefinitely — the one allocation
http.limitscannot bound, since no request exists to count. A TLS handshake
gets 10s; a request head gets 30s on either scheme. The two differ on purpose:
hyper applies the head deadline to every request on a connection, so it is
also the idle keep-alive timeout, and reusing the handshake's 10s there would
drop connections whenever an agent paused to think, charging a fresh TCP (and
TLS) handshake to the next tool call. A long-lived SSE stream is unaffected —
the deadline is on reading a request, not on writing a response. - Three tool-poisoning lint rules —
hidden_text(zero-width characters,
bidi overrides, tag characters in a name or description),
model_directed_instruction("ignore previous instructions", "do not tell the
user"), andsecret_solicitation(a local credential artifact like
~/.ssh/id_rsathat a remote tool cannot need). Tuned against real specs: all
three fire zero times across Stripe (589 ops) and GitHub (1,216 ops). Matching
credent...
v0.1.1
Search, rebuilt on measurement
- BM25 core replaced by the
bm25crate (the
engineopenai/codexuses for its tool search), at the crate's default
parameters — which beat our previous hand-tuned constants on the recall harness. - Convention-aware tokenizer. Identifiers split on camelCase, snake_case,
kebab-case, dots, slashes and acronym runs before stemming. Previously
snake_case tool names — most of the MCP ecosystem — indexed as single opaque
tokens (read_file→read_fil) and were unfindable by natural queries;
fixing it measured +15 points recall@1 on a snake_case server. - Flat indexing. Field weighting by repetition (id ×3, summary ×2) measured
worse than no weighting and was removed. - Usage prior counts successes only. A tool can no longer rise in search
ranking by being called and failing — previously preflight rejections and
upstream errors all counted as "usage". shadow: true— score alternative retrieval configurations against real
traffic without serving them, logged per call as NDJSONshadowevents. The
instrument that produced every claim above, shipped so the claims can be
re-checked on your workload.- Measured and not shipped, with numbers in
docs/measurements.md: schema/parameter-text indexing
(dilutes single-API corpora), embedding retrieval (significant regression on
verbatim queries), naive RRF fusion (poisoned by zero-signal lexical lists),
and larger description caps (upstream brevity, not our caps, is the
constraint).
Fixed
- MCP/HTTP results are byte-faithful by default.
result_formatnow defaults
per upstream kind:rawfor MCP/HTTP upstreams (their bytes are not ours to
rewrite — compacting a pretty-printedread_fileresult mangled the file's
real formatting and broke whitespace-sensitiveerror_hints/verify
matchers),jsonfor spec upstreams (min-mcp builds that envelope, so
compacting stays free and safe).result_format: jsonremains the opt-in for
MCP servers whose results are JSON payloads rather than documents. Origin: http://[::1](bare IPv6 loopback, no port) was refused by the HTTP
transport's DNS-rebinding check — the port stripper cut inside the literal.- A timeout or transport failure on a pagination follow-up page discarded all
already-fetched pages as a protocol error; it now stops pagination and returns
the partial list with the PAGINATION notice. - An MCP result shaped like
{"status":…,"body":…}was mistaken for the spec
envelope, so projections and workflow outputs silently ran againstbody
only. Envelope unwrapping is now gated on the upstream actually being a spec
backend, not on result shape.
Docs
- New About tool search: what Claude and Codex now
do natively, verified against primary sources, and the four places their
limits bite. The standalone mcp-compressor comparison is folded in as a
section — same measured record, framed as the proxy generation the platforms
absorbed — and its page retired. README reframed accordingly: fixing leads,
minification supports. - Filters documented as a search-quality lever, not only access control.
Full Changelog: v0.1.0...v0.1.1
v0.1.0
First public version. A minifying proxy for MCP servers and OpenAPI specs:
your agent sees three tools instead of every upstream's catalog, and you can
patch the tools you don't own on the way through.
Surface
three_toolmode (default) —search_tools(BM25 over every upstream
tool),get_tool_details(full schema on demand),call_tool(routes to the
owning upstream, with optional GraphQL-stylefieldsresponse projection).
Constant ~424 tokens regardless of upstream size.passthroughmode — declare every tool by name, for surfaces small enough
that three meta-tools cost more than the catalog. The startup banner tells you
when you're in that regime.- Three upstream kinds — MCP server subprocess, remote MCP server over
Streamable HTTP, and a mounted OpenAPI spec (pure-Rust converter, body
encoding chosen from the spec's declared media type). - Federation — many upstreams, one search index, still three tools.
- Staged schema minification in
get_tool_details: over-budget schemas
degrade prose → structure-only → depth-pruned with explicit elision counts,
so every field name survives. No blind truncation. - Near-miss suggestions on an unknown tool id.
- Prompts and resources passthrough, namespaced and scope-gated, plus
min-mcp's ownminmcp://toolssource-map resource.
Fixing tools you don't own (overlays)
- Patch descriptions, and the input schema by dotted path:
required,
example,enum,type,format,hide, anduser_supplied(strips a
field from the agent's schema and injects it from the environment, so it
can't be fabricated). - Errors as continuation prompts —
error_hintswith afield:pointer
render a structured{field, allowed_values, fix}error;retryable:gives
an explicit transient/permanent signal. preflight— local required/enum validation before the upstream call,
on by default, container-aware, with a per-tool opt-out.- Request shaping —
defaults, per-endpointheaderswith${ENV}and
{{uuid}}/{{now}}/{{iso8601}}/{{hash}}generators. - Response shaping — declarative
remove/rename/set/keepplus a jq
escape hatch; auto-paginatefollows a cursor and concatenates pages. timeout_s— per-tool call deadline; on expiry the agent is told the
operation may or may not have completed, so a write is never blindly retried.breaker— per-tool circuit breaker (closed → open → half-open probe).
While open, calls are refused locally with a recovery prompt instead of the
agent burning turns on a tool that fails identically every time.- Drift-checked bindings —
authored_shapins the schema an overlay was
written against;binding: weak|strongchooses fail-open or fail-closed. search aliases— make a badly-named tool findable without changing its
id.- Composites — a
workflows:entry runs a fixed multi-step chain as one
tool, threading each step's outputs into the next.
Visibility and auth
- Static
filters:(include/exclude whole APIs or tool families, for everyone)
and per-callerscopes:derived from a validated JWT (HS256, RS256,
JWKS). A scoped-out tool is never listed, searched, callable, or visible in
the source map. - Per-upstream auth headers with
${ENV}expansion, and outbound OAuth
(client-credentials) for OAuth-protected upstreams. - Path-parameter injection hardening: agent-supplied path params are strictly
segment-encoded, so..or/cannot reach a different endpoint. - HTTP serving validates both DNS-rebinding headers —
Host(via rmcp) and
Origin(loopback-only when present).
Results
- Compact JSON by default on every path: the spec envelope embeds
bodyas
JSON rather than an escaped string, and MCP text results are compacted
lexically (whitespace outside strings only — number literals pass through
byte-for-byte).result_format: rawopts out per upstream. - Opt-in idempotent-read cache (
read_cache_ttl_s) for specGETs,
readOnlyHinttools, or overlaycacheable: true— canonical (key-order
insensitive) cache keys, write-through invalidation, and shaping re-applied
per call so a hit still honours that call'sfields.
Tooling
minmcp serve(stdio or--http),inspect,map(source map,--difffor
drift),verify(run overlay checks against the live upstream — a CI gate),
lint(best-practice smells with per-rule stats), andsearch/help/
callmirroring the three tools from the shell.- NDJSON observability (
log_file) and leveled logging viaMINMCP_LOG.
Not in this version
Field addition for prose-only bodies, async-poll and interactive-OAuth
overlays, and a result_format beyond json/raw (a markdown-table format is
measured and pending a comprehension gate — see
docs/about-toon.md).
Measured, then removed
hotset (usage-promoted working set), pd (uniform progressive disclosure),
and a TOON result encoder were all built, benchmarked, and deleted for losing
to the shipped defaults. See docs/measurements.md.
Full Changelog: https://github.com/andrewgoodchild/min-mcp/commits/v0.1.0