mcp_toolkit 0.3.0 → 0.5.0

data/lib/mcp_toolkit/configuration.rb

@@ -25,6 +25,24 @@ class McpToolkit::Configuration
   # @return [String, nil] human-readable `instructions` returned on `initialize`.
   attr_accessor :server_instructions
 
+  # --- gateway client identity (identity split) ------------------------------
+
+  # The `clientInfo` an app presents when it acts as a GATEWAY talking to its
+  # upstream MCP servers (McpToolkit::Gateway::Client's handshake). Split from the
+  # SERVER identity (`server_name`/`server_version`, advertised to the app's OWN
+  # callers) so an authority can present its real server identity downstream while
+  # keeping its upstream handshake byte-identical to a prior deployment. Both
+  # default to the server identity, so a satellite/gateway that doesn't care sets
+  # nothing.
+  #
+  #   c.server_name         = "acme-mcp"          # advertised to our callers
+  #   c.gateway_client_name = "acme-mcp-gateway"  # presented to our upstreams
+  #
+  # @return [String] gateway handshake client name (defaults to `server_name`).
+  attr_writer :gateway_client_name
+  # @return [String] gateway handshake client version (defaults to `server_version`).
+  attr_writer :gateway_client_version
+
   # --- serialization ---------------------------------------------------------
 
   # The DEFAULT serializer base class. A `Resource` registration that does not
@@ -81,10 +99,10 @@ class McpToolkit::Configuration
 
   # Looks up + verifies a plaintext bearer token locally, returning a token
   # object (duck-typed, see below) or nil. This is the authority's
-  # `McpToken.authenticate(plaintext)` equivalent. Required for the :authority
+  # `AccessToken.authenticate(plaintext)` equivalent. Required for the :authority
   # role; unused by a pure satellite.
   #
-  #   c.token_authenticator = ->(plaintext) { McpToken.authenticate(plaintext) }
+  #   c.token_authenticator = ->(plaintext) { AccessToken.authenticate(plaintext) }
   #
   # The returned token object must respond to the methods
   # `McpToolkit::Auth::Authority#introspection_payload` reads (see that module for
@@ -108,6 +126,39 @@ class McpToolkit::Configuration
   # @return [Integer] session sliding-TTL in seconds.
   attr_accessor :session_ttl
 
+  # --- rate limiting ---------------------------------------------------------
+
+  # The built-in per-principal request cap enforced by the authority transport
+  # (McpToolkit::Authority::ControllerMethods#mcp_rate_limit!), counted against
+  # `cache_store` via McpToolkit::RateLimiter. nil (the default) DISABLES rate
+  # limiting entirely, so a pure host is unaffected until it opts in. Set an
+  # Integer to cap each principal to that many requests per `rate_limit_window`.
+  # The default `mcp_rate_limit!` reads this through the overridable
+  # `mcp_rate_limit_max_requests` hook, so a host that keeps the cap in its own
+  # constant/model overrides that hook rather than this value.
+  #
+  # @return [Integer, nil]
+  attr_accessor :rate_limit_max_requests
+
+  # The fixed rate-limit window, in seconds (default 3600 = 1 hour). Ignored
+  # while `rate_limit_max_requests` is nil.
+  #
+  # @return [Integer]
+  attr_accessor :rate_limit_window
+
+  # --- superuser (optional, first-class) -------------------------------------
+
+  # Optional resolver deciding whether a principal is a SUPERUSER — a cross-tenant
+  # caller that may reach `superusers_only!` resources. `->(principal) -> Boolean`.
+  # When set, McpToolkit::Authority::Context#superuser? calls it; when nil (the
+  # default) the context falls back to duck-typing `principal.superuser?` (false
+  # when the principal doesn't respond to it). Superuser is FULLY OPTIONAL: a host
+  # with no such concept leaves this nil and flags no `superusers_only!` resource,
+  # so no caller is ever a superuser.
+  #
+  # @return [#call, nil]
+  attr_accessor :superuser_resolver
+
   # --- filtering -------------------------------------------------------------
 
   # Escapes LIKE wildcards in `matches` / `does_not_match` filter values so they
@@ -118,12 +169,108 @@ 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.
   #   nil lets the gem negotiate (recommended). Set only to force an older spec.
   attr_accessor :protocol_version
 
+  # The protocol versions the hand-rolled AUTHORITY dispatcher
+  # (McpToolkit::Dispatcher) negotiates, newest first. `initialize` echoes the
+  # requested version when it is in this set, else the first (latest). Defaults to
+  # McpToolkit::Protocol::SUPPORTED_VERSIONS; override to pin a host's own set.
+  #
+  # @return [Array<String>]
+  attr_accessor :supported_protocol_versions
+
   # The parent class (as a String, resolved via `constantize`) of the
   # gem-provided McpToolkit::ServerController that McpToolkit::Engine mounts.
   # Doorkeeper-style indirection so a satellite mounting the engine can keep
