mcp_toolkit 0.3.0 → 0.5.0

data/lib/mcp_toolkit/engine.rb

@@ -1,21 +1,39 @@
 # frozen_string_literal: true
 
-# Mountable Rails engine that draws the four MCP transport routes (defined in the
-# engine's config/routes.rb so they survive Rails' route reloads) against the
-# gem-provided McpToolkit::ServerController. A satellite mounts it in one line:
+# Mountable Rails engine that draws the MCP transport routes plus the authority
+# introspection route (defined in the engine's config/routes.rb so they survive
+# Rails' route reloads) against the gem-provided McpToolkit::ServerController /
+# McpToolkit::TokensController. A satellite OR an authority mounts it in one line:
 #
 #   # config/routes.rb
 #   mount McpToolkit::Engine => "/mcp"
 #
-# yielding exactly the endpoints a hand-rolled satellite declared:
+# The mounted McpToolkit::ServerController is role-aware (built lazily from
+# config.auth_role): an authority host gets the hand-rolled dispatcher path, a
+# satellite gets the SDK-backed one — see engine_controllers.rb. This yields
+# exactly the endpoints a hand-rolled host declared:
 #
-#   POST   /mcp          -> create   (JSON-RPC requests/responses)
-#   GET    /mcp          -> stream   (405; no server-initiated SSE)
-#   DELETE /mcp          -> destroy  (terminate the session)
-#   GET    /mcp/health   -> health   (unauthenticated probe)
+#   POST   /mcp                     -> create     (JSON-RPC requests/responses)
+#   GET    /mcp                     -> stream     (405; no server-initiated SSE)
+#   DELETE /mcp                     -> destroy    (terminate the session)
+#   GET    /mcp/health              -> health     (unauthenticated probe)
+#   POST   /mcp/tokens/introspect   -> introspect (authority token introspection;
+#                                                  drawn ONLY when auth_role is
+#                                                  :authority — a satellite that
+#                                                  mounts the engine gets no such
+#                                                  route)
 #
 # Loaded ONLY when Rails::Engine is available (see lib/mcp_toolkit.rb); the gem's
 # non-Rails consumers and its own unit suite never reference it.
 class McpToolkit::Engine < Rails::Engine
   isolate_namespace McpToolkit
+
+  # The gem-provided controllers subclass `config.parent_controller`, which the
+  # host sets in an initializer/to_prepare that must be READ AFTER it runs
+  # (Constraint B). They are therefore built lazily by
+  # `McpToolkit.build_engine_controllers!` (triggered via const_missing on first
+  # reference — at eager-load or first request). This resets them on every code
+  # reload so a changed parent (or a reloaded app parent class) takes effect on the
+  # next reference. Runs before `:eager_load!`, so the fresh classes exist for it.
+  config.to_prepare { McpToolkit.reset_engine_controllers! }
 end

