Skip to content

Releases

v0.3.0

Choose a tag to compare

@github-actions github-actions released this 01 Nov 03:48
2576037

Added

  • Upstreams speak MCP 2026-07-28. Each upstream is probed with server/discover
    and used statelessly if it answers: no handshake or session, _meta on every
    request, and Mcp-Method, Mcp-Name and Mcp-Param-* headers over HTTP. A server
    that doesn't falls back to initialize, so existing upstreams keep working. Before
    this, a modern-only upstream failed at startup, and with optional: true it was
    skipped. The agent-facing side already spoke this revision through rmcp; tests now
    pin that.
  • An upstream's input_required result is an error, not an empty success.
  • Spec tools from GET operations declare readOnlyHint in passthrough.
  • Double-encoded arguments are decoded. A model that sends an object or array
    parameter as a JSON string used to get missing_required_field for fields it had
    supplied, and retried the same call. Such a string now becomes the declared type.
  • min-mcp logs an error when skipping optional upstreams 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,
    icons and _meta now 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 recommends fields, which passthrough tools don't have. An answer
    past the old cap was unreachable. three_tool keeps 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

Full Changelog: v0.2.3...v0.3.0

v0.2.3

Choose a tag to compare

@github-actions github-actions released this 31 Oct 07:47
c7270e9

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::new and 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

Choose a tag to compare

@github-actions github-actions released this 21 Sep 21:15

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 — the serve --http listener including mutual TLS, and every
    outbound connection to an upstream, an IdP, or Vault.
    Caught by the cargo audit job, 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 unexpired exp prove 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: false is a 401. A response missing active is 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 own exp, and the cache is bounded.
    • fail_open is 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 the quinn HTTP/3 stack and webpki-roots. No aws-lc,
    native-tls or openssl anywhere in the tree, before or after.
    • The feature is rustls-no-provider, not rustls: in 0.13 rustls implies
      aws-lc-rs, which needs NASM on Windows x86-64 — the C toolchain this
      project pins ring to avoid. (form and query also 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 in main is not sufficient and was tried: a
      unit test never runs main, 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.

Fixed — secrets

  • ${vault:…} panicked the process instead of resolving a secret. vaultrs
    is built with rustls-no-provider so it shares the ring provider 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, 0 disables) — a ceiling on tool
    calls in flight to upstreams at once, across every caller and both transports.
    This closes the gap http.limits.max_in_flight was 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 audit on dependency changes, on push to main, and weekly, because
    advisories are published against dependencies that have not changed. A yanked
    chacha20 reached this tree through rmcp → rand and was caught only because
    cargo publish --dry-run happened to warn; nothing in the gate would have
    found it, and release binaries are built from that lockfile. Vulnerabilities
    and yanked crates fail; unmaintained stays 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: anonymous is 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), else anonymous. 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 one anonymous bucket 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_policy decides what the SERVER does about a tool whose name or
    description trips a tool-poisoning rule, which until now was only ever
    reported by minmcp lint: warn (default) names each flagged tool and
    serves it, strict refuses to start, off skips the check. The rules are
    factored out of lint() so they resolve no schemas — minmcp lint is 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_file terminate TLS in
    serve --http itself; the banner reads https://. 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, like spec:.
  • Mutual TLS. http.tls.client_ca_file requires 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_headers safe 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_s and breaker.
    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.limits cannot 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"), and secret_solicitation (a local credential artifact like
    ~/.ssh/id_rsa that 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...
Read more

v0.1.1

Choose a tag to compare

@github-actions github-actions released this 12 Aug 09:04

Search, rebuilt on measurement

  • BM25 core replaced by the bm25 crate (the
    engine openai/codex uses 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 NDJSON shadow events. 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_format now defaults
    per upstream kind: raw for MCP/HTTP upstreams (their bytes are not ours to
    rewrite — compacting a pretty-printed read_file result mangled the file's
    real formatting and broke whitespace-sensitive error_hints/verify
    matchers), json for spec upstreams (min-mcp builds that envelope, so
    compacting stays free and safe). result_format: json remains 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 against body
    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

Choose a tag to compare

@github-actions github-actions released this 09 Aug 11:39

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_tool mode (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-style fields response projection).
    Constant ~424 tokens regardless of upstream size.
  • passthrough mode — 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 own minmcp://tools source-map resource.

Fixing tools you don't own (overlays)

  • Patch descriptions, and the input schema by dotted path: required,
    example, enum, type, format, hide, and user_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_hints with a field: 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-endpoint headers with ${ENV} and
    {{uuid}}/{{now}}/{{iso8601}}/{{hash}} generators.
  • Response shaping — declarative remove/rename/set/keep plus a jq
    escape hatch; auto-paginate follows 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_sha pins the schema an overlay was
    written against; binding: weak|strong chooses 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-caller scopes: 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 body as
    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: raw opts out per upstream.
  • Opt-in idempotent-read cache (read_cache_ttl_s) for spec GETs,
    readOnlyHint tools, or overlay cacheable: true — canonical (key-order
    insensitive) cache keys, write-through invalidation, and shaping re-applied
    per call so a hit still honours that call's fields.

Tooling

  • minmcp serve (stdio or --http), inspect, map (source map, --diff for
    drift), verify (run overlay checks against the live upstream — a CI gate),
    lint (best-practice smells with per-rule stats), and search / help /
    call mirroring the three tools from the shell.
  • NDJSON observability (log_file) and leveled logging via MINMCP_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