@@ -151,12 +298,131 @@ class McpToolkit::Configuration
   # @return [McpToolkit::Registry]
   attr_accessor :registry
 
+  # --- gateway / upstreams ---------------------------------------------------
+
+  # @return [Integer] HTTP open/read timeout (s) for a gateway's calls to an
+  #   upstream MCP server (McpToolkit::Gateway::Client).
+  attr_accessor :upstream_timeout
+  # @return [Integer] TTL (s) for an upstream's cached, namespaced tool list in
+  #   McpToolkit::Gateway::Aggregator.
+  attr_accessor :upstream_list_ttl
+
+  # The registry of upstream MCP servers this gateway aggregates + proxies to.
+  # Each config carries its own (like `registry`), so it resets with a fresh
+  # config. Register via the `register_upstream` sugar below or directly on this
+  # instance. Empty unless the app registers upstreams, so a non-gateway app is
+  # unaffected.
+  #
+  # @return [McpToolkit::Gateway::UpstreamRegistry]
+  attr_reader :upstreams
+
+  # --- authority hooks -------------------------------------------------------
+  #
+  # Injection points for the AUTHORITY transport (McpToolkit::Authority::
+  # ControllerMethods) so a PURE host drives billing/tenancy from config without
+  # subclassing. A host whose logic touches its own models overrides the matching
+  # hook METHOD on its McpToolkit::Authority::ServerController subclass instead;
+  # then these stay nil. All default to nil (a no-op).
+
+  # OPTIONAL escape hatch that FULLY REPLACES the built-in limiter: a
+  # `->(controller:, principal:)` that renders + halts when over the limit (or
+  # sets rate-limit headers when under). When set, `mcp_rate_limit!` delegates to
+  # it and the built-in (`rate_limit_max_requests`) is skipped. nil (the default)
+  # means the built-in runs instead. Most hosts want the built-in; reach for this
+  # only when the counting itself must live in app code.
+  #
+  # @return [#call, nil]
+  attr_accessor :rate_limiter
+
+  # Records ONE usage event for a single JSON-RPC call (called per batch element).
+  # `->(request_data:, account:, principal:, controller:)`. MUST never affect the
+  # MCP response. nil = no metering.
+  #
+  # @return [#call, nil]
+  attr_accessor :usage_recorder
+
+  # Persists accumulated usage after the response (an after_action).
+  # `->(controller:)`. MUST never affect the MCP response. nil = no flush.
+  #
+  # @return [#call, nil]
+  attr_accessor :usage_flusher
+
+  # Builds the opaque payload bound to a session on `initialize`. `->(principal:)`
+  # returning a Hash (or nil for none). Lets a host bind e.g.
+  # `{ token_id: principal.id }` so a revoked token can kill an in-flight session,
+  # WITHOUT overriding the controller's `mcp_session_data`. nil (the default) =>
+  # an empty session payload.
+  #
+  # @return [#call, nil]
+  attr_accessor :session_data_builder
+
+  # The host's tool catalog — the api-agnostic seam. Duck-typed; the dispatcher
+  # calls:
+  #
+  #   provider.tool_definitions(context) -> [{ name:, description:, inputSchema: }]
+  #   provider.find(name)                -> a tool object, or nil
+  #
+  # 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.
+  #
+  # 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 ---------------------------------------------------
+
+  # A prefix prepended to the four GENERIC, Registry-backed authority tool names
+  # (`resources`, `resource_schema`, `get`, `list`) served by
+  # McpToolkit::Authority::RegistryToolProvider. Lets a host NAMESPACE its generic
+  # tools — e.g. set `"foo_"` and they advertise (and resolve) as `foo_resources`,
+  # `foo_resource_schema`, `foo_get`, `foo_list` — so distinct MCP surfaces don't
+  # collide and existing clients keep a stable, host-chosen name. Empty by default,
+  # so the tools keep their bare base names. The prefix value is the host's; the gem
+  # names no app concept.
+  #
+  # @return [String]
+  attr_accessor :generic_tool_name_prefix
+
+  # --- diagnostics -----------------------------------------------------------
+
+  # Optional logger for gateway/session diagnostics. All call sites guard with
+  # `logger&.warn` / `logger&.error`, so nil (the default) silences them. A Rails
+  # host typically sets this to `Rails.logger`.
+  #
+  # @return [#warn, #error, nil]
+  attr_accessor :logger
+
   # Vendor-neutral defaults; apps override the auth wiring + identity as needed.
   def initialize
     @server_name = "mcp-server"
     @server_version = "1.0.0"
     @server_instructions = nil
 