data/lib/mcp_toolkit/engine_controllers.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+# Lazy `parent_controller` builder (Constraint B).
+#
+# The engine's controllers (McpToolkit::ServerController,
+# McpToolkit::TokensController) and the authority base
+# (McpToolkit::Authority::ServerController) all subclass
+# `config.parent_controller`. If that superclass were resolved in a class body of
+# an autoloaded/eager-loaded file, it could be read BEFORE the host's
+# initializer/to_prepare had set it — defaulting to ActionController::Base and, in
+# turn, breaking CSRF handling on the introspection endpoint.
+#
+# Instead, none of these controllers is a Zeitwerk-managed file. They are built
+# here from the CURRENT config, and the build is triggered LAZILY:
+#   * `const_missing` (below, and on McpToolkit::Authority) builds them the first
+#     time they are referenced — which, in a host, is at eager-load or first-
+#     request time, i.e. AFTER the app's initializers/to_prepare have run;
+#   * the engine's `config.to_prepare` RESETS them on every code reload so a
+#     changed `parent_controller` (or a reloaded app parent class) takes effect on
+#     the next reference.
+#
+# The whole `config/initializers/mcp_toolkit.rb` of a host can therefore live in
+# `to_prepare`: the parent is only ever read at build time.
+#
+# This file reopens `McpToolkit` to add module methods, so it is Zeitwerk-IGNORED
+# (like engine.rb) and required explicitly from the gem entry point.
+module McpToolkit
+  # The controllers built directly under McpToolkit (the engine's routes point at
+  # these). McpToolkit::Authority::ServerController is built alongside them but is
+  # fetched through McpToolkit::Authority's own const_missing.
+  ENGINE_CONTROLLER_NAMES = %i[ServerController TokensController].freeze
+
+  # (Re)builds the engine controllers + the authority base from the current
+  # config. Idempotent: an existing constant is replaced so a rebuild reflects a
+  # changed `parent_controller`. Reads `config.parent_controller` at call time.
+  def self.build_engine_controllers!
+    parent = config.parent_controller.constantize
+    define_controller(self, :ServerController, build_server_controller(parent))
+    define_controller(self, :TokensController, build_tokens_controller(parent))
+    define_controller(Authority, :ServerController, build_authority_server_controller(parent))
+    ServerController
+  end
+
+  # Undefines the built controllers so the next reference rebuilds them from the
+  # then-current config. Called from the engine's `to_prepare` on every reload.
+  def self.reset_engine_controllers!
+    [[self, :ServerController], [self, :TokensController], [Authority, :ServerController]].each do |mod, name|
+      mod.send(:remove_const, name) if mod.const_defined?(name, false)
+    end
+  end
+
+  # The transport controller the engine mounts at POST/GET/DELETE /mcp, chosen by
+  # ROLE so a single `mount McpToolkit::Engine => "/mcp"` works for either kind of
+  # host: an AUTHORITY (`auth_role == :authority`) gets the hand-rolled dispatcher
+  # path (Authority::ControllerMethods — local token auth, gateway proxying, usage
+  # metering, rate limiting), a SATELLITE (the default) gets the SDK-backed path
+  # (Transport::ControllerMethods, which forwards tokens to a central app). Built
+  # lazily so both `config.parent_controller` and `config.auth_role` are read after
+  # the host's initializer/to_prepare has run. A host that would rather draw its own
+  # routes still subclasses McpToolkit::Authority::ServerController directly.
+  def self.build_server_controller(parent)
+    concern = config.authority? ? McpToolkit::Authority::ControllerMethods : McpToolkit::Transport::ControllerMethods
+    Class.new(parent) { include concern }
+  end
+
+  # The AUTHORITY introspection endpoint the engine mounts at
+  # `POST /mcp/tokens/introspect`. Behavior is preserved exactly: it authenticates
+  # the bearer against `config.token_authenticator` (via Auth::Authority) and
+  # renders the introspection payload; a non-authority app answers `{ valid:
+  # false }` rather than erroring.
+  def self.build_tokens_controller(parent)
+    Class.new(parent) do
+      def introspect
+        token = McpToolkit::Auth::Authority.authenticate(mcp_extract_token, config: mcp_config)
+        return render(json: McpToolkit::Auth::Authority.invalid_payload, status: :unauthorized) if token.nil?
+
+        render json: McpToolkit::Auth::Authority.introspection_payload(token)
+      rescue McpToolkit::Errors::ConfigurationError
+        # Not configured as an authority (no token_authenticator): behave as if the
+        # token were invalid instead of surfacing a 500.
+        render json: McpToolkit::Auth::Authority.invalid_payload, status: :unauthorized
+      end
+
+      private
+
+      def mcp_config
+        McpToolkit.config
+      end
+
+      def mcp_extract_token
+        auth_header = request.headers["Authorization"]
+        return auth_header.sub("Bearer ", "") if auth_header&.start_with?("Bearer ")
+
+        request.headers["X-MCP-Token"].presence || params[:token].presence
+      end
+    end
+  end
+
+  # The AUTHORITY base controller a host subclasses (the recommended path for a
+  # host whose rate-limit/usage/account hooks touch app models).
+  def self.build_authority_server_controller(parent)
+    Class.new(parent) { include McpToolkit::Authority::ControllerMethods }
+  end
+
+  # Removes an existing same-named constant (avoiding a redefinition warning on a
+  # rebuild) before setting the freshly-built class.
+  def self.define_controller(mod, name, klass)
+    mod.send(:remove_const, name) if mod.const_defined?(name, false)
+    mod.const_set(name, klass)
+  end
+
+  # Backstop: build the engine controllers the first time one is referenced before
+  # any `to_prepare`/eager-load pass has built them (e.g. a bespoke route that
+  # names McpToolkit::ServerController directly). McpToolkit::Authority defines the
+  # sibling backstop for its ServerController.
+  def self.const_missing(name)
+    if ENGINE_CONTROLLER_NAMES.include?(name)
+      build_engine_controllers!
+      return const_get(name) if const_defined?(name, false)
+    end
+
+    super
+  end
+end

