mcp_toolkit 0.4.0 → 0.5.0

data/lib/mcp_toolkit/configuration.rb

@@ -169,6 +169,94 @@ class McpToolkit::Configuration
   # @return [#sanitize_sql_like]
   attr_accessor :sql_sanitizer
 
+  # NOTE: (all data-path settings below): the list/get executors and the schema
+  # builder read the PROCESS-GLOBAL `McpToolkit.config` — a per-instance config
+  # bound to a provider affects tool prose only. Configure these globally.
+  #
+  # How a BARE (non-operator) filter value is interpreted by the list executor:
+  #
+  #   :tokenized (default) — a comma-separated string becomes an IN set, the
+  #     "null" token (and a JSON null) matches NULL rows, an Array of non-null
+  #     scalars is an IN set (nil/Hash/nested-Array elements rejected), and an
+  #     empty string means "no filter".
+  #   :literal — the value is handed to the WHERE clause verbatim (an op-less
+  #     Hash is still rejected). This preserves an EXISTING API contract for a
+  #     host whose pre-gem endpoint matched bare values literally: "a,b" is one
+  #     literal string, "null" is the literal string, "" matches empty-string
+  #     rows, an Array (including nil elements) gets the adapter's native IN /
+  #     OR-IS-NULL handling.
+  #
+  # Operator conditions ({ op:, value: }) behave identically in both modes.
+  #
+  # @return [Symbol] :tokenized or :literal
+  attr_accessor :bare_filter_value_semantics
+
+  # Default ordering for a resource whose primary key is NON-numeric (numeric
+  # PKs always order by :id):
+  #
+  #   :created_at (default) — ORDER BY created_at, <pk> (chronological pages
+  #     with a total-order tiebreaker).
+  #   :primary_key — ORDER BY <pk> only. Preserves an EXISTING API contract for
+  #     a host whose pre-gem endpoint ordered every list by id.
+  #
+  # @return [Symbol] :created_at or :primary_key
+  attr_accessor :non_numeric_pk_order
+
+  # Per-column-type overrides for the operator sets advertised by
+  # `resource_schema` and enforced by the list executor, merged over
+  # McpToolkit::Filtering::OPERATORS_BY_TYPE. Lets a host preserve an EXISTING
+  # operator contract exactly — both the schema bytes and which conditions are
+  # accepted — e.g. `{ text: %w[eq in], date: %w[eq in] }` for a pre-gem
+  # endpoint that never offered comparisons on those types. Empty by default
+  # (the gem's own sets apply).
+  #
+  # @return [Hash{Symbol => Array<String>}]
+  attr_reader :filter_operator_overrides
+
+  # Assigns per-type operator overrides, rejecting any operator the gem cannot
+  # safely dispatch. Only McpToolkit::Filtering::AREL_PREDICATIONS map onto an
+  # Arel predication that binds/quotes its value; anything else (e.g. "extract")
+  # would be public_send to an Arel attribute with the request value passed
+  # through VERBATIM — an SQL-injection surface. Fail fast at config time so a
+  # typo can never open that door at request time.
+  def filter_operator_overrides=(overrides)
+    overrides ||= {}
+    unless overrides.is_a?(Hash)
+      raise ArgumentError,
+            "filter_operator_overrides must be a Hash of { column_type => [operator, ...] }, " \
+            "got #{overrides.class}"
+    end
+
+    overrides.each do |type, operators|
+      unsupported = Array(operators).map(&:to_s) - McpToolkit::Filtering::AREL_PREDICATIONS
+      next if unsupported.empty?
+
+      raise ArgumentError,
+            "filter_operator_overrides[#{type.inspect}] has unsupported operator(s): " \
+            "#{unsupported.join(", ")}. Allowed: #{McpToolkit::Filtering::AREL_PREDICATIONS.join(", ")}."
+    end
+
+    @filter_operator_overrides = overrides
+  end
+
+  # Caps how many values an IN-set filter may resolve to, and how many operator
+  # conditions may be ANDed on a single attribute, so a valid token can't emit
+  # an unbounded IN clause / AND-chain (oversized SQL + Arel AST and expensive
+  # planning; rate limiting is opt-in via rate_limit_max_requests). Applies to
+  # the default :tokenized bare-value semantics and to { op:, value: }
+  # conditions. nil disables the cap.
+  #
+  # @return [Integer, nil]
+  attr_accessor :max_filter_values
+
+  # Caps how many JSON-RPC calls a single POST batch may carry on the authority
+  # transport. Rate limiting is per-HTTP-request, so an uncapped batch would let
+  # one request fan out unbounded work (N tool executions / N upstream calls)
+  # under a single rate-limit tick. nil disables the cap.
+  #
+  # @return [Integer, nil]
+  attr_accessor :max_batch_size
+
   # --- protocol / transport --------------------------------------------------
 
   # @return [String, nil] protocol version to pin on the underlying MCP::Server.
