mcp_toolkit 0.3.0 → 0.4.0

data/lib/mcp_toolkit/rate_limiter.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# A fixed-window request counter backing the authority transport's built-in rate
+# limiting (McpToolkit::Authority::ControllerMethods#mcp_rate_limit!). It is
+# storage-agnostic: it counts against the injected `cache_store` (any
+# ActiveSupport::Cache::Store — a shared Rails.cache in production, a MemoryStore
+# in a unit test), so a host enables per-principal throttling by setting
+# `config.rate_limit_max_requests` alone, without hand-rolling a limiter.
+#
+# The window is FIXED, not sliding: every request whose time falls in the same
+# `window`-second bucket shares one counter, keyed by that bucket's start
+# (`window_start`); the entry expires after `window` seconds. The counter is
+# incremented once per call, and the request is allowed while the running count is
+# `<= max_requests`, blocked once it exceeds it (so exactly `max_requests`
+# requests pass per window).
+#
+#   result = McpToolkit::RateLimiter.new(
+#     key: principal.id, max_requests: 1_000, window: 3_600, cache_store: Rails.cache
+#   ).call
+#   result.allowed?     # => false once the count exceeds max_requests
+#   result.limit        # => 1_000
+#   result.remaining    # => max_requests - count, floored at 0
+#   result.reset_at     # => epoch seconds of the next window boundary
+#   result.retry_after  # => seconds until reset_at (0 when already past)
+#
+# The cache key is namespaced (`mcp_toolkit:rate_limit:<key>:<window_start>`) so a
+# host's own cache entries never collide with the counter.
+class McpToolkit::RateLimiter
+  # The outcome of one #call: the throttling decision plus the values the
+  # transport renders into the `X-RateLimit-*` / `Retry-After` headers.
+  Result = Struct.new(:allowed, :limit, :remaining, :reset_at, :retry_after, keyword_init: true) do
+    def allowed?
+      allowed
+    end
+  end
+
+  def initialize(key:, max_requests:, cache_store:, window: 3_600, now: Time.now)
+    @key = key
+    @max_requests = max_requests
+    @cache_store = cache_store
+    @window = window
+    @now = now.to_i
+  end
+
+  # Increments this window's counter and returns the Result. Called once per
+  # request by the transport's rate-limit hook.
+  def call
+    count = @cache_store.increment(cache_key, 1, expires_in: @window) || 1
+    allowed = count <= @max_requests
+
+    Result.new(
+      allowed:,
+      limit: @max_requests,
+      remaining: allowed ? @max_requests - count : 0,
+      reset_at:,
+      retry_after: [reset_at - @now, 0].max
+    )
+  end
+
+  private
+
+  def window_start
+    @now - (@now % @window)
+  end
+
+  def reset_at
+    window_start + @window
+  end
+
+  def cache_key
+    "mcp_toolkit:rate_limit:#{@key}:#{window_start}"
+  end
+end

data/lib/mcp_toolkit/registry.rb

@@ -13,8 +13,33 @@ class McpToolkit::Registry
   def initialize
     @resources = {}
     @default_required_permissions_scope = nil
+    @resource_extension = nil
+    @resource_finalizer = nil
   end
 