data/lib/mcp_toolkit/filtering.rb

@@ -4,15 +4,21 @@
 # the following semantics:
 #
 #   * a BARE value filters by equality:               filter: { booking_id: 42 }
-#     (a comma-separated string becomes an IN lookup:  filter: { status: "a,b" })
+#     - a comma-separated string becomes an IN lookup: filter: { status: "a,b" }
+#     - an Array of scalars becomes an IN lookup too:  filter: { status: ["a", "b"] }
+#     - the string "null" (or a JSON null) matches NULL rows: filter: { canceled_at: "null" }
+#       (as a SCALAR value only — inside an IN set, elements must be non-null
+#       scalars and "null" stays a literal string, because SQL `IN` cannot match
+#       NULL; a null-or-nothing condition is expressed as a scalar filter)
 #   * an { op:, value: } HASH filters with an operator: filter: { price: { op: "gteq", value: 100 } }
 #   * an ARRAY of those hashes ANDs them (ranges):
 #       filter: { price: [{ op: "gteq", value: 100 }, { op: "lt", value: 200 }] }
 #
 # Supported operators (validated against the column's DB type):
-#   eq, not_eq, gt, gteq, lt, lteq        — numeric / datetime columns
+#   eq, not_eq, gt, gteq, lt, lteq        — numeric / datetime columns (+ in for date)
 #   eq, not_eq, in, matches, does_not_match — string columns (matches => case-insensitive LIKE)
 #   eq, not_eq                            — boolean columns
+#   eq, in                                — any other column type (uuid, enum, jsonb, ...)
 #
 # Allowlist-safe: only the resource's declared `filterable` keys may be filtered,
 # each resolved to its backing column. Unknown keys are rejected upstream by the
@@ -24,17 +30,29 @@ module McpToolkit::Filtering
     float: %w[eq not_eq gt gteq lt lteq].freeze,
     decimal: %w[eq not_eq gt gteq lt lteq].freeze,
     datetime: %w[eq not_eq gt gteq lt lteq].freeze,
-    date: %w[eq not_eq gt gteq lt lteq].freeze,
-    string: %w[eq not_eq in matches does_not_match].freeze,
-    text: %w[eq not_eq in matches does_not_match].freeze,
+    date: %w[eq not_eq gt gteq lt lteq in].freeze,
+    string: %w[eq in not_eq matches does_not_match].freeze,
+    text: %w[eq in not_eq matches does_not_match].freeze,
     boolean: %w[eq not_eq].freeze
   }.freeze
 
+  # Operators for a column type OUTSIDE the table above (uuid, enum, jsonb,
+  # citext, ...): plain equality/IN still work on any column, so they stay
+  # available rather than turning "cannot be filtered with operators" — which
+  # also matches the API contract this replaces for adopting hosts.
+  DEFAULT_OPERATORS = %w[eq in].freeze
+
   # Operators that map straight onto an Arel predication method.
   AREL_PREDICATIONS = %w[eq not_eq gt gteq lt lteq in matches does_not_match].freeze
 
   NULL_TOKEN = "null"
 
+  # Operators for which a null value is meaningful: eq/in render `IS NULL`,
+  # not_eq renders `IS NOT NULL`. Every other operator rejects null explicitly —
+  # a comparison or LIKE against NULL can never match a row in SQL, so passing
+  # one through silently would return a wrong (empty) result.
+  NULL_ACCEPTING_OPERATORS = %w[eq in not_eq].freeze
+
   # @param relation the already account-scoped relation
   # @param column [Symbol] the backing DB column (already resolved from the allowlist)
   # @param value the filter value: a bare value, an { op:, value: } hash, or an
