mcp_toolkit 0.3.0 → 0.4.0

data/lib/mcp_toolkit/authority/tools/base.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+# Shared base for the four GENERIC, Registry-backed authority tools
+# (McpToolkit::Authority::Tools::{Resources,ResourceSchema,Get,List}) served
+# through McpToolkit::Authority::RegistryToolProvider on the hand-rolled
+# authority dispatch path.
+#
+# Unlike the satellite tools (McpToolkit::Tools::*, which subclass the SDK's
+# MCP::Tool, self-authenticate, and return an MCP::Tool::Response), these are
+# plain objects satisfying the dispatcher's duck-typed tool contract:
+#
+#   tool.required_permissions_scope  -> nil   (see below — no STATIC scope)
+#   tool.call(context:, **arguments) -> Hash  (the dispatcher wraps it into
+#                                              { content: [{ type: "text", ... }] })
+#
+# The scope a caller needs is DYNAMIC — it depends on which `resource` argument
+# was passed — so these tools declare no static scope and instead enforce the
+# resolved resource's `required_scope_for` INSIDE #call (see #ensure_scope!).
+# The `context` (McpToolkit::Authority::Context) supplies the resolved account,
+# the principal, and the derived superuser flag.
+#
+# The tools reuse the existing executors / schema builder UNCHANGED; this base
+# only holds the resolution + gating every one of them repeats: resolve the
+# resource descriptor, gate a superuser-only resource, gate the per-resource
+# scope, and (for get/list) require a selected account.
+class McpToolkit::Authority::Tools::Base
+  class << self
+    attr_reader :_description, :_input_schema
+
+    def tool_name(name = nil)
+      @_tool_name = name.to_s if name
+      @_tool_name
+    end
+
+    def description(text = nil)
+      @_description = text if text
+      @_description
+    end
+
+    def input_schema(schema = nil)
+      @_input_schema = schema if schema
+      @_input_schema || { type: "object", properties: {} }
+    end
+
+    # The static tool definition returned by the provider's `tool_definitions`
+    # (part of `tools/list`). Generic and context-independent.
+    def definition
+      { name: tool_name, description: _description, inputSchema: input_schema }
+    end
+  end
+
+  attr_reader :config
+
+  def initialize(config:)
+    @config = config
+  end
+
+  # The dispatcher's central scope gate reads this; nil = no STATIC scope. The
+  # real, per-resource scope is enforced dynamically in #ensure_scope! (the scope
+  # depends on the `resource` argument, unknown until #call).
+  def required_permissions_scope
+    nil
+  end
+
+  private
+
+  def registry
+    config.registry
+  end
+
+  # Resolves the `resource` argument to a registered descriptor, raising the
+  # protocol InvalidParams (=> JSON-RPC -32602) for a blank or unknown name so the
+  # dispatcher renders a clean top-level error.
+  def resolve_descriptor(name)
+    raise McpToolkit::Protocol::InvalidParams, "resource is required" if name.to_s.strip.empty?
+
+    registry.fetch(name)
+  rescue McpToolkit::Registry::UnknownResource => e
+    raise McpToolkit::Protocol::InvalidParams, e.message
+  end
+
+  # Refuses a superuser-only resource for a non-superuser caller (get / list /
+  # resource_schema). `resources` HIDES such resources instead — see that tool.
+  def ensure_resource_accessible!(descriptor, context)
+    return unless descriptor.superusers_only?
+    return if context.superuser?
+
+    raise McpToolkit::Protocol::InvalidRequest,
+          "#{descriptor.name} is restricted to superuser (user-scoped) MCP tokens"
+  end
+
+  # Enforces the resource's effective required scope against the principal. Blank
+  # scope => no check. Mirrors the dispatcher's central gate error shape
+  # (InvalidRequest), keeping scope refusals byte-consistent across host tools.
+  def ensure_scope!(descriptor, context)
+    required = registry.required_scope_for(descriptor)
+    return if required.to_s.empty?
+    return if context.principal&.authorized_for_scope?(required)
+
+    raise McpToolkit::Protocol::InvalidRequest, "This token lacks the #{required.inspect} scope"
+  end
+
+  # get / list read tenant data, so they REQUIRE a resolved account: a superuser
+  # token that selected none would otherwise reach `scope.call(nil)` and leak
+  # across tenants. resource_schema / resources (shape only) do not call this.
+  def ensure_account!(context)
+    return if context.account
+
+    raise McpToolkit::Protocol::InvalidParams,
+          "an account must be selected (pass account_id) to read this resource"
+  end
+
+  # Runs an executor, translating a data-layer McpToolkit::Errors::InvalidParams
+  # (bad id, unknown filter/field key, ...) into the protocol InvalidParams the
+  # dispatcher renders as JSON-RPC -32602 (rather than letting it fall through to
+  # the dispatcher's generic -32603 internal-error mapping).
+  def run_executor
+    yield
+  rescue McpToolkit::Errors::InvalidParams => e
+    raise McpToolkit::Protocol::InvalidParams, e.message
+  end
+end