+    @gateway_client_name = nil
+    @gateway_client_version = nil
+
     @serializer_base = nil # set lazily in #serializer_base to avoid load-order issues
 
     @auth_role = :satellite
@@ -169,16 +435,107 @@ 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
     @parent_controller = "ActionController::Base"
     @account_meta_key = "mcp-toolkit/account-id"
     @account_id_header = "X-MCP-Account-ID"
 
+    initialize_authority_hook_defaults
+    @generic_tool_name_prefix = ""
+
+    @upstream_timeout = 10
+    @upstream_list_ttl = 900 # 15 minutes
+    @logger = nil
+
     @registry = McpToolkit::Registry.new
+    @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).
+  def initialize_authority_hook_defaults
+    @rate_limiter = nil
+    @usage_recorder = nil
+    @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?
+  end
+
+  # Config sugar: register a gateway upstream. Delegates to `upstreams.register`,
+  # so a blank url is ignored (an unconfigured upstream is simply absent). Pass
+  # `public_tool_list: false` for an upstream whose tool list varies by caller
+  # privilege, to opt it out of the shared list cache.
+  #
+  #   c.register_upstream(key: "notifications", url: ENV["NOTIFICATIONS_SERVER_URL"])
+  def register_upstream(key:, url:, public_tool_list: true)
+    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.
+  def gateway_client_name
+    @gateway_client_name || server_name
+  end
+
+  # The gateway handshake client version, defaulting to the server version.
+  def gateway_client_version
+    @gateway_client_version || server_version
   end
 
   # The serializer base, lazily defaulting to the gem's bundled DSL base. Lazy so