@@ -46,14 +64,40 @@ module McpToolkit::Filtering
     if compound?(value)
       apply_condition(relation, column, value, config:)
     elsif collection?(value)
+      enforce_filter_limit!(value.length, config)
       value.inject(relation) { |rel, condition| apply_condition(rel, column, condition, config:) }
+    elsif mixed_collection?(value)
+      raise McpToolkit::Errors::InvalidParams,
+            "a filter array must contain either only { op:, value: } conditions or only bare values"
     else
-      # Bare value: equality. A comma-separated string becomes an IN lookup,
-      # matching the implicit `eq` semantics.
-      relation.where(column => equality_value(value))
+      # Bare value(s): equality. Under the default :tokenized semantics a
+      # comma-separated string or an Array of scalars becomes an IN lookup and
+      # "null" / a JSON null matches NULL rows; under :literal the value is
+      # handed to the WHERE clause verbatim (see
+      # Configuration#bare_filter_value_semantics).
+      relation.where(column => bare_value(value, config))
     end
   end
 
+  def self.bare_value(value, config)
+    if value.is_a?(Hash)
+      raise McpToolkit::Errors::InvalidParams,
+            "unsupported filter value; use a bare scalar, an array of scalars, " \
+            "or { op:, value: } condition(s)"
+    end
+
+    # An Array bare value renders as `WHERE column IN (...)` under EITHER
+    # semantics, so bound its size before the branch below. The :literal path
+    # returns the array verbatim and would otherwise skip the limit that
+    # equality_value/equality_value_set enforce only on the :tokenized path —
+    # defeating the query-complexity guard on the new host-compatibility path.
+    enforce_filter_limit!(value.length, config) if value.is_a?(Array)
+
+    return value if config.bare_filter_value_semantics == :literal
+
+    equality_value(value, config:)
+  end
+
   # A single operator-based condition, e.g. { op: "gt", value: 1000 }.
   def self.compound?(value)
     condition_hash?(value) && (value.key?(:op) || value.key?("op"))
@@ -64,6 +108,13 @@ module McpToolkit::Filtering
     value.is_a?(Array) && value.any? && value.all? { |element| compound?(element) }
   end
 
+  # An Array mixing operator conditions with bare values — rejected explicitly:
+  # neither the AND-of-conditions nor the IN-set reading fits, and treating it as
+  # either would silently match the wrong rows.
+  def self.mixed_collection?(value)
+    value.is_a?(Array) && value.any? { |element| compound?(element) }
+  end
+
   def self.condition_hash?(value)
     value.is_a?(Hash)
   end
@@ -73,7 +124,7 @@ module McpToolkit::Filtering
     raise McpToolkit::Errors::InvalidParams, "a filter operator is required" if operator.empty?
 
     type = column_type(relation, column)
-    validate_operator!(operator, type, column)
+    validate_operator!(operator, type, column, config:)
 
     raw = fetch(condition, :value)
     relation.where(predicate_for(relation, column, operator, raw, config:))
@@ -94,12 +145,24 @@ module McpToolkit::Filtering
     model.columns_hash[column.to_s]&.type
   end
 
-  def self.validate_operator!(operator, type, column)
-    allowed = OPERATORS_BY_TYPE[type]
-    if allowed.nil?
+  # Operators an attribute of the given column type accepts — the single source
+  # for both the schema's advertisement and the executor's enforcement, so the
+  # two can never disagree. `[]` for an attribute with no backing column (which
+  # cannot be filtered with operators). A host can override sets per type via
+  # config.filter_operator_overrides (e.g. to preserve a pre-gem contract).
+  def self.operators_for(type, config: McpToolkit.config)
+    return [] if type.nil?
+
+    config.filter_operator_overrides.fetch(type) { OPERATORS_BY_TYPE.fetch(type, DEFAULT_OPERATORS) }
+  end
+
+  def self.validate_operator!(operator, type, column, config:)
+    if type.nil?
       raise McpToolkit::Errors::InvalidParams,
             "'#{column}' cannot be filtered with operators"
     end
+
+    allowed = operators_for(type, config:)
     return if allowed.include?(operator)
 
     raise McpToolkit::Errors::InvalidParams,
