mcp_toolkit 0.3.0 → 0.5.0

data/lib/mcp_toolkit/session.rb

@@ -7,24 +7,31 @@
 # Cache-backed (rather than the gem's in-process StreamableHTTPTransport) so
 # sessions survive across Puma workers and interoperate with a gateway's client.
 # The cache store + TTL come from McpToolkit.config.
+#
+# A session carries an opaque `data` hash the transport can attach at creation
+# (e.g. `{ token_id: ... }`) so an AUTHORITY can bind a session to a token id —
+# the property that lets a revoked token kill an in-flight session. The gem does
+# NOT interpret `data` (it never re-resolves a token; that's the consumer's auth
+# concern): it stores it, round-trips it, and exposes it via `#data`.
 class McpToolkit::Session
   CACHE_KEY_PREFIX = "mcp_toolkit:session:"
 
-  def self.create!(config: McpToolkit.config)
+  def self.create!(data: {}, config: McpToolkit.config)
     id = SecureRandom.uuid
-    config.cache_store.write(cache_key(id), { created_at: Time.now.to_i }, expires_in: config.session_ttl)
-    new(id:)
+    config.cache_store.write(cache_key(id), { created_at: Time.now.to_i, data: }, expires_in: config.session_ttl)
+    new(id:, data:)
   end
 
   def self.find(id, config: McpToolkit.config)
     return nil if id.to_s.empty?
 
-    data = config.cache_store.read(cache_key(id))
-    return nil unless data
+    stored = config.cache_store.read(cache_key(id))
+    return nil unless stored
 
-    # Sliding expiry: bump TTL on every successful lookup.
-    config.cache_store.write(cache_key(id), data, expires_in: config.session_ttl)
-    new(id:)
+    # Sliding expiry: bump TTL on every successful lookup, re-writing the row
+    # untouched.
+    config.cache_store.write(cache_key(id), stored, expires_in: config.session_ttl)
+    new(id:, data: stored[:data] || {})
   end
 
   def self.delete(id, config: McpToolkit.config)
@@ -38,9 +45,10 @@ class McpToolkit::Session
   end
   private_class_method :cache_key
 
-  attr_reader :id
+  attr_reader :id, :data
 
-  def initialize(id:)
+  def initialize(id:, data: {})
     @id = id
+    @data = data || {}
   end
 end

data/lib/mcp_toolkit/tool_reference_rewriter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Rewrites backticked generic-tool references ("use the `resources` tool") inside
+# tool prose so they always name the tools exactly as they appear in the serving
+# server's `tools/list`. Two serving paths need this: the authority's own generic
+# tools when the host configures a `generic_tool_name_prefix` (a client would
+# otherwise be pointed at an unprefixed tool that does not exist), and the
+# gateway's aggregated upstream tools, whose names are re-keyed into the
+# `<app>__<tool>` namespace while their prose would otherwise keep naming the
+# upstream's bare tools.
+#
+# Only EXACT backticked base names are rewritten; other backticked terms
+# (`resource`, `filter`, `target_resource`, ...) never match.
+module McpToolkit::ToolReferenceRewriter
+  GENERIC_TOOL_REFERENCES = /`(resource_schema|resources|list|get)`/
+
+  module_function
+
+  # Rewrites `node` (a String, or a Hash/Array structure such as a tool
+  # definition or input schema, walked recursively) with `name_prefix` applied to
+  # every backticked generic-tool reference. Non-string leaves pass through
+  # untouched; an empty prefix returns the node verbatim.
+  def rewrite(node, name_prefix)
+    return node if name_prefix.to_s.empty?
+
+    case node
+    when String then node.gsub(GENERIC_TOOL_REFERENCES) { "`#{name_prefix}#{Regexp.last_match(1)}`" }
+    when Hash then node.transform_values { |value| rewrite(value, name_prefix) }
+    when Array then node.map { |value| rewrite(value, name_prefix) }
+    else node
+    end
+  end
+end