+  # A Module MIXED INTO every Resource before its registration block runs, so a host
+  # can add its OWN declaration DSL (its "extras") on top of the gem's built-in
+  # `model` / `scope` / `serializer` / `filterable` / `superusers_only!` / `note` /
+  # `filter`. The host method typically stores into the generic `Resource#extra`
+  # bag; the `resource_finalizer` reads it back. nil (the default) mixes in nothing,
+  # so a host with no extras is unaffected. Set ONCE in `configure` (not per reload),
+  # since `reset!` preserves it.
+  #
+  #   McpToolkit.registry.resource_extension = MyApp::ResourceExtension  # adds `dependencies`
+  #
+  # @return [Module, nil]
+  attr_accessor :resource_extension
+
+  # A callable run against each Resource AFTER its registration block, so a host can
+  # derive gem-native fields from its declared extras — e.g. build a `serializer`
+  # from the `model` + declared `dependencies`, or a lazy `filterable`. `->(resource)`.
+  # nil (the default) is a no-op. This is the hook that lets a host avoid a parallel
+  # registration system: it declares resources DIRECTLY against the gem registry and
+  # fills the derived pieces here. Set ONCE in `configure`; preserved across `reset!`.
+  #
+  # @return [#call, nil]
+  attr_accessor :resource_finalizer
+
   # Registry-wide DEFAULT required scope, so a satellite declares its scope ONCE
   # for every resource instead of repeating it per resource:
   #
@@ -32,7 +57,9 @@ class McpToolkit::Registry
 
   def register(name, &)
     resource = McpToolkit::Resource.new(name)
+    resource.extend(@resource_extension) if @resource_extension
     resource.instance_eval(&)
+    @resource_finalizer&.call(resource)
     @resources[name.to_s] = resource
   end
 
@@ -59,8 +86,9 @@ class McpToolkit::Registry
   end
 
   # Clears registered resources for a dev reload (the satellite re-declares them
-  # in `to_prepare`). The `default_required_permissions_scope` is PRESERVED, since
-  # it's declared once in `configure` rather than per-reload.
+  # in `to_prepare`). The `default_required_permissions_scope`, `resource_extension`
+  # and `resource_finalizer` are PRESERVED, since they're declared once in
+  # `configure` rather than per-reload.
   def reset!
     @resources = {}
   end

data/lib/mcp_toolkit/resource.rb

@@ -16,6 +16,20 @@
 class McpToolkit::Resource
   class NotConfigured < StandardError; end
 
+  # A resource-specific ("custom") filter: a request-facing key whose value is
+  # applied to the relation by an arbitrary host-supplied block, rather than the
+  # generic equality/operator allowlist. The block is api-agnostic — it receives
+  # the already-scoped relation and the raw request value and returns a narrowed
+  # relation — so a host can express a relational or otherwise non-column filter
+  # (e.g. "only rows whose associated booking is in this rental") without the gem
+  # knowing anything about the query. `type`/`description` are surfaced by
+  # resource_schema so a client can discover the filter.
+  CustomFilter = Struct.new(:name, :type, :description, :applier, keyword_init: true)
+
+  # Sentinel distinguishing `extra(:key)` (read) from `extra(:key, nil)` (write nil).
+  UNSET = Object.new
+  private_constant :UNSET
+
   attr_reader :name
 
   def initialize(name)
@@ -24,10 +38,32 @@ class McpToolkit::Resource
     @serializer = nil
     @scope_block = nil
     @description = nil
+    @note = nil
+    @superusers_only = false
     @filterable = {}
+    @filterable_source = nil
+    @custom_filters = {}
     @required_permissions_scope = nil
+    @extras = {}
+  end
+
+  # A generic, api-agnostic metadata bag for host-defined "extras" — declarations
+  # the gem does not model itself (e.g. an app's ORM dependency list used to build a
+  # serializer). It is the storage behind `config.registry.resource_extension` (the
+  # host DSL that writes extras inside a registration block) and
+  # `config.registry.resource_finalizer` (which reads them back to derive gem-native
+  # fields such as `serializer` / `filterable`). Write with `extra(:key, value)`;
+  # read with `extra(:key)` (nil when unset). The gem never inspects the values.
+  def extra(key, value = UNSET)
+    return @extras[key] if value.equal?(UNSET)
+
+    @extras[key] = value
   end
 
+  # The full host-extras bag (symbol/whatever key => value). Read-only view for a
+  # resource_finalizer that wants to iterate every declared extra.
+  attr_reader :extras
+
   def model(klass = nil)
     @model = klass if klass
     @model