@@ -113,25 +176,55 @@ module McpToolkit::Filtering
   # test fake) receives a portable Predicate value object it knows how to apply.
   def self.predicate_for(relation, column, operator, raw, config:)
     value = normalize_value(operator, raw, config:)
-    arel_operator = operator == "eq" ? "in" : operator
+    method = arel_operator(operator, value)
+
+    # Defense in depth: only a known-safe Arel predication may ever reach
+    # public_send. operators_for/validate_operator! already gate this and
+    # config.filter_operator_overrides is validated at assignment — but the
+    # value handed to any operator outside eq/in/matches is passed through
+    # VERBATIM (normalize_value's else branch), so an operator that slipped in
+    # (e.g. a host-configured "extract") must never be dispatched: Arel would
+    # interpolate the request value as raw SQL. This is the last guard before
+    # the metaprogramming call.
+    unless AREL_PREDICATIONS.include?(method)
+      raise McpToolkit::Errors::InvalidParams, "'#{operator}' is not a supported filter operator"
+    end
 
     model = relation.respond_to?(:model) ? relation.model : nil
     if model.respond_to?(:arel_table)
-      model.arel_table[column.to_sym].public_send(arel_operator, value)
+      model.arel_table[column.to_sym].public_send(method, value)
     else
-      Predicate.new(column.to_sym, arel_operator, value)
+      Predicate.new(column.to_sym, method, value)
     end
   end
 
-  # `eq` against a (possibly comma-separated) value becomes an IN set. `matches`
-  # / `does_not_match` wrap the value in `%...%` with LIKE wildcards escaped so
-  # they match literally. `null` => nil for every operator.
+  # `eq` fans out to an IN lookup (normalize_value turns its value into a set) —
+  # EXCEPT against NULL: Arel renders `in(nil)` as `IN (NULL)`, which matches no
+  # rows in SQL, so eq/in with a nil value stay/become `eq` (rendered `IS NULL`).
+  def self.arel_operator(operator, value)
+    return operator unless %w[eq in].include?(operator)
+
+    value.nil? ? "eq" : "in"
+  end
+
+  # `eq` / `in` against a (possibly comma-separated string or Array) value
+  # becomes an IN set. `matches` / `does_not_match` wrap the value in `%...%`
+  # with LIKE wildcards escaped so they match literally. `null` / a JSON null
+  # => nil for the NULL_ACCEPTING_OPERATORS, rejected for every other operator.
   def self.normalize_value(operator, raw, config:)
-    return nil if raw.to_s == NULL_TOKEN
+    if raw.nil? || raw.to_s == NULL_TOKEN
+      unless NULL_ACCEPTING_OPERATORS.include?(operator)
+        raise McpToolkit::Errors::InvalidParams,
+              "'#{operator}' does not accept a null value " \
+              "(only #{NULL_ACCEPTING_OPERATORS.join("/")} do)"
+      end
+      return nil
+    end
 
     case operator
     when "eq", "in"
-      raw.to_s.split(",")
+      resolved = equality_value(raw, config:)
+      resolved.is_a?(Array) ? resolved : [resolved]
     when "matches", "does_not_match"
       "%#{config.sql_sanitizer.sanitize_sql_like(raw.to_s)}%"
     else
@@ -139,11 +232,63 @@ module McpToolkit::Filtering
     end
   end
 
-  def self.equality_value(value)
-    return nil if value.to_s == NULL_TOKEN
+  # A bare (non-operator) filter value resolved for equality: `"null"` / nil =>
+  # nil (matches NULL rows); a comma-separated string => its parts (IN); an
+  # Array => an IN set of non-null scalars (see .equality_value_set). Any other
+  # non-scalar (an op-less Hash) is rejected — passed through it would reach the
+  # database as a malformed condition.
+  def self.equality_value(value, config: McpToolkit.config)
+    return equality_value_set(value, config:) if value.is_a?(Array)
+    return nil if value.nil? || value.to_s == NULL_TOKEN
+
+    if value.is_a?(Hash)
+      raise McpToolkit::Errors::InvalidParams,
+            "unsupported filter value; use a bare scalar, an array of scalars, " \
+            "or { op:, value: } condition(s)"
+    end
 
     str = value.to_s