data/lib/mcp_toolkit/tools/authority_base.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+# Optional base class for a HOST's own tools served by the authority dispatcher
+# (McpToolkit::Dispatcher). A host tool MAY subclass this, or may be any object
+# satisfying the duck-typed tool contract the dispatcher calls:
+#
+#   tool.required_permissions_scope        -> String | nil   (gem's scope gate)
+#   tool.call(context:, **arguments)       -> Hash | String  (gem wraps into
+#                                                              { content: [...] })
+#
+# The dispatcher treats the object returned by `provider.find(name)` as the tool;
+# an AuthorityBase SUBCLASS satisfies the contract as CLASS methods (the class
+# `.call` instantiates, runs, and error-maps a single invocation).
+#
+# What this base adds over hand-rolling the contract:
+#   * a class DSL (`tool_name` / `description` / `input_schema` /
+#     `required_permissions_scope` / `definition`) mirroring the tool-definition
+#     shape `tools/list` returns;
+#   * per-request accessors (`account` / `principal` / `bearer_token` /
+#     `superuser?`) read from the injected Authority::Context;
+#   * `ensure_resource_accessible!` to gate a superuser-only resource;
+#   * error mapping — an ArgumentError (e.g. a missing required kwarg) becomes an
+#     InvalidParams, any other StandardError an InternalError, while a
+#     deliberately-raised McpToolkit::Protocol::Error passes through with its own
+#     code.
+#
+# The gem NEVER references a host's API layer, serializers, or resource catalog —
+# all of that lives behind the host's `#call`.
+class McpToolkit::Tools::AuthorityBase
+  class << self
+    attr_reader :_tool_name, :_description, :_input_schema
+
+    def tool_name(name = nil)
+      if name
+        @_tool_name = name.to_s
+      else
+        @_tool_name || self.name.to_s.demodulize.underscore.gsub(/_tool$/, "")
+      end
+    end
+
+    def description(desc = nil)
+      @_description = desc if desc
+      @_description
+    end
+
+    def input_schema(&block)
+      @_input_schema = yield if block
+      @_input_schema || { type: "object", properties: {} }
+    end
+
+    # OAuth-style scope (`<app>__<action>`) a token must carry to call this tool,
+    # enforced by the dispatcher before the tool runs. Defaults to nil (no scope
+    # required). NOT inherited — a subclass that doesn't declare its own scope is
+    # unscoped, even if an ancestor declared one.
+    def required_permissions_scope(scope = nil)
+      @_required_permissions_scope = scope.to_s if scope
+      @_required_permissions_scope
+    end
+
+    def definition
+      {
+        name: tool_name,
+        description: _description,
+        inputSchema: _input_schema || { type: "object", properties: {} }
+      }
+    end
+
+    # The dispatcher's entry point: build an instance bound to this request's
+    # context and run it, mapping tool-level errors to protocol errors.
+    def call(context:, **arguments)
+      new(context:).execute(**arguments)
+    end
+  end
+
+  attr_reader :context
+
+  def initialize(context:)
+    @context = context
+  end
+
+  def account
+    context.account
+  end
+
+  def principal
+    context.principal
+  end
+
+  def bearer_token
+    context.bearer_token
+  end
+
+  # Whether the caller is a superuser, per the Context (which duck-types it off
+  # the principal). Used to gate resources/tools that expose cross-tenant data.
+  def superuser?
+    context.superuser?
+  end
+
+  # Guards a resource flagged `superusers_only?`: a non-superuser caller is
+  # refused. No-op for unrestricted resources.
+  def ensure_resource_accessible!(resource)
+    return unless resource.superusers_only?
+    return if superuser?
+
+    raise McpToolkit::Protocol::InvalidRequest, "#{resource.name} is restricted to superuser (user-scoped) MCP tokens"
+  end
+
+  # ArgumentErrors Ruby itself raises while binding the request arguments to the
+  # subclass's `#call` signature: a missing/unknown keyword or wrong arity. Their
+  # messages carry only keyword names (the tool's own declared params) and counts,
+  # so surfacing them tells a client how to fix the call. Every OTHER ArgumentError
+  # is raised from inside the tool's business logic (e.g. `Integer("x")`) and its
+  # message may carry SQL, internal class names, or a value — so it is sanitized
+  # like any unexpected error rather than relayed verbatim.
+  ARGUMENT_BINDING_ERROR_MESSAGE = /\A(missing keyword|unknown keyword|wrong number of arguments)/
+
+  # Runs the tool's business logic (the subclass's `#call`) with error mapping.
+  # Arrives with symbol-keyed arguments from the dispatcher.
+  def execute(**arguments)
+    call(**arguments)
+  rescue McpToolkit::Protocol::Error
+    # A deliberately-raised protocol error carries its own JSON-RPC code
+    # (e.g. InvalidParams); let it bubble untouched so the client sees it.
+    raise
+  rescue ArgumentError => e
+    raise McpToolkit::Protocol::InvalidParams, e.message if ARGUMENT_BINDING_ERROR_MESSAGE.match?(e.message)
+
+    raise sanitized_internal_error(e)
+  rescue StandardError => e
+    raise sanitized_internal_error(e)
+  end
+
+  # The subclass implements its business logic here, receiving the tool arguments
+  # as keywords and returning a Hash or String.
+  def call(**_arguments)
+    raise NotImplementedError, "#{self.class} must implement #call"
+  end
+
+  private
+
+  # An UNEXPECTED error's message may carry SQL, internal class names, or a
+  # hostname — it must not reach the caller (the dispatcher relays a
+  # Protocol::Error's message verbatim). Log the detail; return a generic error.
+  def sanitized_internal_error(error)
+    McpToolkit.config.logger&.error("MCP tool #{self.class} error: #{error.message}\n#{error.backtrace&.join("\n")}")
+    McpToolkit::Protocol::InternalError.new("Internal error")
+  end
+end