@@ -277,11 +365,31 @@ class McpToolkit::Configuration
   # where a tool object responds to `#required_permissions_scope` (String|nil, the
   # gem's scope gate) and `#call(context:, **arguments)` (returns Hash|String,
   # which the gem wraps into `{ content: [{ type: "text", text: }] }`). See
-  # McpToolkit::Tools::AuthorityBase for a base that satisfies this. nil = the host
-  # contributes no own tools (a pure gateway).
+  # McpToolkit::Tools::AuthorityBase for a base that satisfies this.
   #
-  # @return [#tool_definitions, #find, nil]
-  attr_accessor :tool_provider
+  # UNSET (the default), the provider is composed automatically: the generic
+  # RegistryToolProvider (bound to this config) first, then every entry of
+  # `extra_tool_providers` — so a host that only serves the generic tools plus
+  # its own bespoke ones needs no provider plumbing at all. Assign explicitly to
+  # take full control of the catalog.
+  #
+  # @return [#tool_definitions, #find]
+  attr_writer :tool_provider
+
+  def tool_provider
+    @tool_provider || composed_tool_provider
+  end
+
+  # Additional tool providers (or bare TOOL classes, auto-wrapped in a
+  # SingleToolProvider) composed AFTER the generic Registry-backed tools when
+  # `tool_provider` is not explicitly assigned. The registry provider is always
+  # first, so a generic tool name resolves to it; extras only answer their own
+  # names.
+  #
+  #   config.extra_tool_providers = [MyApp::Tools::AuditLog]
+  #
+  # @return [Array<#tool_definitions, Class>]
+  attr_accessor :extra_tool_providers
 
   # --- generic tool naming ---------------------------------------------------
 
@@ -327,9 +435,7 @@ class McpToolkit::Configuration
     @token_authenticator = nil
 
     @cache_store = ActiveSupport::Cache::MemoryStore.new
-    @session_ttl = 3600 # 1 hour
-
-    @sql_sanitizer = McpToolkit::SqlSanitizer.new
+    initialize_data_path_defaults
 
     @protocol_version = nil
     @supported_protocol_versions = McpToolkit::Protocol::SUPPORTED_VERSIONS
@@ -348,6 +454,40 @@ class McpToolkit::Configuration
     @upstreams = McpToolkit::Gateway::UpstreamRegistry.new
   end
 
+  # Session-TTL and list-executor defaults: the :tokenized / :created_at
+  # data-path semantics (a host preserving a pre-gem contract overrides these —
+  # see each accessor's docs).
+  def initialize_data_path_defaults
+    @session_ttl = 3600 # 1 hour
+
+    @sql_sanitizer = McpToolkit::SqlSanitizer.new
+    @bare_filter_value_semantics = :tokenized
+    @non_numeric_pk_order = :created_at
+    @filter_operator_overrides = {}
+    @max_filter_values = 500
+    @max_batch_size = 50
+  end
+
+  # The default authority tool catalog when no explicit `tool_provider` is
+  # assigned: the generic Registry-backed tools first (so a generic name always
+  # resolves to them; included only when the host registered resources — a pure
+  # gateway keeps contributing nothing), then each extra provider — a bare tool
+  # CLASS is wrapped in a SingleToolProvider. Built per read (cheap, stateless
+  # providers), so a reload that re-assigns `extra_tool_providers` or registers
+  # resources takes effect immediately.
+  def composed_tool_provider
+    providers = []
+    providers << McpToolkit::Authority::RegistryToolProvider.new(config: self) if registry.resources.any?
+    Array(extra_tool_providers).each do |provider|
+      providers << (provider.respond_to?(:tool_definitions) ? provider : McpToolkit::Authority::SingleToolProvider.new(provider))
+    end
+    return nil if providers.empty?
+    return providers.first if providers.one?
+
+    McpToolkit::Authority::CompositeToolProvider.new(*providers)
+  end
+  private :composed_tool_provider
+
   # The authority transport's injection points all default to nil (a no-op): a
   # pure satellite/gateway never touches them. `rate_limit_window` is the sole
   # non-nil default (the window size only matters once a cap opts in).
@@ -357,6 +497,7 @@ class McpToolkit::Configuration
     @usage_flusher = nil
     @session_data_builder = nil
     @tool_provider = nil