@@ -48,6 +84,59 @@ class McpToolkit::Resource
     @description
   end
 
+  # Free-form usage caveat surfaced by the `resources` / `resource_schema` tools,
+  # e.g. to flag a resource as internal-debugging-only and not to be interpreted
+  # without domain knowledge. Read with no arg. api-agnostic passthrough string.
+  def note(text = nil)
+    @note = text if text
+    @note
+  end
+
+  # Restricts this resource to superuser (cross-tenant) callers on the AUTHORITY
+  # path: an authority tool refuses `get` / `list` / `resource_schema` for a
+  # non-superuser and HIDES the resource from `resources` discovery. Declared in a
+  # resource's registration block:
+  #
+  #   McpToolkit.registry.register(:audit_events) do
+  #     superusers_only!
+  #     ...
+  #   end
+  #
+  # Generic and api-agnostic — the gem never names an app concept; the caller's
+  # superuser-ness is derived by the Authority::Context off the principal.
+  def superusers_only!
+    @superusers_only = true
+  end
+
+  # Whether this resource is restricted to superuser callers (default false).
+  def superusers_only?
+    @superusers_only
+  end
+
+  # Declares a resource-specific ("custom") filter: a request-facing `name` whose
+  # value is applied to the already-scoped relation by the given block. Unlike the
+  # `filterable` allowlist (generic equality/operator filters on a declared
+  # column), a custom filter runs ARBITRARY host logic, so a host can express a
+  # relational filter the gem could not derive:
+  #
+  #   filter :rental_id, type: :integer, description: "Only rows for this rental" do |relation, value|
+  #     relation.joins(:booking).where(bookings: { rental_id: value })
+  #   end
+  #
+  # The block receives `(relation, value)` and MUST return a relation (narrowing
+  # only). `type` / `description` are metadata surfaced by `resource_schema`. The
+  # value arrives from a TOP-LEVEL request param keyed by `name` (see ListExecutor),
+  # applied BEFORE the allowlist `filterable` filters. api-agnostic: the gem stores
+  # and calls the block without inspecting it.
+  def filter(name, type:, description:, &applier)
+    @custom_filters[name.to_sym] = CustomFilter.new(name: name.to_sym, type:, description:, applier:)
+  end
+
+  # Request-facing custom-filter key (symbol) => CustomFilter. Consumed by the list
+  # executor (which applies each block whose key is present in the request params)
+  # and by resource_schema (which surfaces each filter's type/description).
+  attr_reader :custom_filters
+
   # The OAuth-style scope a token MUST carry to reach this resource via the
   # generic tools (e.g. "notifications__read"). Declared explicitly per resource:
   #
@@ -80,24 +169,35 @@ class McpToolkit::Resource
   #
   # Unmapped/unknown keys are rejected by the list executor, never silently
   # dropped, so a typo surfaces as actionable feedback.
-  def filterable(mapping = nil)
-    return @filterable if mapping.nil?
-
-    mapping.each do |request_key, column|
-      @filterable[request_key.to_sym] = column.to_sym
+  # Accepts a Hash (merged now) OR a callable returning a Hash (resolved LAZILY on
+  # first read). The lazy form lets a host derive the map from something that must
+  # NOT be touched at registration/boot time — e.g. a DB-backed column list
+  # (`Model.column_names`): registration typically runs inside an initializer's
+  # `to_prepare`, before the database may exist (e.g. CI's `db:create`), so hitting
+  # the DB there aborts boot. A callable source is invoked at most once — on the
+  # first read (a tool call, when the DB is present) — then memoized.
+  def filterable(mapping = nil, &block)
+    source = block || mapping
+    return filterable_columns if source.nil?
+
+    if source.respond_to?(:call)
+      @filterable_source = source
+    else
+      merge_filterable!(source)
     end
-    @filterable
+    self
   end
 
   # Request-facing filter keys (symbols, sorted) this resource can be filtered
   # by. Surfaced via the `resource_schema` tool.
   def filterable_keys