data/lib/mcp_toolkit/authority/tools/get.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Authority-path tool: fetch a single record by id from a registered resource,
+# scoped to the caller's resolved account. Gates a superuser-only resource, the
+# resource's required scope, and requires a selected account before reading.
+class McpToolkit::Authority::Tools::Get < McpToolkit::Authority::Tools::Base
+  tool_name "get"
+  description <<~DESC.strip
+    Fetch a single record by id from a read-only resource. Pass the resource name as `resource`
+    and the record id as `id`. Use the `resources` tool to discover available resources.
+
+    For tokens that span multiple accounts (superuser), pass `account_id` to pin the active
+    account; account-scoped tokens may omit it. The response mirrors the resource's record
+    shape (attributes + a `links` block).
+
+    Pass `fields` to return a sparse fieldset — the attributes and/or relationships you name
+    (as an array or comma-separated string), omitting everything else. Include "id" if you need
+    it. Valid names come from the resource's `resource_schema`; unknown names are rejected.
+  DESC
+
+  input_schema(
+    {
+      type: "object",
+      properties: {
+        resource: {
+          type: "string",
+          description: "Resource name (use the `resources` tool to discover valid values)"
+        },
+        # The id type is left open so a string/UUID primary key works as well as an
+        # integer one; the record is looked up by the value as given, uncoerced.
+        id: { type: %w[string integer], description: "The record ID (integer or string/UUID)" },
+        account_id: {
+          type: "integer",
+          description: "Account to operate on. Required for superuser tokens; ignored otherwise."
+        },
+        fields: {
+          type: %w[array string],
+          items: { type: "string" },
+          description: "Sparse fieldset — names of attributes and/or relationships to include, as " \
+                       "an array or a comma-separated string. Omit to return every field. Include " \
+                       "\"id\" if you need it. Unknown names are rejected."
+        }
+      },
+      required: %w[resource id]
+    }
+  )
+
+  def call(context:, resource: nil, id: nil, fields: nil, **_args)
+    descriptor = resolve_descriptor(resource)
+    ensure_resource_accessible!(descriptor, context)
+    ensure_scope!(descriptor, context)
+    ensure_account!(context)
+
+    run_executor do
+      McpToolkit::GetExecutor.call(resource: descriptor, scope_root: context.account, id:, fields:)
+    end
+  end
+end

data/lib/mcp_toolkit/authority/tools/list.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# Authority-path tool: fetch a paginated list of records from a registered
+# resource, scoped to the caller's resolved account. Gates a superuser-only
+# resource, the resource's required scope, and requires a selected account before
+# reading. Standard filters, per-attribute equality/operator filters, resource
+# custom filters, pagination, and sparse fieldsets are all handled by the reused
+# McpToolkit::ListExecutor.
+class McpToolkit::Authority::Tools::List < McpToolkit::Authority::Tools::Base
+  tool_name "list"
+  description <<~DESC.strip
+    Fetch a paginated list of records from a read-only resource. Pass the resource name as
+    `resource`. Use the `resources` tool to discover resources and `resource_schema` to learn a
+    resource's shape.
+
+    Standard filters:
+      - ids: comma-separated list of IDs to fetch
+      - updated_since: ISO 8601 timestamp; only records updated after this time
+      - limit: page size (default 25, max 100)
+      - offset: pagination offset (default 0)
+
+    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.
+
+    Sparse fieldset:
+      - fields: names of the attributes and/or relationships to include in each record, as an
+        array or a comma-separated string. Omit to return every field. Include "id" if you need
+        it. Valid names come from a resource's `resource_schema`; unknown names are rejected.
+
+    For tokens that span multiple accounts (superuser), pass `account_id` to pin the active
+    account; account-scoped tokens may omit it. The response shape is
+    { "<resource>": [...], "meta": { total_count, limit, offset } }.
+  DESC
+
+  input_schema(
+    {
+      type: "object",
+      properties: {
+        resource: {
+          type: "string",
+          description: "Resource name (use the `resources` tool to discover valid values)"
+        },
+        account_id: {
+          type: "integer",
+          description: "Account to operate on. Required for superuser tokens; ignored otherwise."
+        },
+        ids: { type: "string", description: "Comma-separated list of IDs to fetch" },
+        updated_since: {
+          type: "string",
+          description: "ISO 8601 timestamp; only records updated after this time"
+        },
+        filter: {
+          type: "object",
+          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)" },
+        offset: { type: "integer", description: "Pagination offset (default 0)" },
+        fields: {
+          type: %w[array string],
+          items: { type: "string" },
+          description: "Sparse fieldset — names of attributes and/or relationships to include in " \
+                       "each record, as an array or a comma-separated string. Omit to return every " \
+                       "field. Include \"id\" if you need it. Unknown names are rejected."
+        }
+      },
+      required: ["resource"]
+    }
+  )
+
+  def call(context:, resource: nil, **params)
+    descriptor = resolve_descriptor(resource)
+    ensure_resource_accessible!(descriptor, context)
+    ensure_scope!(descriptor, context)
+    ensure_account!(context)
+
+    run_executor do
+      McpToolkit::ListExecutor.call(resource: descriptor, scope_root: context.account, params:)
+    end
+  end
+end