-    str.include?(",") ? str.split(",") : value
+    return value unless str.include?(",")
+
+    parts = str.split(",")
+    enforce_filter_limit!(parts.length, config)
+    parts
+  end
+
+  # Resolves an Array filter value into a flat IN set. Elements must be non-null
+  # scalars (comma-separated strings are split in); nil / nested Array / Hash
+  # elements are rejected explicitly — SQL `IN` cannot match NULL (Arel renders
+  # a nil element as the never-matching `IN (..., NULL)`), and a non-scalar
+  # element is a malformed condition either way. The `"null"` token is NOT
+  # resolved inside a set for the same reason: it stays a literal string, and a
+  # null-or-nothing condition is expressed as a scalar filter value instead.
+  def self.equality_value_set(values, config: McpToolkit.config)
+    resolved = values.flat_map do |element|
+      if element.nil? || element.is_a?(Array) || element.is_a?(Hash)
+        raise McpToolkit::Errors::InvalidParams,
+              "an IN-set filter must contain only non-null scalar values; " \
+              "to match NULL rows pass \"null\" as the filter's single value"
+      end
+
+      str = element.to_s
+      str.include?(",") ? str.split(",") : [element]
+    end
+    enforce_filter_limit!(resolved.length, config)
+    resolved
+  end
+
+  # Bounds how many values an IN-set resolves to (and how many operator
+  # conditions may be ANDed on one attribute, enforced by .apply), so a valid
+  # token can't emit an unbounded IN clause / AND-chain — oversized SQL + Arel
+  # AST and expensive query planning, which matters because rate limiting is
+  # opt-in (config.rate_limit_max_requests). Disabled when
+  # config.max_filter_values is nil.
+  def self.enforce_filter_limit!(count, config)
+    max = config.max_filter_values
+    return if max.nil? || count <= max
+
+    raise McpToolkit::Errors::InvalidParams,
+          "a filter may carry at most #{max} values or conditions (got #{count})"
   end
 
   # Portable representation of an operator predicate, applied by the in-memory