-    @filterable.keys.sort
+    filterable_columns.keys.sort
   end
 
   # Request-facing filter key (symbol) => backing column (symbol). Consumed by
   # the list executor to build the WHERE clause.
   def filterable_columns
+    resolve_filterable_source!
     @filterable
   end
 
@@ -126,4 +226,22 @@ class McpToolkit::Resource
 
     serializer.declared_associations
   end
+
+  private
+
+  # Resolves a lazily-provided filterable source (a callable) exactly once — on the
+  # first `filterable_columns` / `filterable_keys` read — then drops it, so later
+  # reads are pure Hash access. This is what keeps a DB-derived map (e.g.
+  # `Model.column_names`) out of registration/boot time.
+  def resolve_filterable_source!
+    return unless @filterable_source
+
+    source = @filterable_source
+    @filterable_source = nil
+    merge_filterable!(source.call || {})
+  end
+
+  def merge_filterable!(mapping)
+    mapping.each { |request_key, column| @filterable[request_key.to_sym] = column.to_sym }
+  end
 end

data/lib/mcp_toolkit/resource_schema.rb

@@ -38,6 +38,7 @@ class McpToolkit::ResourceSchema
     {
       name: resource.name,
       description: resource.description,
+      note: resource.note,
       attributes:,
       relationships:,
       standard_filters: STANDARD_FILTERS,
@@ -59,10 +60,22 @@ class McpToolkit::ResourceSchema
       name:,
       type: type ? type.to_s : COMPUTED_TYPE,
       format: type ? TYPE_FORMATS[type] : nil,
-      filterable: filterable_column_for(name).present?
+      filterable: filterable_column_for(name).present?,
+      operators: operators_for(name)
     }.compact
   end
 
+  # The filter operators an attribute accepts, derived from the backing column's
+  # type via McpToolkit::Filtering::OPERATORS_BY_TYPE. `[]` for a non-filterable
+  # attribute (or one whose column type has no operator set) — self-describing so
+  # a client knows exactly which `{ op:, value: }` conditions `list` will accept.
+  def operators_for(attribute_name)
+    pair = filterable_column_for(attribute_name)
+    return [] unless pair
+
+    McpToolkit::Filtering::OPERATORS_BY_TYPE.fetch(column_type(pair.last), [])
+  end
+
   # Per-attribute equality filters this resource accepts on the `list` tool's
   # `filter` argument. Each entry is the request-facing key, the backing column
   # it matches against, and the column's type — self-describing so an MCP client

data/lib/mcp_toolkit/serializer/base.rb

@@ -144,8 +144,8 @@ class McpToolkit::Serializer::Base
 
   # Infer the serialized model from the serializer class name by stripping a
   # trailing "Serializer" and the host namespace, e.g.
-  #   Mcp::NotificationSerializer            -> Notification
-  #   Mcp::PushNotifications::FilterSerializer -> PushNotifications::Filter
+  #   Api::WidgetSerializer                 -> Widget
+  #   Api::ScheduledWidgets::FilterSerializer -> ScheduledWidgets::Filter
   # Subclasses whose name doesn't follow the convention set `model_class`.
   def self.model_class
     @model_class ||= begin

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:)
+    config.cache_store.write(cache_key(id), stored, expires_in: config.session_ttl)
+    # `data` defaults to {} for legacy rows written before the payload existed.
+    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/tools/authority_base.rb

@@ -0,0 +1,127 @@
+# 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
+
+  # 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
+  rescue StandardError => e
+    raise McpToolkit::Protocol::InternalError, e.message
+  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
+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,95 @@
+# 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.
+  def flush(controller:)
+    events = buffer_for(controller)
+    return if events.empty?
+
+    @sink.call(events)
+  rescue StandardError => e
+    report("failed to flush #{events&.size} event(s)", e)
+  end
+
+  private
+
+  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.4.0"
 end