data/lib/mcp_toolkit/authority/tools/resource_schema.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Authority-path discovery tool: the detailed schema (attributes with types +
+# filter operators, relationships, filters, note) of one registered resource.
+#
+# Reveals shape, not tenant data, so it does NOT require a selected account — but
+# it still gates a superuser-only resource (refuse) and the resource's required
+# scope, so a caller can't discover the shape of something it can't read.
+class McpToolkit::Authority::Tools::ResourceSchema < McpToolkit::Authority::Tools::Base
+  tool_name "resource_schema"
+  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`, 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
+    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
+
+  input_schema(
+    {
+      type: "object",
+      properties: {
+        resource: {
+          type: "string",
+          description: "Resource name (use the `resources` tool to discover valid values)"
+        }
+      },
+      required: ["resource"]
+    }
+  )
+
+  def call(context:, resource: nil, **_args)
+    descriptor = resolve_descriptor(resource)
+    ensure_resource_accessible!(descriptor, context)
+    ensure_scope!(descriptor, context)
+
+    McpToolkit::ResourceSchema.call(descriptor, registry:)
+  end
+end

data/lib/mcp_toolkit/authority/tools/resources.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Authority-path discovery tool: lists every read-only resource registered in the
+# config's Registry, HIDING superuser-only resources from a non-superuser caller
+# (so they are neither advertised nor discoverable without a superuser token).
+#
+# The top-level list is context-independent except for that visibility filter, so
+# the tool takes no arguments and does no per-resource scope check (per-resource
+# scopes are enforced by `get` / `list` / `resource_schema`).
+class McpToolkit::Authority::Tools::Resources < McpToolkit::Authority::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.
+  DESC
+
+  def call(context:, **_args)
+    {
+      resources: visible_resources(context).map do |resource|
+        { name: resource.name, description: resource.description }
+      end
+    }
+  end
+
+  private
+
+  # Superuser-only resources are hidden from a non-superuser caller.
+  def visible_resources(context)
+    registry.resources.reject { |resource| resource.superusers_only? && !context.superuser? }
+  end
+end

data/lib/mcp_toolkit/authority.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Namespace for the AUTHORITY-side building blocks: the per-request Context, the
+# transport concern (Authority::ControllerMethods), and the lazily-parented base
+# controller (Authority::ServerController).
+#
+# `ServerController` is NOT a file under this directory: like the engine's
+# controllers, it subclasses a host controller (`config.parent_controller`) that
+# is absent from the gem's own unit suite, so it cannot be a Zeitwerk-managed
+# file (eager-loading it would raise). It is built on demand by
+# `McpToolkit.build_engine_controllers!`, so this `const_missing` triggers that
+# build the first time `McpToolkit::Authority::ServerController` is referenced
+# (which, in a host, is after the app's initializers/to_prepare have run — so the
+# configured parent is read at build time, not at autoload time).
+module McpToolkit::Authority
+  def self.const_missing(name)
+    if name == :ServerController
+      McpToolkit.build_engine_controllers!
+      return const_get(name) if const_defined?(name, false)
+    end
+
+    super
+  end
+end

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
@@ -124,6 +175,14 @@ class McpToolkit::Configuration
   #   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 +210,111 @@ 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. nil = the host
+  # contributes no own tools (a pure gateway).
+  #
+  # @return [#tool_definitions, #find, nil]
+  attr_accessor :tool_provider
+
+  # --- 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
@@ -174,11 +332,56 @@ class McpToolkit::Configuration
     @sql_sanitizer = McpToolkit::SqlSanitizer.new
 
     @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
+
+  # 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
+    @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
+
+  # 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