data/lib/mcp_toolkit/tools/base.rb

@@ -26,7 +26,7 @@ class McpToolkit::Tools::Base < MCP::Tool
   # `required_scope` is the explicitly-declared scope a token must carry (the
   # caller resolves it from the resource — see Registry#required_scope_for).
   # Empty/nil => no scope check (authorized_for_scope? treats "" as a pass).
-  def self.with_account(server_context, account_id: nil, required_scope: nil)
+  def self.with_account(server_context, account_id: nil, required_scope: nil, resource: nil)
     config = config_from(server_context)
     context = McpToolkit::Auth::Authenticator.call(
       token: server_context[:bearer_token],
@@ -40,6 +40,9 @@ class McpToolkit::Tools::Base < MCP::Tool
       return error_response("Unauthorized: token lacks the #{required_scope.inspect} scope")
     end
 
+    superuser_refusal = superuser_only_refusal(resource, context.introspection)
+    return superuser_refusal if superuser_refusal
+
     text_response(yield(context.scope_root))
   rescue McpToolkit::Errors::Unauthorized => e
     error_response("Unauthorized: #{e.message}")
@@ -52,7 +55,7 @@ class McpToolkit::Tools::Base < MCP::Tool
   # which reveal shape, not tenant data, so a superuser shouldn't have to pin an
   # account just to discover what exists. Empty/nil `required_scope` => no scope
   # check.
-  def self.with_authentication(server_context, required_scope: nil)
+  def self.with_authentication(server_context, required_scope: nil, resource: nil)
     config = config_from(server_context)
     introspection = McpToolkit::Auth::Introspection.call(server_context[:bearer_token], config:)
     return error_response("Unauthorized: invalid or expired token") unless introspection.valid?
@@ -61,11 +64,28 @@ class McpToolkit::Tools::Base < MCP::Tool
       return error_response("Unauthorized: token lacks the #{required_scope.inspect} scope")
     end
 
-    text_response(yield)
+    superuser_refusal = superuser_only_refusal(resource, introspection)
+    return superuser_refusal if superuser_refusal
+
+    # Yields the introspection so a discovery tool (`resources`) can HIDE
+    # superuser-only resources from a non-superuser caller (get/list/resource_schema
+    # instead pass `resource:` above to REFUSE a specific one).
+    text_response(yield(introspection))
   rescue McpToolkit::Errors::InvalidParams => e
     error_response("Invalid request: #{e.message}")
   end
 
+  # Refuses a superuser-only resource for a non-superuser caller (get / list /
+  # resource_schema); nil = allowed. Mirrors the authority path's
+  # `ensure_resource_accessible!`. `resources` HIDES such resources instead of
+  # refusing — it filters on `introspection.superuser?` directly.
+  def self.superuser_only_refusal(resource, introspection)
+    return nil unless resource&.superusers_only?
+    return nil if introspection.superuser?
+
+    error_response("Unauthorized: #{resource.name} is restricted to superuser (user-scoped) MCP tokens")
+  end
+
   def self.text_response(payload)
     text = payload.is_a?(String) ? payload : JSON.generate(payload)
     MCP::Tool::Response.new([{ type: "text", text: }])

data/lib/mcp_toolkit/tools/get.rb

@@ -48,7 +48,7 @@ class McpToolkit::Tools::Get < McpToolkit::Tools::Base
     # the scope check (and so an unknown resource is a clean tool error).
     descriptor = resolve_descriptor(resource, config)
     required_scope = config.registry.required_scope_for(descriptor)
-    with_account(server_context, account_id:, required_scope:) do |scope_root|
+    with_account(server_context, account_id:, required_scope:, resource: descriptor) do |scope_root|
       McpToolkit::GetExecutor.call(resource: descriptor, scope_root:, id:, fields:)
     end
   rescue McpToolkit::Errors::InvalidParams => e

data/lib/mcp_toolkit/tools/list.rb

@@ -15,11 +15,26 @@ class McpToolkit::Tools::List < McpToolkit::Tools::Base
       - limit: page size (default 25, max 100)
       - offset: pagination offset (default 0)
 
-    Per-attribute equality filters:
-      - filter: an object of { <key>: <value> } exact-match filters, applied ON TOP of the
-        account scope (they can only narrow, never widen). Each resource advertises its
-        available filter keys via `resource_schema` (the `filters` array). Unknown keys are
-        rejected.
+    Per-attribute filters:
+      - filter: an object of { <key>: <value> } filters, applied ON TOP of the account scope
+        (they can only narrow, never widen). Each resource advertises its available filter keys
+        and operators via `resource_schema`. Unknown keys are rejected.
+      - A bare value matches by equality. A comma-separated string or an array of scalars
+        matches ANY of the values (IN), e.g. { "status": "booked,canceled" } or
+        { "status": ["booked", "canceled"] }. The string "null" (or a JSON null) matches
+        records where the value is NULL.
+      - An operator condition is an object { "op": <operator>, "value": <value> }, e.g.
+        { "price": { "op": "gteq", "value": 100 } }. An array of conditions ANDs them into a
+        range: { "price": [{ "op": "gteq", "value": 100 }, { "op": "lt", "value": 200 }] }.
+        Each attribute's supported operators are listed in `resource_schema`.
+      - Some filter keys require a companion key (e.g. a polymorphic id and its type) —
+        `resource_schema` advertises these under a relationship's `filter.requires`; pass
+        both keys together.
+
+    Resource-specific filters:
+      - Some resources accept additional filters advertised in `resource_schema` under
+        `resource_filters`. Pass each as a TOP-LEVEL argument (NOT inside `filter`), e.g.
+        { "resource": "...", "<name>": <value> }.
 
     Sparse fieldset:
       - fields: names of the attributes and/or relationships to include in each record, as an
@@ -50,8 +65,8 @@ class McpToolkit::Tools::List < McpToolkit::Tools::Base
       },
       filter: {
         type: "object",
-        description: "Per-attribute exact-match equality filters, e.g. { \"booking_id\": 42 }. " \
-                     "See a resource's `resource_schema` `filters` for the keys it accepts.",
+        description: "Per-attribute filters, e.g. { \"booking_id\": 42 }. See a resource's " \
+                     "`resource_schema` `filters` for the keys and operators it accepts.",
         additionalProperties: true
       },
       limit: { type: "integer", description: "Page size (default 25, max 100)" },