data/lib/mcp_toolkit/gateway/aggregator.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+# Aggregates the tool lists of all configured upstream MCP servers for a
+# gateway's `tools/list`, namespacing each tool as `<app>__<tool>`.
+#
+# Per upstream the namespaced list is cached in `config.cache_store`
+# (`config.upstream_list_ttl`, default 15 min) and bustable via `flush!` /
+# `flush!(key)`. On a cache miss the live pull runs per-upstream (one HTTP call
+# each); a failing/timeout upstream is omitted + logged, never breaking the list.
+#
+# Why the cache is safe to share globally: an upstream's `tools/list` is
+# token-INDEPENDENT — it returns the same public tool definitions to every valid
+# caller and enforces scope only when a tool is CALLED (per-call authorization is
+# the upstream's job). So one caller's pull is a correct answer for all callers.
+# This is a registration CONTRACT, not an assumption: an upstream that filters its
+# list by the caller's privilege (e.g. hides superuser-only tools) MUST register
+# `public_tool_list: false`, which opts it out of this cache (pulled live per
+# request) so a privileged caller's list can never be served to an unprivileged
+# one. See McpToolkit::Gateway::UpstreamRegistry::Upstream.
+#
+# Only a NON-EMPTY pull is ever cached. An empty or failed pull is almost always a
+# transient upstream hiccup (timeout, a session/handshake blip, a degenerate 200);
+# caching it would freeze a whole app's tools out of `tools/list` for the full TTL
+# for EVERY caller (a poisoned global cache), which is exactly the failure this
+# guards against. A stale empty already in the cache is treated as a miss and
+# re-pulled, so the aggregate self-heals as soon as the upstream returns tools.
+#
+# Concurrency: upstreams are pulled CONCURRENTLY via concurrent-ruby futures. When
+# running inside Rails, each future is wrapped in `Rails.application.executor` so
+# it participates in the framework's per-request lifecycle (reloading, query
+# cache, connection checkout); a non-Rails host runs plain futures. Output order
+# follows the registry order.
+class McpToolkit::Gateway::Aggregator
+  CACHE_KEY_PREFIX = "mcp_toolkit:gateway:tools:"
+
+  def initialize(config: McpToolkit.config)
+    @config = config
+  end
+
+  # Namespaced tool definitions across all configured upstreams. `bearer_token`
+  # is used only on a cache miss, so the upstream can authenticate the list
+  # request the same way it would a call. Upstreams are fetched concurrently;
+  # output order follows the registry order.
+  def tool_definitions(bearer_token: nil)
+    futures = config.upstreams.all.map do |upstream|
+      Concurrent::Promises.future do
+        within_executor { cached_or_live_definitions(upstream, bearer_token:) }
+      end
+    end
+
+    futures.flat_map(&:value!)
+  end
+
+  def flush!(key = nil)
+    if key
+      cache.delete(cache_key(key))
+    else
+      config.upstreams.all.each { |upstream| cache.delete(cache_key(upstream.key)) }
+    end
+  end
+
+  private
+
+  attr_reader :config
+
+  # Runs the block inside the Rails executor when a BOOTED Rails app is present
+  # (so a future participates in the request lifecycle: reloading, query cache,
+  # connection checkout), or plainly otherwise. Guards for `Rails` being defined
+  # but not booted (e.g. `rails/version` required without an initialized app), in
+  # which case `Rails.application` is nil and we run the block directly.
+  def within_executor(&)
+    if defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+      Rails.application.executor.wrap(&)
+    else
+      yield
+    end
+  end
+
+  def cached_or_live_definitions(upstream, bearer_token:)
+    # A caller-dependent upstream opts out of the shared cache (keyed by upstream
+    # only): caching it would leak one caller's list to callers of other privilege.
+    return live_definitions(upstream, bearer_token:) unless upstream.public_tool_list
+
+    cached = cache.read(cache_key(upstream.key))
+    # `present?` treats both a nil miss AND a stale empty list as "no cache", so a
+    # previously poisoned empty entry is re-pulled instead of served.
+    return cached if cached.present?
+
+    definitions = live_definitions(upstream, bearer_token:)
+    # Only persist a real, non-empty list; never cache an empty/degraded pull.
+    cache.write(cache_key(upstream.key), definitions, expires_in: config.upstream_list_ttl) if definitions.present?
+    definitions
+  rescue McpToolkit::Gateway::Client::Error => e
+    # Degrade gracefully: omit this upstream's tools, don't cache the failure.
+    config.logger&.error("MCP upstream #{upstream.key} tools/list failed, omitting: #{e.message}")
+    []
+  rescue StandardError => e
+    # Backstop: any OTHER error while processing ONE upstream (e.g. a malformed
+    # tool definition) must degrade just that upstream, never 500 the whole
+    # aggregated tools/list and take every sibling upstream down with it.
+    config.logger&.error("MCP upstream #{upstream.key} tools/list errored, omitting: #{e.class}: #{e.message}")
+    []
+  end
+
+  def live_definitions(upstream, bearer_token:)
+    client = McpToolkit::Gateway::Client.new(upstream:, bearer_token:, config:)
+    client.tools_list.filter_map do |definition|
+      namespaced(upstream, definition)
+    end
+  end
+
+  # Re-keys an upstream tool definition into the gateway's aggregate namespace,
+  # rewriting backticked generic-tool references in its prose too — a proxied
+  # `list` saying "use the `resources` tool" must point at `<app>__resources`,
+  # the only name that exists on THIS server's tools/list. The rewrite returns a
+  # fresh structure, so the upstream's (possibly cached) definition is never
+  # mutated.
+  def namespaced(upstream, definition)
+    # A hostile/broken upstream can return a non-Hash entry (or a Hash with no
+    # "name"); skip it (logging the shape, never its content) so one bad entry
+    # degrades to omission instead of raising through the whole aggregate.
+    unless definition.is_a?(Hash) && definition["name"]
+      config.logger&.warn("MCP upstream #{upstream.key}: skipping a malformed tool entry (#{definition.class})")
+      return nil
+    end
+
+    rewritten = McpToolkit::ToolReferenceRewriter.rewrite(definition, upstream.name_for(""))
+    rewritten = rewritten.dup if rewritten.equal?(definition)
+    rewritten["name"] = upstream.name_for(definition["name"])
+    rewritten
+  end
+
+  def cache
+    config.cache_store
+  end
+
+  def cache_key(key)
+    "#{CACHE_KEY_PREFIX}#{key}"
+  end
+end