+    @extra_tool_providers = []
     @rate_limit_max_requests = nil # nil = rate limiting disabled
     @rate_limit_window = 3600 # 1 hour
     @superuser_resolver = nil # nil = duck-type principal.superuser?
@@ -372,6 +513,19 @@ class McpToolkit::Configuration
     upstreams.register(key:, url:, public_tool_list:)
   end
 
+  # Declares the gateway's upstreams from an ENV-var map — `{ key => env var
+  # name }` — the shape every authority host repeats: resets the registry first
+  # (idempotent across code reloads, where the registration typically re-runs in
+  # a `to_prepare`), and an upstream whose ENV url is blank is never registered,
+  # so an unconfigured environment behaves like no-upstreams. `env` is
+  # injectable for tests.
+  #
+  #   config.register_upstreams_from_env("billing" => "BILLING_MCP_URL")
+  def register_upstreams_from_env(mapping, env: ENV)
+    upstreams.reset!
+    mapping.each { |key, env_var| register_upstream(key:, url: env[env_var.to_s]) }
+  end
+
   # The gateway handshake client name, defaulting to the server identity when the
   # host hasn't split it. Read (not stored) so a `server_name` change before the
   # split is set still flows through.

data/lib/mcp_toolkit/dispatcher.rb

@@ -42,9 +42,13 @@ class McpToolkit::Dispatcher
     config.logger&.error("MCP dispatcher error: #{e.message}\n#{e.backtrace&.join("\n")}")
     return nil unless request.key?("id")
 
+    # A generic message to the caller: the raw exception text of an UNEXPECTED
+    # error (ActiveRecord::StatementInvalid carrying SQL, a NoMethodError naming
+    # internal classes, an internal hostname) must not leak. Full detail is in
+    # the log line above.
     McpToolkit::Protocol.error_response(
       id: request["id"],
-      error: McpToolkit::Protocol::InternalError.new(e.message)
+      error: McpToolkit::Protocol::InternalError.new("Internal error")
     )
   end
 
@@ -189,8 +193,13 @@ class McpToolkit::Dispatcher
   # JSON gives string keys; a tool's `call(context:, **arguments)` needs symbol
   # keys for the keyword splat. Deep-symbolized so nested argument hashes reach
   # the tool in the same shape a symbol-keyed caller would pass.
+  #
+  # `context` is stripped: a tool is invoked as `call(context:, **arguments)`, and
+  # a splatted keyword OVERRIDES the explicit one, so a caller-supplied `context`
+  # argument would replace the gem-resolved Authority::Context with attacker JSON
+  # (auth-context injection). `context` is never a legitimate tool argument.
   def symbolized_arguments(arguments)
-    arguments.to_h.deep_symbolize_keys
+    arguments.to_h.deep_symbolize_keys.except(:context)
   end
 
   def ensure_tool_scope!(tool)
@@ -228,7 +237,12 @@ class McpToolkit::Dispatcher
         data: error.jsonrpc_error["data"]
       )
     else
-      McpToolkit::Protocol::InternalError.new(error.message)
+      # A TRANSPORT failure (no upstream JSON-RPC error): its message embeds the
+      # internal upstream host:port (Faraday/Net::HTTP "Failed to open TCP
+      # connection to <host>:<port>"). The proxy already logged the detail
+      # (Gateway::Proxy#log_proxied_failure), so relay only a generic error —
+      # never the internal topology — to the caller.
+      McpToolkit::Protocol::InternalError.new("Internal error")
     end
   end
 end

data/lib/mcp_toolkit/engine.rb

@@ -3,12 +3,15 @@
 # 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 mounts it in one line:
+# 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)

data/lib/mcp_toolkit/engine_controllers.rb

@@ -49,10 +49,18 @@ module McpToolkit
     end
   end
 
-  # The SATELLITE transport controller the engine mounts (unchanged behavior; the
-  # SDK-backed path). Built lazily only so its parent is read after config.
+  # 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)
-    Class.new(parent) { include McpToolkit::Transport::ControllerMethods }
+    concern = config.authority? ? McpToolkit::Authority::ControllerMethods : McpToolkit::Transport::ControllerMethods
+    Class.new(parent) { include concern }
   end
 
   # The AUTHORITY introspection endpoint the engine mounts at

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

@@ -96,20 +96,40 @@ class McpToolkit::Gateway::Aggregator
     # 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.map do |definition|
+    client.tools_list.filter_map do |definition|
       namespaced(upstream, definition)
     end
   end
 
-  # Re-keys an upstream tool definition into the gateway's aggregate namespace.
+  # 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)
-    definition = definition.dup
-    definition["name"] = upstream.name_for(definition["name"])
-    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