data/lib/mcp_toolkit/dispatcher.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+# Hand-rolled JSON-RPC dispatcher for the AUTHORITY + gateway path: it handles a
+# single JSON-RPC request (one element of a batch), serving the host's own tools
+# and, as a gateway, aggregating + proxying upstream MCP servers — WITHOUT the
+# official `mcp` SDK in the request path.
+#
+# The gem carries two dispatch front-ends by design (see McpToolkit::Protocol):
+# this Dispatcher for the authority/gateway endpoint, and McpToolkit::Server.build
+# (the SDK wrapper) for satellites. They are independent; nothing here touches the
+# satellite path.
+#
+# Everything host-specific is injected:
+#   * `context`  — an McpToolkit::Authority::Context (the resolved account, the
+#                  authenticated principal, and the bearer token to forward
+#                  upstream). Re-created PER JSON-RPC request by the transport, so
+#                  each batch element carries its own account.
+#   * `config`   — server identity (`server_name`/`server_version`), the
+#                  negotiable protocol versions, the registered `upstreams`, and
+#                  the `tool_provider` (the host's api-agnostic tool catalog).
+#
+# The wire behavior — top-level JSON-RPC tool-error codes, `initialize`
+# capabilities `{ tools: { listChanged: true } }`, 3-version negotiation, verbatim
+# upstream error relay, and the custom `notifications/<app>/tools/list_changed`
+# cache-bust — is the byte contract of a first-party endpoint and is preserved
+# exactly.
+class McpToolkit::Dispatcher
+  attr_reader :context, :config
+
+  def initialize(context:, config: McpToolkit.config)
+    @context = context
+    @config = config
+  end
+
+  def handle_request(request)
+    dispatch_request(request)
+  rescue McpToolkit::Protocol::Error => e
+    return nil unless request.key?("id")
+
+    McpToolkit::Protocol.error_response(id: request["id"], error: e)
+  rescue StandardError => e
+    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("Internal error")
+    )
+  end
+
+  private
+
+  # Happy path; raises here are turned into JSON-RPC errors by handle_request.
+  def dispatch_request(request)
+    validate_request!(request)
+
+    result = dispatch_method(request["method"], request["params"] || {})
+
+    # JSON-RPC 2.0: notifications (requests without `id`) MUST NOT receive a response.
+    return nil unless request.key?("id")
+
+    McpToolkit::Protocol.success_response(id: request["id"], result:)
+  end
+
+  def validate_request!(request)
+    unless request["jsonrpc"] == McpToolkit::Protocol::JSONRPC_VERSION
+      raise McpToolkit::Protocol::InvalidRequest, "Missing jsonrpc version"
+    end
+    raise McpToolkit::Protocol::InvalidRequest, "Missing method" if request["method"].blank?
+  end
+
+  def dispatch_method(method, params)
+    case method
+    when "initialize"
+      handle_initialize(params)
+    when "initialized", "notifications/initialized"
+      handle_initialized
+    when "tools/list"
+      handle_tools_list
+    when "tools/call"
+      handle_tools_call(params)
+    when "ping"
+      handle_ping
+    else
+      return handle_upstream_list_changed(method) if upstream_list_changed_notification?(method)
+
+      raise McpToolkit::Protocol::MethodNotFound, method
+    end
+  end
+
+  # Satellites can tell the authority their tool list changed via a
+  # `notifications/<app>/tools/list_changed` notification, busting that upstream's
+  # cached aggregate. Matches the configured upstream keys only.
+  def upstream_list_changed_notification?(method)
+    upstream_key_from_notification(method).present?
+  end
+
+  def handle_upstream_list_changed(method)
+    McpToolkit::Gateway::Aggregator.new(config:).flush!(upstream_key_from_notification(method))
+    {}
+  end
+
+  def upstream_key_from_notification(method)
+    match = method.to_s.match(%r{\Anotifications/(?<key>.+)/tools/list_changed\z})
+    return nil unless match
+
+    config.upstreams.find(match[:key]) ? match[:key] : nil
+  end
+
+  def handle_initialize(params)
+    requested = params["protocolVersion"].to_s
+    versions = config.supported_protocol_versions
+    negotiated = versions.include?(requested) ? requested : versions.first
+
+    result = {
+      protocolVersion: negotiated,
+      capabilities: {
+        # listChanged: true — the aggregated list includes upstream tools, which
+        # can change when an upstream is reconfigured or sends a list_changed
+        # notification that busts the cached aggregate.
+        tools: { listChanged: true }
+      },
+      serverInfo: {
+        name: config.server_name,
+        version: config.server_version
+      }
+    }
+
+    # `instructions` is advertised on initialize only when configured, matching the
+    # SDK-backed satellite server (McpToolkit::Server.build) and the documented
+    # contract. Omitted when nil to keep the envelope clean.
+    result[:instructions] = config.server_instructions if config.server_instructions
+    result
+  end
+
+  def handle_initialized
+    {}
+  end
+
+  def handle_ping
+    {}
+  end
+
+  def handle_tools_list
+    {
+      tools: host_tool_definitions +
+        McpToolkit::Gateway::Aggregator.new(config:).tool_definitions(bearer_token: context.bearer_token)
+    }
+  end
+
+  # The host's own tool definitions, sourced from the injected tool_provider (the
+  # api-agnostic seam). `context` lets the provider hide superuser-only tools from
+  # a non-superuser caller. A host that registered no provider contributes none.
+  def host_tool_definitions
+    provider = config.tool_provider
+    return [] unless provider
+
+    provider.tool_definitions(context)
+  end
+
+  def handle_tools_call(params)
+    tool_name = params["name"]
+    arguments = params["arguments"] || {}
+
+    upstream = config.upstreams.split_tool_name(tool_name)
+    return handle_upstream_tools_call(upstream, arguments) if upstream
+
+    handle_host_tools_call(tool_name, arguments)
+  end
+
+  def handle_host_tools_call(tool_name, arguments)
+    tool = config.tool_provider&.find(tool_name)
+    raise McpToolkit::Protocol::MethodNotFound, "Tool not found: #{tool_name}" unless tool
+
+    ensure_tool_scope!(tool)
+
+    result = tool.call(context:, **symbolized_arguments(arguments))
+
+    {
+      content: [
+        {
+          type: "text",
+          text: result.is_a?(String) ? result : result.to_json
+        }
+      ]
+    }
+  end
+
+  # 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.except(:context)
+  end
+
+  def ensure_tool_scope!(tool)
+    required_scope = tool.required_permissions_scope
+    return if required_scope.blank?
+    return if context.principal&.authorized_for_scope?(required_scope)
+
+    raise McpToolkit::Protocol::InvalidRequest, "This token lacks the #{required_scope.inspect} scope"
+  end
+
+  def handle_upstream_tools_call((app_key, bare_tool_name), arguments)
+    McpToolkit::Gateway::Proxy.new(
+      app_key:,
+      tool_name: bare_tool_name,
+      account_id: context.account&.id,
+      bearer_token: context.bearer_token,
+      config:
+    ).call(arguments)
+  rescue McpToolkit::Gateway::UnknownUpstream => e
+    # The gateway stays transport-agnostic; the dispatcher maps an unknown
+    # upstream to its own "method not found".
+    raise McpToolkit::Protocol::MethodNotFound, e.message
+  rescue McpToolkit::Gateway::UpstreamCallError => e
+    raise translate_upstream_call_error(e)
+  end
+
+  # Translates the gateway's transport-agnostic upstream failure into the JSON-RPC
+  # error shape — verbatim relay of a satellite JSON-RPC error, else a generic
+  # internal error.
+  def translate_upstream_call_error(error)
+    if error.jsonrpc_error
+      McpToolkit::Protocol::Error.new(
+        error.jsonrpc_error["message"].to_s,
+        code: error.jsonrpc_error["code"] || McpToolkit::Protocol::ErrorCodes::INTERNAL_ERROR,
+        data: error.jsonrpc_error["data"]
+      )
+    else
+      # 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