@ni-c/mcp-hub 0.10.0 → 0.11.1

package/CHANGELOG.md

@@ -7,6 +7,432 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- #region changelog -->
 
+## [0.11.1] - 2026-09-06
+
+### Security
+
+- **The published image shipped a vulnerable `libssh2`, and no amount of
+  rescanning was going to change that.** `libssh2-1 1.10.0-3+b1` — pulled in as
+  a dependency of `git`, which the image installs so servers can be fetched
+  straight from a repository — is affected by CVE-2026-7598 and CVE-2026-58050,
+  both HIGH, both fixed in `bookworm-security` as `1.10.0-3+deb12u1` before the
+  scanner ever reported them. The fix could not reach the image because the apt
+  layer was never rebuilt: the base digest is pinned and the apt command is a
+  constant, so the layer cache answered every build with the packages installed
+  the day it was first built. The image scanned green one afternoon and red
+  three hours later from the same cached layer, and a workflow rerun reproduced
+  the finding exactly.
+
+  Both Dockerfiles now take an `APT_SECURITY_EPOCH` build argument that is
+  interpolated into the apt command itself, and CI passes the current UTC date.
+  The layer therefore expires once a day rather than never, while builds within
+  a day stay cached. The argument has to appear *in* the command — BuildKit keys
+  a `RUN` on its expanded command line, and an ARG that is merely declared
+  invalidates nothing. In the hub image the npm replacement step moved above
+  that boundary: it is the expensive one, it rots with its pins rather than with
+  time, and it needs neither apt nor the system CA store.
+
+  This is the second time the same cache has held back a Debian security fix
+  (CVE-2026-56408 in `libexpat1` was the first), which is why the remedy is a
+  mechanism rather than another rebuild.
+
+### Changed
+
+- The npm tarball no longer carries the `.js.map` source maps — 61 files and
+  360 kB unpacked, against 540 kB of actual code. `sourceMap` stays on and the
+  maps are still built: the integration tests and CI run `dist/index.js` out of
+  a checkout, where `src/` sits right next to it and a stack trace resolves
+  through them. In an installed package it cannot — the sources those maps point
+  at are not part of it.
+
+## [0.11.0] - 2026-09-03
+
+### Added
+
+- **The meta-tools answer in both channels.** Five of the six now declare an
+  `outputSchema` and return the same object as `structuredContent` as well as
+  the JSON text block they always returned. A client that wants to *use* the
+  answer no longer has to parse a string and hope; one that wants to read it
+  still gets the text, because the SDK does not synthesize a text block for an
+  object-shaped value and dropping it would have left older clients with
+  nothing.
+
+  `list_servers` and `list_tools` therefore answer with `{"servers": […]}` and
+  `{"tools": […]}` rather than a bare array. That is the breaking part of this
+  change, and it is not cosmetic: the 2025 wire cannot carry a non-object
+  `structuredContent`, so the SDK wraps one in `{"result": …}` — and an
+  array-rooted answer would let a client tell from the payload which protocol
+  revision it had been given. The hub's promise is that it cannot. There is a
+  test comparing both eras field for field.
+
+  `call_tool` is the one without a schema. It returns the child's own result,
+  and a schema of the hub's would only be honest if the hub wrapped somebody
+  else's payload — which would break the passthrough the era matrix pins across
+  all four client/child combinations.
+
+- **`get_tool_schema` hands on the child's `outputSchema`.** This is the gap the
+  rest of the work uncovered. `call_tool` has always returned a child's
+  `structuredContent` verbatim, but the schema to validate it against was
+  dropped on the way out of `/hub`, so an aggregate client received structured
+  data it had no way to check — while `hub-tools.md` claimed structured content
+  "passes through". Half of it did.
+
+  `list_tools` marks such a tool with `hasOutputSchema: true` rather than
+  inlining the schema, so a large server's list stays a list. Both follow the
+  rule `annotations` already followed: the child's own document, verbatim, and
+  the key absent when it declared none.
+
+- **`list_tools` and `get_tool_schema` carry a child's tool annotations
+  through.** Over `/hub` a client never sees the child's own `tools/list`, so
+  those two answers are the only place it can learn that one of two similarly
+  named tools deletes and the other does not. They came back as name plus
+  description, which left every tool looking identical at exactly the moment a
+  model decides which to call. The proxy endpoint `/<name>/mcp` was already
+  correct; there is a test for it now too, because "already correct" is a
+  property that stops being true silently.
+
+  Verbatim, not summarised into a marker of the hub's own. The specification
+  says a client "MUST consider tool annotations to be untrusted unless they come
+  from trusted servers", and the hub is in no position to vouch for a child it
+  merely forwards to — a derived `kind` would have been the hub's claim about
+  somebody else's server. A child that declared nothing arrives with no
+  `annotations` key at all; an empty object would read as all four defaults,
+  which is a claim it did not make.
+
+- **The six meta-tools annotate themselves**, which they never did. The
+  specification gives `destructiveHint` and `openWorldHint` a default of `true`,
+  so silence declared `list_servers` a destructive tool in an open world.
+  `call_tool` is the one where that really is the answer: whatever the named
+  tool does, `call_tool` does.
+
+- **The hub speaks both MCP revisions on every endpoint.** `2026-07-28` and
+  `2025-11-25`, on `/hub`, on `/<name>/mcp` and over `--stdio`; the client
+  picks during its opening exchange and cannot tell from the answers which one
+  it got. Which traffic is carried on which revision is a
+  [matrix](https://mcp-hub.ni-c.de/reference/standards#what-is-carried-per-revision)
+  now, with a test behind every row, because this project has twice announced
+  something it did not deliver.
+
+  The 2025 path is untouched: it is served by the same transport that always
+  served it, so a `GET` still opens a stream and a `DELETE` still answers 200
+  rather than the 405 the modern handler's own fallback would give. claude.ai
+  opens that stream on every reconnect.
+
+- **Change notifications travel, on both sides.** A `2026-07-28` client opens a
+  `subscriptions/listen` stream and names what it wants — tool, prompt and
+  resource list changes, or specific resource URIs — and the hub delivers.
+  Upstream it subscribes to each child the way that child understands:
+  `subscriptions/listen` to a 2026 server, `resources/subscribe` to a 2025 one.
+  So a server that has never heard of the newer mechanism still reaches a client
+  that speaks nothing else, which is the common case in practice.
+  [Details](https://mcp-hub.ni-c.de/guide/subscriptions).
+
+  This is the second thing the 2026 revision made possible for a stateless
+  gateway, and for the same reason as the first: the state is the open HTTP
+  response rather than a session table, so a client reconnecting without closing
+  anything leaves nothing behind. One handler per route now outlives the
+  request, because it owns those streams — it holds the sockets currently open
+  and no record of who opened them.
+
+  The bookkeeping is a lease per stream rather than a reference count per URI.
+  A count cannot tell "nobody wants this any more" from "the one leaving wanted
+  it too", and gets it wrong in the direction that silently stops delivering to
+  the client that stayed.
+
+  A sleeping [on-demand](https://mcp-hub.ni-c.de/guide/on-demand) server watches
+  nothing: subscribing does not wake it — the acknowledgment comes from the
+  cached capabilities — and the subscription is re-established when something
+  else does, followed by a re-read signal for everything that client was
+  watching. What changed during the nap is not reported, only that there is
+  reason to look. `subscriptions: "off"` withdraws one server's right to push.
+
+- **An end-to-end suite that runs the hub the way it ships.** Three tiers: in
+  this process, as `node dist/index.js`, and as the published image through
+  `demo/compose.yml`. It is not part of `npm test`, which stays fast and stays
+  the pull-request gate; this one runs nightly, on any pull request that touches
+  it, and as a gate on release tags. [What it is
+  for](https://github.com/ni-c/mcp-hub/blob/main/e2e/README.md).
+
+  The tiers exist because a class of question cannot be asked from inside the
+  process being tested. `src/index.ts`'s startup block — environment parsing,
+  the listener, signal handlers — is entered only when the file is the program.
+  `mcp-hub-admin` is a *separate program* sharing `/data` with a running hub,
+  and a test that called the same `AuthStore` instance proves the hub can read
+  its own memory; that mistake shipped once, as a revocation that reported
+  success and did nothing. An `uncaughtException` in-process takes the test
+  runner down rather than the hub. And uid 1000, a read-only root filesystem,
+  the healthcheck and tini cannot be wrong in a bare process at all.
+
+  The consumer is a scripted agent rather than a model. It discovers through the
+  six meta-tools and then builds its arguments *from the schema the hub
+  published*, which is the whole point: a schema damaged in transit — truncated,
+  budget-clipped, missing a property it declares required — stops working there
+  and nowhere else. A model handed a broken schema improvises around it, and
+  improvisation is not an assertion.
+
+  Alongside it: thirteen fixture servers that each misbehave in one specific way
+  no off-the-shelf server does, a four-cell client-era × child-era matrix built
+  on one catalogue registered twice so a difference can only be the hub's, raw
+  `fetch` conformance checks that assert an HTTP status and a JSON-RPC code
+  together, and a recorder for what real clients put on the wire.
+
+- **`src/timings.ts`.** The supervisor's ping interval, wake timeout, idle
+  sweep and backoff curve read the environment, the same way `mcp-limits.ts`
+  already did for the call deadline. `IDLE_TIMEOUT_MS` is the sub-minute sibling
+  of `IDLE_TIMEOUT_MINUTES`.
+
+  Defaults are unchanged, so no deployment behaves differently. What changes is
+  that the behaviour becomes observable: at the shipped numbers, watching a
+  server fall asleep costs a minute and the five-minute backoff ceiling cannot
+  be reached at all. Four minutes of a test suite spent asleep is four minutes
+  somebody eventually deletes.
+
+- **`describe_connection`, behind `MCP_DIAGNOSTICS`.** A seventh meta-tool that
+  answers the one question a client cannot answer for itself: which protocol
+  era this connection is on, whether this request carried an elicitation
+  capability, and — for a named server — whether a question from it would
+  actually reach the person at the far end.
+
+  It exists because a server falling back to its two-call token looks identical
+  to a server that simply did not ask. From inside the client both are silence,
+  and only the hub knows which one it was. The first thing it reported in
+  anger: a connector on the `2026-07-28` era that declares no `elicitation`
+  capability at all — which the era, unlike the older one, would let it do.
+
+  Off by default. Not for safety — it reports only what the caller's own request
+  already carried, and nothing about any other client — but because every tool a
+  client can see costs context in every conversation it has, and "six meta-tools
+  instead of N×tools" is the argument for the aggregate. With the switch on,
+  `/hub` and `--stdio` serve seven.
+
+- **One log line when a question is dropped.** When the hub declines to carry a
+  child's elicitation it now says so once per client, server and reason, instead
+  of leaving the only trace inside a tool result that one caller sees. The
+  decision itself moved into a single function that both the forwarding path and
+  the new tool call, so the explanation cannot drift from the behaviour.
+
+### Fixed
+
+- **The meta-tools no longer advertise an empty schema where they mean
+  "anything".** Five fields carry a document the hub does not own — a child's
+  `annotations` on `list_tools` and `get_tool_schema`, the two schemas on
+  `get_tool_schema`, and the `arguments` of `call_tool` — and zod writes that
+  as `"additionalProperties": {}`. An empty schema is legal and means exactly
+  what `true` means, but it is the spelling some MCP clients refuse or
+  mishandle, which is the worst kind of bug to own: the tool works against the
+  client you tested with and fails against the one you did not.
+
+  Only the emitted JSON Schema changes. The runtime is still as permissive as
+  it has to be, and deliberately so: those fields are validated against the zod
+  schema, a child is free to put anything in them, and the SDK turns a refused
+  answer into an error result. A test walks every schema the hub advertises and
+  fails on any node that constrains nothing, so a future zod release cannot put
+  the spelling back without saying so.
+
+- **A non-object output schema now reaches a 2025 client with its value wrapped
+  to match.** The per-server endpoint writes its own `tools/call` handler, and
+  such a handler has to run the result through the wire codec itself. It did
+  not. The schema half was already being rewritten to `{"result": …}` on the
+  way out, so a child whose `outputSchema` describes an array handed a 2025
+  client a bare array to validate against a schema saying "object" — correct
+  data that looks broken. Both halves are projected now, and a fixture with an
+  array-rooted schema pins it on every era pair.
+
+  The e2e agent, which checks that a result carries everything its schema
+  requires, was silently doing nothing on the `/hub` door for the same reason:
+  the schema it read from `get_tool_schema` was always `undefined`. It bites
+  there now, and it also asserts that the text block and `structuredContent`
+  agree.
+
+- **Three capabilities the hub announced but did not serve.** `listChanged` for
+  tools, prompts and resources is now advertised only on the revision that
+  carries it, and is true there; `resources.subscribe` likewise, having been
+  stripped outright since 0.6.3. `logging` is no longer advertised at all —
+  `logging/setLevel` never had a handler, so a client that believed it got a
+  `-32601` at call time, and on `2026-07-28` the level is per-request `_meta`
+  with no RPC left to implement.
+
+  A 2025 client is now told none of the three. That is a visible change, and the
+  honest one: it was never going to receive any of them.
+
+- **A `subscriptions/listen` POST no longer occupies an in-flight slot.** It is
+  a POST whose response stays open for the life of the subscription, so counted
+  as work in progress it held one of `MCP_MAX_CONCURRENT_REQUESTS` (default
+  four) the entire time — a handful of subscribed clients would have locked
+  every tool call on the hub out with a 429 while nothing was running. It is the
+  standing channel by another name and is charged to
+  `MCP_MAX_CONCURRENT_STREAMS`, where the 2025 era's `GET` already went.
+
+- **Elicitation travels end to end.** A child server that needs to ask the
+  person at the far end something — `smtp-mcp` before it sends, `imap-mcp`
+  before it expunges a mailbox — now reaches them through the hub instead of
+  silently falling back to a weaker check. On `2026-07-28` a question is a
+  *result*, not a push: the call ends, the person decides, the client retries
+  with the answer. Nothing is held open, so the stateless transport is what
+  makes this work rather than what prevented it.
+
+  The hub adds what follows from the question crossing a trust boundary. It is
+  attributed to the server that asked, after the text has been stripped of the
+  bidirectional and zero-width characters that could visually undo that line.
+  Embedded `sampling/createMessage` and `roots/list` requests are dropped and
+  named in the log — relaying them would spend the caller's model budget and
+  hand out its workspace layout on a child's say-so. The child's `_meta` is
+  removed. The resumption state is signed and bound to the server, the tool,
+  the OAuth client and the endpoint, so it cannot be pasted onto another call.
+
+  The capability is mirrored per request from what the client itself declared,
+  and never widened — so it is announced only for a call whose answer has
+  somewhere to go. A `2025-11-25` client over HTTP is therefore not offered it
+  at all, and the child takes its own fallback, which is the same rule this
+  project already applies to `listChanged`.
+
+  `"passthrough": "off"` on a server withdraws its right to put words in front
+  of the user without switching it off; `MCP_ELICITATION=false` is the global
+  brake. Four further `MCP_ELICITATION_*` variables bound rounds, lifetime,
+  message size and payload size. See
+  [Elicitation](https://mcp-hub.ni-c.de/guide/elicitation).
+
+- **A question from a server that had gone to sleep was lost.** The hub decided
+  whether a child could be asked by reading the protocol era off its client,
+  and an on-demand child that is asleep has none — so the first tool call after
+  an idle nap silently took the weaker path and the second one worked. The wake
+  now happens before the decision.
+
+### Changed
+
+- **On MCP SDK 2.0.** The single `@modelcontextprotocol/sdk` package has been
+  replaced by the split `@modelcontextprotocol/{core,client,server,node,express}`.
+  Behaviour is unchanged by the migration itself: no wire format, endpoint or
+  response differs, and deployments need do nothing. Speaking `2026-07-28` as
+  well is a separate change, listed under Added above — it is what the
+  migration was for.
+
+  Notably **not** installed is `@modelcontextprotocol/server-legacy`, the frozen
+  copy of v1's authorization-server helpers that npm marks deprecated on
+  install. Replacing the hand-written OAuth server with `oidc-provider` first is
+  what made that possible — this migration only had to touch the MCP wire layer.
+
+  Two things the mechanical migration would have changed quietly, and did not:
+  `tools/list` is still walked one page at a time, because v2's `listTools()`
+  aggregates the whole pagination internally and would have bypassed the tool
+  count and metadata budgets that bound what a hostile child can make the hub
+  hold in memory; and a malformed line on a child's stdio is still reported,
+  because v2's read buffer skips unparseable lines in silence.
+
+- **The authorization server is now `oidc-provider` instead of ~900 lines of
+  hand-written OAuth.** Every endpoint keeps its path, the login and consent
+  pages are the same pages, and the discovery document advertises everything it
+  advertised before — there is a test that compares it field by field against
+  the old one and fails on anything that is not a written-down decision.
+
+  **This is a clean cut, not a migration: every client re-registers and
+  authorizes once more.** Tokens issued by the previous server are refused
+  rather than honoured, because a credential nothing can revoke is worse than a
+  reconnect. Registrations, approvals and API tokens in `state.json` are
+  untouched; only the OAuth artifacts are new.
+
+  Access tokens are **opaque** rather than JWTs. That is what makes
+  `mcp-hub-admin clients revoke` take effect on the next call instead of when
+  the token expires: oidc-provider never persists a JWT, so a JWT could not be
+  withdrawn at all. Nothing that presents a token has to change.
+
+  Several things got stricter on the way. Replaying a rotated refresh token now
+  revokes the grant's access tokens as well. Client assertions may not be valid
+  for longer than five minutes. Nothing an authorization server holds is written
+  to `state.json` in a form anyone could present — the file used to keep hashes
+  of refresh tokens, and now keeps hashes of everything. A `Host` header can no
+  longer influence the URLs in the discovery document.
+
+  Visible differences, none of which change what is allowed: redirects use
+  `303` where they used `302`, `invalid_client` may be answered `401` rather
+  than `400` (RFC 6749 §5.2 allows either), a rejected redirect URI is reported
+  as `invalid_redirect_uri`, and the login page lives at `/interaction/<id>/`
+  instead of being rendered by `/authorize` directly. The discovery document
+  gained the OpenID fields oidc-provider always publishes; no ID token is ever
+  issued.
+
+- **Four more reserved server names: `jwks`, `interaction`, `session` and
+  `userinfo`.** They are paths the authorization server answers on, and a server
+  configured under one of them would shadow the login flow rather than merely be
+  unreachable. A configuration using one of these names is now refused at
+  startup with the same message as for `token` or `authorize`.
+
+- **Both images now run on Node 24 ("Krypton"), the active LTS line, instead of
+  Node 26.** Node 26 is Current until October, and a non-LTS build leaves
+  `process.release.lts` unset — which is not cosmetic, because libraries branch
+  on it. It is also what the CI matrix already tests against, so the container
+  and the test runs no longer sat on different majors.
+
+  Nothing else changes: npm is still replaced wholesale and its three vulnerable
+  vendored packages still overwritten in place, verified against the built
+  image.
+
+### Security
+
+Five findings from an internal review of the authorization surface, which is the
+half that was rewritten onto oidc-provider in this cycle and had not been looked
+at adversarially since.
+
+- **`/token` bounds the body it reads.** It is the one provider path whose
+  request stream the hub takes away from the library — `stripPhantomSecret` has
+  to read it to strip a presented secret — and it read it without a ceiling.
+  `/token` cannot ask who is calling before it reads, because the credentials
+  are in the body, so an anonymous 300 MB request took the process from 157 MB
+  resident to 1.4 GB, and the per-path budget still allows fifty of them per
+  caller per window. The ceiling is oidc-provider's own 56 KiB, so nothing a
+  legitimate client sends changes, and an oversized body now gets the same
+  answer the library would have given it.
+
+- **A public client's record no longer carries a secret.** RFC 7591 makes
+  `client_secret_basic` the default when `token_endpoint_auth_method` is
+  omitted — which is what Claude and ChatGPT both do — so the authorization
+  server minted and persisted a real secret before `clientDefaults` rewrote the
+  method to `none`. Two consequences, neither visible from outside:
+  `state.json` gained a value someone could present, which is the one thing it
+  is careful never to hold; and `stripPhantomSecret` gates on the stored client
+  having no secret, so it stopped firing for exactly the clients it exists for.
+  A connector that echoed the secret from its registration response got
+  `401 invalid_client` — the failure quirk 2 was written to prevent. The
+  response still carries a secret, because ChatGPT insists on one; only the
+  record is cleaned.
+
+- **A hundred wrong passwords no longer lock the operator out.** The global
+  failure ceiling refused every address once it was reached, so an attacker
+  could close the only administrative way in — from one host, in under a second,
+  renewable every fifteen minutes — and the operator holding the correct
+  password got `429` from an address that had never touched the form. The
+  ceiling now refuses the callers that are guessing, and refuses them on their
+  first failure rather than their tenth once the hub is under a distributed
+  attempt, so the total number of guesses still collapses. What it no longer
+  does is let them spend somebody else's budget.
+
+- **Every per-caller budget counts an IPv6 /64, not an address.** A /64 is the
+  smallest block one subscriber is handed, and a /56 or /48 is what a
+  residential line usually gets, so a limiter keyed on the full address counted
+  one host as billions of callers: twenty-five registrations from twenty-five
+  addresses in one network spent twenty-five budgets of twenty. IPv4 keeps its
+  own address, and an IPv4-mapped form is folded back onto it so the same caller
+  is not counted twice for arriving over a dual-stack listener. Log lines are
+  unchanged — fail2ban still gets the host that actually connected.
+
+- **A `TRUSTED_PROXIES` list that never matches is now said out loud.** It is
+  compared against the address the connection came from, and the easiest way to
+  get it wrong is the least visible: a proxy configured as
+  `proxy_pass http://localhost:…` on a dual-stack host arrives over `::1`,
+  which `127.0.0.1` does not cover. Every forwarded header is then ignored and
+  per-caller limiting collapses into one global counter — the exact failure the
+  startup warning covers for an *unset* list, with nothing said when the list is
+  merely wrong. The hub now says so once, when a forwarded header arrives from
+  an address it does not trust.
+
+Unchanged, and confirmed by the same review: the docker policy proxy refused
+every one of thirty-three attempts to reach the daemon past it — privileged
+containers, host mounts, `Mounts` instead of `Binds`, foreign images, prototype
+pollution in the create body, duplicate query parameters, encoded traversal in a
+container name, `exec`, `build`, `networks/create`; and the metadata-document
+fetcher refused literal private addresses, IPv4-mapped ones and public names
+that resolve inward.
+
 ## [0.10.0] - 2026-08-27
 
 ### Added

package/README.md

@@ -7,10 +7,20 @@
 [![license](https://img.shields.io/npm/l/%40ni-c%2Fmcp-hub)](LICENSE)
 [![container](https://img.shields.io/badge/ghcr.io-ni--c%2Fmcp--hub-blue)](https://github.com/ni-c/mcp-hub/pkgs/container/mcp-hub)
 [![docs](https://img.shields.io/badge/docs-mcp--hub.ni--c.de-informational)](https://mcp-hub.ni-c.de)
+[![Glama](https://glama.ai/mcp/servers/ni-c/mcp-hub/badges/score.svg)](https://glama.ai/mcp/servers/ni-c/mcp-hub)
 [![sponsor](https://img.shields.io/badge/sponsor-ni--c-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/ni-c)
 
-A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) gateway: it serves
-many stdio MCP servers from **one container**, published over HTTPS.
+A dual-era [Model Context Protocol](https://modelcontextprotocol.io) (MCP) gateway: it
+serves many stdio MCP servers from **one container**, published over HTTPS, and speaks
+**both MCP revisions on every endpoint** — `2026-07-28` and `2025-11-25`. The client
+picks, and cannot tell which one it is on from the answers. On the 2026 revision that
+includes **elicitation** — a child server's question reaches the person at the far end
+instead of dying at the gateway
+([how](https://mcp-hub.ni-c.de/guide/elicitation)) — and **subscriptions**: the hub
+serves `subscriptions/listen` to its clients and subscribes to its children on
+whichever revision _they_ speak, so a server that has never heard of it still reaches
+a client that speaks nothing else
+([how](https://mcp-hub.ni-c.de/guide/subscriptions)).
 
 Lets MCP clients that cannot spawn a local process — ChatGPT connectors, Claude on
 the Web and in Code, Mistral Le Chat, Cursor, LibreChat and any other
@@ -83,11 +93,63 @@ replaces N containers with one process:
   servers.
 - **Stateless Streamable HTTP**: no session state, so claude.ai's
   reconnect-without-DELETE behaviour cannot leak processes or memory.
+- **Dual-era**: every endpoint — `/hub`, `/<name>/mcp` and `--stdio` — answers
+  MCP `2026-07-28` and `2025-11-25` alike; the client picks and cannot tell
+  from the answers which it got. On the 2026 revision that includes
+  **elicitation**: a server asking the user something returns the question
+  rather than pushing it, so it reaches the person at the far end instead of
+  dying at the gateway. The hub attributes it to the server that asked, strips
+  what could lie about that, drops embedded sampling and roots requests, and
+  seals the resumption state against the call it belongs to. `passthrough:
+"off"` withdraws one server's right to ask;
+  [details](https://mcp-hub.ni-c.de/guide/elicitation).
+- **Change notifications, in both eras**: a client opens a
+  `subscriptions/listen` stream and hears when a child's tools, prompts or
+  resources change. The hub subscribes to each child the way that child
+  understands — `subscriptions/listen` to a 2026 server, `resources/subscribe`
+  to a 2025 one — so the era gap is the gateway's problem rather than either
+  end's. The state is the open response, not a session table, so this costs the
+  stateless design nothing. A sleeping server watches nothing and is told to
+  re-read on waking; `subscriptions: "off"` withdraws one server's right to
+  push; [details](https://mcp-hub.ni-c.de/guide/subscriptions).
 - **Lightweight by design**: one Node process, no database (state is one JSON
-  file plus a JWT key under `/data`), a handful of runtime dependencies, and
+  file plus a signing key under `/data`), six runtime dependencies, and
   multi-arch images — a stated project goal is to run comfortably on a
   single-board computer like a Raspberry Pi.
 
+## Servers to run behind it
+
+The hub is server-agnostic — it serves any stdio MCP server whose entry fits
+Claude Code's `mcpServers` format, which is most of them. These eighteen are
+built and maintained alongside it, so their documentation carries the hub entry
+you need and their tool filters line up with the hub's own `allowTools` /
+`denyTools`:
+
+| Server                                                                 | npm                               | What it reaches                                                                |
+| ---------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------ |
+| [audiobookshelf-mcp](https://audiobookshelf-mcp.ni-c.de)               | `audiobookshelf-mcp`              | Audiobookshelf — libraries, listening progress, collections and playlists      |
+| [caldav-mcp](https://caldav-mcp.ni-c.de)                               | `@ni-c/caldav-mcp`                | CalDAV — events, tasks and journal entries on any server that speaks it        |
+| [calibreweb-mcp](https://calibreweb-mcp.ni-c.de)                       | `calibreweb-mcp`                  | Calibre-Web — read-only library access through the OPDS feed                   |
+| [freshrss-mcp](https://freshrss-mcp.ni-c.de)                           | `@ni-c/freshrss-mcp`              | FreshRSS — feeds, categories and articles as plain text, not stream ids        |
+| [google-search-console-mcp](https://google-search-console-mcp.ni-c.de) | `@ni-c/google-search-console-mcp` | Google Search Console — properties, sitemaps, search analytics, URL inspection |
+| [healthchecks-mcp](https://healthchecks-mcp.ni-c.de)                   | `healthchecks-mcp`                | Healthchecks — cron and uptime checks, and why one failed                      |
+| [hetzner-dns-mcp](https://hetzner-dns-mcp.ni-c.de)                     | `hetzner-dns-mcp`                 | Hetzner Cloud DNS — zones, record sets and BIND import/export                  |
+| [imap-mcp](https://imap-mcp.ni-c.de)                                   | `@ni-c/imap-mcp`                  | IMAP mailboxes — read, search, organise and draft mail; it cannot send         |
+| [linkwarden-mcp](https://linkwarden-mcp.ni-c.de)                       | `linkwarden-mcp`                  | Linkwarden — bookmarks, collections and the article text it preserved          |
+| [mealie-mcp](https://mealie-mcp.ni-c.de)                               | `@ni-c/mealie-mcp`                | Mealie — recipes, meal plans, shopping lists and cookbooks                     |
+| [ntfy-mcp](https://ntfy-mcp.ni-c.de)                                   | `@ni-c/ntfy-mcp`                  | ntfy — publish and update notifications, manage users and topic access         |
+| [opengist-mcp](https://opengist-mcp.ni-c.de)                           | `opengist-mcp`                    | Opengist — gists, revisions, commit history and raw files                      |
+| [osm-mcp](https://osm-mcp.ni-c.de)                                     | `osm-mcp`                         | OpenStreetMap — geocoding, routing, isochrones and POI search                  |
+| [rustpad-mcp](https://rustpad-mcp.ni-c.de)                             | `rustpad-mcp`                     | Rustpad — collaborative pads edited through real OT, not overwrites            |
+| [smtp-mcp](https://smtp-mcp.ni-c.de)                                   | `@ni-c/smtp-mcp`                  | SMTP — sends mail, behind a recipient allowlist and a human confirmation       |
+| [wg-easy-mcp](https://wg-easy-mcp.ni-c.de)                             | `wg-easy-mcp`                     | wg-easy v15+ — the full WireGuard client lifecycle                             |
+| [wikijs-mcp](https://wikijs-mcp.ni-c.de)                               | `@ni-c/wikijs-mcp`                | Wiki.js — search, read and edit pages, plus assets, users and groups           |
+| [woodpecker-ci-mcp](https://woodpecker-ci-mcp.ni-c.de)                 | `@ni-c/woodpecker-ci-mcp`         | Woodpecker CI — repositories, pipelines, logs, secrets and crons               |
+
+Each one runs perfectly well on its own over stdio. Put them behind the hub when
+you want them reachable from a client that cannot spawn a local process, or when
+you would rather register one connector than eighteen.
+
 ## Configuration
 
 `/config/mcp.json` — identical to Claude Code (`${VAR}` expands from the
@@ -366,15 +428,20 @@ immediately. Per-client recipes:
 
 ## Notes & limitations
 
-- Stateless transport: server-initiated notifications (`listChanged`,
-  subscriptions, sampling) are not delivered to clients. Tool/resource/prompt
-  request-response works fully; the hub's tool cache does follow
-  `tools/list_changed` internally.
-- Access tokens are self-contained 15-minute JWTs. Revoking a client rejects
-  its existing JWTs and removes all of its refresh tokens. Refresh tokens
-  rotate; replaying a token
-  that was already rotated away revokes its whole chain, and a refresh cannot
-  ask for more scope than the original grant.
+- Change notifications (`listChanged`, resource updates) are carried on
+  `2026-07-28` via `subscriptions/listen`, whose state is the open response
+  rather than a session table. A `2025-11-25` client is offered neither, because
+  that revision needs a channel the stateless transport does not keep — so the
+  capability is withheld instead of announced and dropped. An on-demand server
+  watches nothing while it sleeps; the subscription is re-established on the
+  next wake and the client is told to re-read.
+- Elicitation travels end to end on `2026-07-28`: it is a result rather than a
+  push. Sampling and log messages are not forwarded.
+- Access tokens are opaque and last 15 minutes. Revoking a client takes effect
+  on its next request rather than when the token expires — the token is a
+  reference to a stored record, so withdrawing it is a deletion. Refresh tokens
+  rotate; replaying one that was already rotated away is treated as a leak and
+  revokes the whole grant, access tokens included.
 - Upstream auth is fully decoupled from the hub's own OAuth: an expired
   upstream token just marks that one server `down` (503 on its path, visible
   in `/health`) — clients never see the upstream's 401.

package/dist/admin.js

@@ -4,7 +4,7 @@ import { AuthStore, clientLimitsFromEnv } from './auth/store.js';
 import { isSafeRedirectUri } from './auth/redirect-uri.js';
 import { clampDisplayName } from './auth/text.js';
 import { isClientIdMetadataUrl } from './auth/cimd.js';
-import { mintApiToken } from './auth/provider.js';
+import { mintApiToken } from './auth/api-tokens.js';
 import { loadConfig } from './config.js';
 import { authFor, requireOAuthServer, startUpstreamLogin, upstreamStatus } from './upstream/login.js';
 function usage() {

package/dist/auth/api-tokens.js

@@ -0,0 +1,27 @@
+import crypto from 'node:crypto';
+import { SignJWT } from 'jose';
+/** Distinguishes admin-minted API tokens from interactive OAuth tokens. */
+export const API_TOKEN_SUBJECT = 'mcp-hub-token';
+/**
+ * Mint a long-lived, resource-bound API token for clients that cannot do
+ * OAuth (OpenAI Responses API, xAI API, Gemini API, plain-header clients).
+ * The JWT is returned exactly once; only its record (jti) is persisted, which
+ * is what `tokens list` shows and `tokens revoke` deletes.
+ */
+export async function mintApiToken(store, externalUrl, resource, days, label) {
+    const id = crypto.randomBytes(8).toString('base64url');
+    const now = Math.floor(Date.now() / 1000);
+    const expiresAt = now + days * 86_400;
+    const token = await new SignJWT({})
+        .setProtectedHeader({ alg: 'EdDSA' })
+        .setIssuer(new URL(externalUrl).href)
+        .setAudience(resource.href)
+        .setSubject(API_TOKEN_SUBJECT)
+        .setIssuedAt(now)
+        .setExpirationTime(expiresAt)
+        .setJti(id)
+        .sign(store.privateKey);
+    store.saveApiToken(id, { label, resource: resource.href, createdAt: now, expiresAt });
+    return { id, token, expiresAt };
+}
+//# sourceMappingURL=api-tokens.js.map

package/dist/auth/headers.js

@@ -7,7 +7,7 @@
  * sits there with no visible error, so the pages have to name the one origin
  * their flow legitimately ends on.
  */
-export function contentSecurityPolicy(formActionOrigins = []) {
+function contentSecurityPolicy(formActionOrigins = []) {
     const formAction = ["'self'", ...formActionOrigins].join(' ');
     return `default-src 'none'; style-src 'unsafe-inline'; form-action ${formAction}; frame-ancestors 'none'; base-uri 'none'`;
 }
@@ -30,4 +30,25 @@ export function allowFormActionTo(res, redirectUri) {
         return;
     res.set('Content-Security-Policy', contentSecurityPolicy([origin]));
 }
+/**
+ * The headers every page and token response of the auth surface carries.
+ *
+ * Shared rather than repeated: the mounted authorization server is a Koa app
+ * the Express router never enters, so these have to be put in front of it
+ * explicitly -- and two copies of the list would drift the moment one of them
+ * gained a header.
+ *
+ * RFC 6749 §5.1 requires `no-store` on token responses; the login form has no
+ * business being cached either. The CSP and the legacy frame header keep an
+ * attacker from clickjacking approval or password entry. This application has
+ * no legitimate framing use case.
+ */
+export const authSecurityHeaders = (_req, res, next) => {
+    res.set('Cache-Control', 'no-store');
+    res.set('Content-Security-Policy', contentSecurityPolicy());
+    res.set('X-Frame-Options', 'DENY');
+    res.set('X-Content-Type-Options', 'nosniff');
+    res.set('Referrer-Policy', 'no-referrer');
+    next();
+};
 //# sourceMappingURL=headers.js.map