@@ -65,7 +80,10 @@ class McpToolkit::Tools::List < McpToolkit::Tools::Base
                      "resource's `resource_schema` for valid attribute and relationship names."
       }
     },
-    required: ["resource"]
+    required: ["resource"],
+    # Resource-specific filters (resource_schema's `resource_filters`) arrive as
+    # top-level arguments, so the schema must not advertise a closed shape.
+    additionalProperties: true
   )
 
   def self.call(server_context:, resource: nil, account_id: nil, **params)
@@ -74,7 +92,7 @@ class McpToolkit::Tools::List < McpToolkit::Tools::Base
     # the scope check (and so an unknown resource is a clean tool error).
     descriptor = resolve_descriptor(resource, config)
     required_scope = config.registry.required_scope_for(descriptor)
-    with_account(server_context, account_id:, required_scope:) do |scope_root|
+    with_account(server_context, account_id:, required_scope:, resource: descriptor) do |scope_root|
       McpToolkit::ListExecutor.call(resource: descriptor, scope_root:, params:)
     end
   rescue McpToolkit::Errors::InvalidParams => e

data/lib/mcp_toolkit/tools/resource_schema.rb

@@ -7,11 +7,19 @@ class McpToolkit::Tools::ResourceSchema < McpToolkit::Tools::Base
   description <<~DESC.strip
     Describe a single read-only resource in detail. Pass the resource name as `resource` (use
     the `resources` tool to discover names). Returns:
-      - attributes: every field in the response, each with its `type` and a value `format` hint
+      - attributes: every field in the response, each with its `type`, a value `format` hint,
+        whether it is `filterable`, and the filter `operators` it accepts
       - relationships: associated resources emitted in the record's `links`; each names the
         `target_resource` it resolves to (callable via `list`/`get`)
       - standard_filters: ids, updated_since, limit, offset (accepted by the `list` tool)
-      - filters: the per-attribute equality filter keys the `list` tool accepts
+      - filters: the per-attribute equality/operator filter keys the `list` tool accepts in
+        its `filter` argument
+      - resource_filters: resource-specific filters, if any — each is passed as a TOP-LEVEL
+        argument of the `list` tool (NOT inside `filter`), e.g. { "resource": "...",
+        "<name>": <value> }
+      - filter_examples: ready-to-use `filter` payloads for this resource
+    A relationship's `filter` block lists the keys that filter by it; when it names a
+    `requires` key (e.g. a polymorphic id needing its type), pass BOTH keys together.
     The `attributes` and `relationships` names are also the valid values for the `fields` sparse
     fieldset argument on `get` / `list`. Call this before `list` to learn a resource's shape.
   DESC
@@ -31,7 +39,8 @@ class McpToolkit::Tools::ResourceSchema < McpToolkit::Tools::Base
     # Resolve the resource FIRST so its effective required scope gates discovery
     # of THIS resource's shape (and an unknown resource is a clean tool error).
     descriptor = resolve_descriptor(resource, config)
-    with_authentication(server_context, required_scope: config.registry.required_scope_for(descriptor)) do
+    with_authentication(server_context, required_scope: config.registry.required_scope_for(descriptor),
+                                        resource: descriptor) do
       McpToolkit::ResourceSchema.call(descriptor, registry: config.registry)
     end
   rescue McpToolkit::Errors::InvalidParams => e

data/lib/mcp_toolkit/tools/resources.rb

@@ -5,9 +5,10 @@ class McpToolkit::Tools::Resources < McpToolkit::Tools::Base
   tool_name "resources"
   description <<~DESC.strip
     List all read-only resources available via the `list` and `get` tools. Returns each
-    resource's name and a short description. Call this once at the start of a session to learn
-    what exists, then use `resource_schema` for a specific resource's attributes and
-    relationships.
+    resource's name, a short description, whether it accepts filters (`filterable`) and — when
+    present — a usage `note` (read it before interpreting the resource's data). Call this once
+    at the start of a session to learn what exists, then use `resource_schema` for a specific
+    resource's attributes, relationships and filters.
   DESC
 
   input_schema(properties: {})
@@ -16,12 +17,34 @@ class McpToolkit::Tools::Resources < McpToolkit::Tools::Base
     config = config_from(server_context)
     # Discovery requires the registry-level default scope (the satellite's
     # app-wide scope); per-resource scopes are enforced by `get` / `list`.
-    with_authentication(server_context, required_scope: config.registry.default_required_permissions_scope) do
+    with_authentication(server_context,
+                        required_scope: config.registry.default_required_permissions_scope) do |introspection|
       {
-        resources: config.registry.resources.map do |resource|
-          { name: resource.name, description: resource.description }
-        end
+        resources: config.registry.resources
+                         .reject { |resource| resource.superusers_only? && !introspection.superuser? }
+                         .map do |resource|
+                           {
+                             name: resource.name,
+                             description: resource.description,
+                             filterable: filterable?(resource, config),
+                             note: resource.note
+                           }.compact
+                         end
       }
     end
   end
+
+  # Whether the resource can be filtered at all — via the generic allowlist OR a
+  # resource-specific custom filter. Mirrors the authority-path resources tool:
+  # resolving a lazily-declared allowlist may run host code, and one resource's
+  # failing resolution must not take down the whole discovery index, so a raise
+  # degrades to nil (the key is omitted) and the source is retried on the next
+  # read (see Resource#filterable).
+  def self.filterable?(resource, config)
+    resource.filterable_columns.any? || resource.custom_filters.any?
+  rescue StandardError => e
+    config.logger&.warn("mcp_toolkit: filterable resolution failed for #{resource.name}: #{e.message}")
+    nil
+  end
+  private_class_method :filterable?
 end

data/lib/mcp_toolkit/transport/controller_methods.rb

@@ -5,7 +5,7 @@ require "logger"
 # The MCP Streamable-HTTP transport, provided as an includable concern. An
 # app's controller includes this to get the full transport with no per-app code:
 #
-#   class Mcp::ServerController < ApplicationController
+#   class McpController < ApplicationController
 #     include McpToolkit::Transport::ControllerMethods
 #   end
 #
@@ -44,7 +44,7 @@ require "logger"
 #
 # CSRF: the concern disables forgery protection (this is a token-authenticated
 # JSON API). Inherit from ActionController::Base (not ::API) if your app's
-# controller stack needs helper_method, as bsa-notifications does.
+# controller stack needs helper_method (as some host controller stacks require).
 module McpToolkit::Transport::ControllerMethods
   extend ActiveSupport::Concern
 

data/lib/mcp_toolkit/usage_metering/recorder.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+# Generic, api-agnostic usage metering for the AUTHORITY transport.
+#
+# Wired to the authority controller's billing hooks purely through config, so a
+# host meters MCP traffic WITHOUT subclassing or customizing the controller:
+#
+#   meter = McpToolkit::UsageMetering::Recorder.new(
+#     event_builder:    ->(request_data:, params:, arguments:, scrubbed_arguments:, account:, principal:) { {...} },
+#     sink:             ->(events) { MyLedger.insert_all(events) },
+#     parameter_filter: ActiveSupport::ParameterFilter.new(Rails.application.config.filter_parameters),
+#     logger:           Rails.logger,
+#     error_reporter:   ->(e) { Sentry.capture_exception(e) }
+#   )
+#   config.usage_recorder = meter.method(:record)   # per JSON-RPC call
+#   config.usage_flusher  = meter.method(:flush)    # after the response
+#
+# One event is accumulated per BILLABLE JSON-RPC call (default: `tools/call`) and
+# all of a request's events are flushed together after the response. Because the
+# authority transport re-resolves the account per batch element and calls `record`
+# per element, a mixed-account batch meters each call against its own account.
+#
+# Two invariants:
+#   * Metering NEVER affects the MCP response — every error here is logged (via
+#     `logger`) and reported (via `error_reporter`), then swallowed.
+#   * The raw arguments are scrubbed through `parameter_filter` BEFORE they reach
+#     the event, so a filtered key (e.g. a token) never leaves this object.
+#
+# The `event_builder` returns ONE ledger row's attributes (a Hash) for a call, or
+# nil to skip it; the gem stays app-agnostic by never naming the row's columns. The
+# `sink` persists the accumulated array in one shot.
+#
+# Per-request state (the accumulation buffer) lives on the Rack request env, so the
+# Recorder itself is stateless and safe to share across requests/threads.
+class McpToolkit::UsageMetering::Recorder
+  DEFAULT_BILLABLE_METHODS = %w[tools/call].freeze
+  BUFFER_ENV_KEY = "mcp_toolkit.usage_events"
+
+  def initialize(event_builder:, sink:, parameter_filter: nil,
+                 billable_methods: DEFAULT_BILLABLE_METHODS, logger: nil, error_reporter: nil)
+    @event_builder = event_builder
+    @sink = sink
+    @parameter_filter = parameter_filter
+    @billable_methods = billable_methods
+    @logger = logger
+    @error_reporter = error_reporter
+  end
+
+  # `config.usage_recorder` target. Accumulates one event for a billable call onto
+  # the current request's buffer. Non-billable methods (ping, initialize,
+  # tools/list, ...) are ignored; a nil event from the builder is skipped.
+  def record(request_data:, account:, principal:, controller:)
+    return unless request_data.is_a?(Hash)
+    return unless @billable_methods.include?(request_data["method"])
+
+    params = request_data["params"].to_h
+    arguments = params["arguments"].to_h
+    event = @event_builder.call(
+      request_data:, params:, arguments:,
+      scrubbed_arguments: scrub(arguments), account:, principal:
+    )
+    buffer_for(controller) << event unless event.nil?
+  rescue StandardError => e
+    report("failed to accumulate event", e)
+  end
+
+  # `config.usage_flusher` target. Persists the request's accumulated events via the
+  # sink in one shot. No-op when nothing was accumulated. If the batch write fails,
+  # falls back to per-event writes so one un-persistable ("poison") event can't drop
+  # metering for the whole request.
+  def flush(controller:)
+    events = buffer_for(controller)
+    return if events.empty?
+
+    @sink.call(events)
+  rescue StandardError => e
+    flush_individually(events, e)
+  end
+
+  private
+
+  # The batch write failed. Retry each event on its own so a single un-persistable
+  # event (a constraint violation, bad encoding) loses ONLY itself instead of
+  # dropping every sibling call's metering — which a caller could otherwise
+  # exploit to evade billing for a whole batch by appending one poison call.
+  # Assumes the batch sink is atomic (nothing persisted on failure — true for
+  # `insert_all`); a non-atomic sink could double-write the events that did land,
+  # so this stays a fallback, not the default path.
+  def flush_individually(events, batch_error)
+    @logger&.warn(
+      "MCP usage tracking: batch flush of #{events.size} event(s) failed " \
+      "(#{batch_error.message}), retrying individually"
+    )
+    events.each do |event|
+      @sink.call([event])
+    rescue StandardError => e
+      report("dropped 1 unpersistable usage event", e)
+    end
+  rescue StandardError
+    # Metering MUST NEVER affect the MCP response. `flush` already runs this from
+    # its rescue, so a raise here (e.g. a misbehaving logger or error_reporter)
+    # would escape into the after_action. Swallow it as the last resort.
+    nil
+  end
+
+  def scrub(arguments)
+    hash = arguments.to_h
+    @parameter_filter ? @parameter_filter.filter(hash) : hash
+  end
+
+  # Per-request accumulation buffer, stored on the Rack env so the Recorder holds
+  # no per-request state of its own (thread-safe to share across requests).
+  def buffer_for(controller)
+    controller.request.env[BUFFER_ENV_KEY] ||= []
+  end
+
+  def report(message, error)
+    @logger&.warn("MCP usage tracking: #{message}: #{error.message}")
+    @error_reporter&.call(error)
+  end
+end

data/lib/mcp_toolkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module McpToolkit
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

data/lib/mcp_toolkit.rb

@@ -15,9 +15,12 @@ require "zeitwerk"
 #   active_support/concern - Transport::ControllerMethods is an includable concern
 #   active_support/cache   - the default MemoryStore cache_store
 #
-# `faraday` is the one exception: it is required alongside its sole owner,
-# Auth::AuthorityServerClient, which is the only object that builds an HTTP
-# connection.
+# Two third-party libs are the exception to the centralize-here rule: each is
+# required alongside its owner file rather than up front.
+#   faraday    - the HTTP client, required by the objects that build a connection
+#                (Auth::AuthorityServerClient and Gateway::Client).
+#   concurrent - concurrent-ruby's futures, required by its sole owner
+#                Gateway::Aggregator (which pulls upstreams in parallel).
 require "json"
 require "digest"
 require "time"
@@ -63,8 +66,18 @@ loader.ignore("#{__dir__}/mcp_toolkit/version.rb")
 # under `app/controllers` (outside this lib-rooted loader), so it needs no ignore;
 # it is loaded by Rails' autoloader via the engine when mounted.
 loader.ignore("#{__dir__}/mcp_toolkit/engine.rb")
+# `engine_controllers.rb` reopens `McpToolkit` to add the lazy `parent_controller`
+# builder + `const_missing` (it defines module methods, not a file-named
+# constant), so it is required explicitly below rather than autoloaded.
+loader.ignore("#{__dir__}/mcp_toolkit/engine_controllers.rb")
 loader.setup
 
+# The lazy `parent_controller` builder (McpToolkit.build_engine_controllers! /
+# reset_engine_controllers! / const_missing). Required unconditionally (it names no
+# Rails constant at load time); it only builds controllers when one is referenced,
+# which happens only under Rails.
+require_relative "mcp_toolkit/engine_controllers"
+
 # The toolkit for building account-scoped, read-only MCP servers on top of the
 # official `mcp` gem. See README.md for the satellite + authority quickstarts.
 #