mcp_toolkit 0.3.0

data/lib/mcp_toolkit/auth/authenticator.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+# SATELLITE side. Resolves the authenticated, scoped context for a tool call:
+#
+#   1. Introspect the bearer token against the central app (cached).
+#   2. Reject if invalid / expired.
+#   3. Resolve the active central account id, enforcing tenancy:
+#        - accounts_user token  => its single bound `account_id`. A supplied
+#          selector, if present, MUST match it.
+#        - user (superuser) token => the selector is REQUIRED and MUST be one of
+#          the token's `account_ids`.
+#   4. Map that central account id to the LOCAL scope root via
+#      `config.account_resolver` (e.g. Account.find_by(synced_id:)) and return
+#      it as the tools' `scope_root`.
+#
+# The required scope (explicitly declared per resource via
+# `required_permissions_scope`, or the registry default) is enforced separately
+# by Tools::Base (#with_account / #with_authentication) via
+# `authorized_for_scope?`; the authenticator only validates the token and
+# resolves the tenant.
+#
+# The account selector mirrors what a gateway forwards: the resolved account id
+# arrives as `_meta[config.account_meta_key]`. We also accept an `account_id`
+# tool argument and the `config.account_id_header` header as fallbacks.
+class McpToolkit::Auth::Authenticator
+  Context = Struct.new(:scope_root, :introspection, keyword_init: true)
+
+  # @param token [String] the plaintext bearer the central app forwarded
+  # @param meta [Hash] the JSON-RPC `_meta` (string or symbol keys)
+  # @param arguments [Hash] the tool-call arguments (may carry `account_id`)
+  # @param header_account_id [Integer,String,nil] the account-id header value
+  # @param config [McpToolkit::Configuration]
+  def self.call(token:, meta: {}, arguments: {}, header_account_id: nil, config: McpToolkit.config)
+    new(token:, meta:, arguments:, header_account_id:, config:).call
+  end
+
+  def initialize(token:, meta:, arguments:, header_account_id:, config: McpToolkit.config)
+    @token = token
+    @meta = (meta || {}).transform_keys(&:to_s)
+    @arguments = (arguments || {}).transform_keys(&:to_s)
+    @header_account_id = header_account_id
+    @config = config
+  end
+
+  def call
+    introspection = McpToolkit::Auth::Introspection.call(token, config:)
+    raise McpToolkit::Errors::Unauthorized, "invalid or expired token" unless introspection.valid?
+
+    central_account_id = resolve_account_id(introspection)
+    scope_root = config.account_resolver.call(central_account_id)
+    unless scope_root
+      raise McpToolkit::Errors::Unauthorized, "no local scope found for account_id=#{central_account_id}"
+    end
+
+    Context.new(scope_root:, introspection:)
+  end
+
+  private
+
+  attr_reader :token, :meta, :arguments, :header_account_id, :config
+
+  def resolve_account_id(introspection)
+    candidate = candidate_account_id
+
+    if introspection.accounts_user?
+      bound = introspection.account_id
+      # Compare as STRINGS: ids may be numeric or string/UUID, and to_i would
+      # collapse every non-numeric id to 0 (letting "acct_B" match "acct_A").
+      if candidate.present? && candidate.to_s != bound.to_s
+        raise McpToolkit::Errors::Unauthorized,
+              "account_id #{candidate} does not match this token's bound account"
+      end
+
+      return bound.to_s
+    end
+
+    # superuser / multi-account: selection is mandatory and must be authorized.
+    if candidate.blank?
+      raise McpToolkit::Errors::Unauthorized,
+            "this token spans multiple accounts; an account must be selected " \
+            "via _meta[\"#{config.account_meta_key}\"] (or the account_id argument)"
+    end
+
+    # String-normalized membership (see accounts_user branch): `candidate` may be
+    # an Integer (forwarded `_meta` JSON number) or a String (header/arg); to_s
+    # normalizes both and authorized_account_ids is likewise string-normalized.
+    unless introspection.authorized_account_ids.include?(candidate.to_s)
+      raise McpToolkit::Errors::Unauthorized, "account_id #{candidate} is not authorized for this token"
+    end
+
+    candidate.to_s
+  end
+
+  def candidate_account_id
+    meta[config.account_meta_key].presence ||
+      arguments["account_id"].presence ||
+      header_account_id.presence
+  end
+end

data/lib/mcp_toolkit/auth/authority.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# AUTHORITY side. The helpers the central app uses to (a) authenticate a
+# plaintext bearer token against its local token store and (b) answer the
+# introspection request satellites send.
+#
+# Both are thin and config-driven: the actual token lookup is the app's
+# `config.token_authenticator` callable (its `McpToken.authenticate`
+# equivalent), and the introspection payload is derived from the duck-typed
+# token object that callable returns.
+#
+# ## Token object contract
+#
+# `config.token_authenticator.call(plaintext)` must return nil (no/invalid
+# token) or an object responding to:
+#
+#   #kind            -> :accounts_user | :user (or string equivalents)
+#   #account_id      -> the single bound account id for an accounts_user token,
+#                       else nil
+#   #account_ids     -> Array of authorized account ids
+#   #expires_at      -> a Time/DateTime responding to #iso8601, or nil
+#   #scopes          -> Array of OAuth-style `<app>__<action>` scopes ([] = no scopes).
+#                       The sole authorization source on the satellite side.
+#
+# Optionally `#touch_last_used!` (called after a successful authenticate if
+# present). A typical app token model (e.g. `McpToken`) satisfies this.
+module McpToolkit::Auth::Authority
+  # Authenticate a plaintext bearer locally. Returns the token object or nil.
+  # Calls `touch_last_used!` on the token if it responds to it (throttled
+  # last-used tracking is the token model's concern, not ours).
+  def self.authenticate(plaintext, config: McpToolkit.config)
+    authenticator = config.token_authenticator
+    if authenticator.nil?
+      raise McpToolkit::Errors::ConfigurationError,
+            "token_authenticator is not configured; required for the :authority role"
+    end
+
+    token = authenticator.call(plaintext)
+    return nil unless token
+
+    token.touch_last_used! if token.respond_to?(:touch_last_used!)
+    token
+  end
+
+  # Build the introspection response payload for a token object. This is the
+  # JSON the authority's `/mcp/tokens/introspect` endpoint renders, and the
+  # exact contract Auth::Introspection (the satellite) parses.
+  #
+  # @param token [#kind, #account_id, #account_ids, #expires_at, #scopes]
+  # @return [Hash]
+  def self.introspection_payload(token)
+    account_ids = Array(token.account_ids)
+    {
+      valid: true,
+      kind: token.kind.to_s,
+      account_id: account_id_for(token, account_ids),
+      account_ids:,
+      expires_at: token.expires_at&.iso8601,
+      scopes: Array(token.scopes)
+    }
+  end
+
+  # The payload returned for a missing/invalid token. Render with HTTP 401.
+  def self.invalid_payload
+    { valid: false }
+  end
+
+  # account_id is the single bound account for an accounts_user token, else nil
+  # (a superuser/multi-account token advertises its set via account_ids).
+  def self.account_id_for(token, account_ids)
+    return token.account_id unless token.account_id.nil?
+
+    token.kind.to_s == McpToolkit::TokenKinds::ACCOUNTS_USER ? account_ids.first : nil
+  end
+end

data/lib/mcp_toolkit/auth/authority_server_client.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+# SATELLITE side. The HTTP client that talks to the central authority's
+# introspection endpoint. Owns the Faraday connection (timeouts, JSON parsing,
+# adapter) and the POST itself, so Auth::Introspection is left with the caching
+# and result-parsing concerns only.
+#
+#   POST {config.introspect_url}
+#   Authorization: Bearer <token>
+#   Accept: application/json
+#
+# Returns the raw response body on a 200, or nil otherwise (a non-200 status or a
+# transport-level Faraday error). Auth::Introspection turns that into an
+# Introspection::Result.
+class McpToolkit::Auth::AuthorityServerClient
+  def initialize(config)
+    @config = config
+  end
+
+  # POSTs the token to the authority's introspection endpoint. Returns the
+  # response body on a 200; nil on any non-200 status or transport failure.
+  def introspect(token)
+    response = connection.post(config.introspect_url) do |request|
+      request.headers["Authorization"] = "Bearer #{token}"
+      request.headers["Accept"] = "application/json"
+    end
+
+    return nil unless response.status == 200
+
+    response.body
+  rescue Faraday::Error
+    nil
+  end
+
+  private
+
+  attr_reader :config
+
+  def connection
+    timeout = config.introspection_timeout
+    Faraday.new do |conn|
+      conn.options.timeout = timeout
+      conn.options.open_timeout = timeout
+      conn.response :json, content_type: /\bjson$/
+      conn.adapter Faraday.default_adapter
+    end
+  end
+end

data/lib/mcp_toolkit/auth/introspection.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+# SATELLITE side. Authenticates the bearer token the central app forwards by
+# calling the central app's introspection endpoint, with a short-TTL cache so a
+# burst of tool calls in one session does not hammer the central app.
+#
+#   POST {central_app_url}{introspect_path}
+#   Authorization: Bearer <token>
+#
+# Response contract (the AUTHORITY emits this; see Auth::Authority):
+#   { valid: bool,
+#     kind: <one of McpToolkit::TokenKinds — accounts-user or superuser>,
+#     account_id: <id|null>,
+#     account_ids: [...],
+#     expires_at: <iso8601|null>,
+#     scopes: [...] }   # OAuth-style `<app>__<action>` scopes a token carries
+#
+# Authorization is purely scope-based: a token reaches a tool when it carries the
+# scope that tool explicitly requires (declared per resource via
+# `required_permissions_scope`, or the registry default; enforced in
+# Tools::Base#with_account / #with_authentication via `authorized_for_scope?`).
+#
+# The cache is keyed on a SHA-256 of the token (never the plaintext) so cached
+# entries can't be reversed back to a usable credential from cache storage. The
+# HTTP call itself is delegated to Auth::AuthorityServerClient.
+class McpToolkit::Auth::Introspection
+  CACHE_PREFIX = "mcp_toolkit:introspection:"
+
+  Result = Struct.new(
+    :valid, :kind, :account_id, :account_ids, :expires_at, :scopes, keyword_init: true
+  ) do
+    # Locally enforce the authority's `expires_at` (defense-in-depth): a token is
+    # only valid when the authority said so AND it has not lapsed. Without this,
+    # validity would rest solely on the authority's `valid: true` boolean, so a
+    # stale `valid: true` (e.g. a clock-skewed or buggy authority, or a cached
+    # Result) with a past `expires_at` would be accepted indefinitely.
+    def valid?
+      valid == true && !expired?
+    end
+
+    # True when `expires_at` is present and now is at/after it. Blank/nil means
+    # the token has no expiry (=> not expired). An UNPARSEABLE `expires_at` is
+    # treated as expired (fail-closed) rather than silently accepted. Kept public
+    # for clarity/testability.
+    def expired?
+      raw = expires_at
+      return false if raw.nil? || raw.to_s.strip.empty?
+
+      expiry = parse_expiry(raw)
+      return true if expiry.nil? # unparseable => fail closed
+
+      expiry <= Time.now
+    end
+
+    private
+
+    def parse_expiry(raw)
+      return raw if raw.is_a?(Time)
+
+      Time.iso8601(raw.to_s)
+    rescue ArgumentError, TypeError
+      begin
+        Time.parse(raw.to_s)
+      rescue ArgumentError, TypeError
+        nil
+      end
+    end
+
+    public
+
+    def accounts_user?
+      kind.to_s == McpToolkit::TokenKinds::ACCOUNTS_USER
+    end
+
+    def superuser?
+      kind.to_s == McpToolkit::TokenKinds::USER
+    end
+
+    # True when the token carries the EXACT `required_scope` (e.g.
+    # `notifications__read`). An empty required scope passes (a tool that
+    # requires no scope is reachable by any valid token). A non-empty required
+    # scope must be present in the token's `scopes`; empty token scopes are
+    # therefore unrestricted ONLY for tools that require no scope.
+    def authorized_for_scope?(required_scope)
+      return true if required_scope.to_s.empty?
+
+      scope_list = Array(scopes).map(&:to_s)
+      scope_list.include?(required_scope.to_s)
+    end
+
+    # Account ids are STRING-normalized for comparison: the contract allows
+    # integer OR string/UUID ids, so coercing to_i would collapse every
+    # non-numeric id to 0 and let unrelated accounts match. Strings compare
+    # safely and the resolver's `find_by(synced_id:)` coerces back per-column.
+    def authorized_account_ids
+      Array(account_ids).map(&:to_s)
+    end
+  end
+
+  INVALID = Result.new(valid: false).freeze
+
+  # Returns an Introspection::Result. Invalid/expired/unreachable => a result
+  # whose `valid?` is false. Caches positive AND negative results briefly.
+  def self.call(token, config: McpToolkit.config)
+    new(token, config:).call
+  end
+
+  def initialize(token, config: McpToolkit.config)
+    @token = token
+    @config = config
+  end
+
+  def call
+    return INVALID if token.to_s.empty?
+
+    cached = cache.read(cache_key)
+    return cached if cached
+
+    result = fetch
+    cache.write(cache_key, result, expires_in: config.introspection_cache_ttl)
+    result
+  end
+
+  private
+
+  attr_reader :token, :config
+
+  def fetch
+    body = authority_server_client.introspect(token)
+    return INVALID if body.nil?
+
+    parse(body)
+  end
+
+  def parse(body)
+    payload = body.is_a?(Hash) ? body : JSON.parse(body)
+    return INVALID unless payload["valid"] == true
+
+    Result.new(
+      valid: true,
+      kind: payload["kind"],
+      account_id: payload["account_id"],
+      account_ids: payload["account_ids"],
+      expires_at: payload["expires_at"],
+      scopes: payload["scopes"]
+    )
+  rescue JSON::ParserError
+    INVALID
+  end
+
+  def authority_server_client
+    McpToolkit::Auth::AuthorityServerClient.new(config)
+  end
+
+  def cache
+    config.cache_store
+  end
+
+  def cache_key
+    "#{CACHE_PREFIX}#{Digest::SHA256.hexdigest(token)}"
+  end
+end

data/lib/mcp_toolkit/configuration.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+# The single, injectable configuration object for an app's MCP server.
+#
+# Generic but OPINIONATED: every setting has a sensible, vendor-neutral default,
+# so a satellite needs to override only a handful of values. The two things an
+# app almost always sets are
+# `server_name` and the auth wiring (`central_app_url` for a satellite, or
+# `token_authenticator` for the authority).
+#
+# Whether ANY scope is required is decided PER TOOL, not per app: a resource
+# declares `required_permissions_scope "notifications__read"` (or the registry
+# declares `default_required_permissions_scope` once for all resources). There is
+# no app-wide permission setting here.
+#
+# Accessed through `McpToolkit.config` (or `MCPToolkit.config`) and mutated in a
+# `McpToolkit.configure { |c| ... }` block.
+class McpToolkit::Configuration
+  # --- server identity -------------------------------------------------------
+
+  # @return [String] the MCP server name advertised in `initialize`.
+  attr_accessor :server_name
+  # @return [String] the MCP server version advertised in `initialize`.
+  attr_accessor :server_version
+  # @return [String, nil] human-readable `instructions` returned on `initialize`.
+  attr_accessor :server_instructions
+
+  # --- serialization ---------------------------------------------------------
+
+  # The DEFAULT serializer base class. A `Resource` registration that does not
+  # supply its own `serializer` inherits nothing here — serializers are picked
+  # per-resource — but this is the class the gem ships and documents as the base
+  # to subclass. Apps that want their own existing serializers simply register
+  # resources with those classes instead; the gem only requires that a serializer
+  # responds to `serialize_one` / `serialize_collection` (see
+  # McpToolkit::Serializer::Base for the contract).
+  #
+  # @return [Class]
+  # The reader is defined below as a lazily-defaulting method; only the writer
+  # comes from here.
+  attr_writer :serializer_base
+
+  # --- auth: role ------------------------------------------------------------
+
+  # @return [Symbol] :satellite (introspect tokens against a central app) or
+  #   :authority (be the introspection provider + authenticate local tokens).
+  #   A single app MAY be both — set :authority and still configure a
+  #   `central_app_url` if it also exposes its own tools as a satellite.
+  attr_accessor :auth_role
+
+  # --- auth: satellite side --------------------------------------------------
+
+  # @return [String, nil] base URL of the central auth app.
+  #   The satellite POSTs `<central_app_url>/mcp/tokens/introspect`.
+  attr_accessor :central_app_url
+  # @return [String, nil] the introspect path appended to `central_app_url`.
+  attr_accessor :introspect_path
+  # @return [Integer] seconds to cache an introspection result (positive AND
+  #   negative) so a burst of tool calls does not hammer the central app.
+  attr_accessor :introspection_cache_ttl
+  # @return [Integer] HTTP open/read timeout for the introspection call.
+  attr_accessor :introspection_timeout
+
+  # Resolves the central account id to the satellite's LOCAL scope root.
+  #
+  # A satellite stores rows keyed by the central app's account id (synced via
+  # Kafka etc.). This callable receives the resolved central `account_id` and
+  # MUST return the object that `Resource#scope` blocks root on (typically the
+  # local `Account`). Return nil to signal "no local account" (=> Unauthorized).
+  #
+  #   c.account_resolver = ->(synced_account_id) { Account.find_by(synced_id: synced_account_id) }
+  #
+  # Defaults to the identity function: the resolved central account id is used
+  # directly as the scope root (suitable for an app whose scope blocks key on the
+  # central id, or for the authority itself).
+  #
+  # @return [#call]
+  attr_accessor :account_resolver
+
+  # --- auth: authority side --------------------------------------------------
+
+  # 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
+  # role; unused by a pure satellite.
+  #
+  #   c.token_authenticator = ->(plaintext) { McpToken.authenticate(plaintext) }
+  #
+  # The returned token object must respond to the methods
+  # `McpToolkit::Auth::Authority#introspection_payload` reads (see that module for
+  # the contract): `kind`, `account_id`, `account_ids`, `expires_at`, `scopes`. A
+  # `touch_last_used!` method, if present, is called.
+  #
+  # @return [#call, nil]
+  attr_accessor :token_authenticator
+
+  # --- caching ---------------------------------------------------------------
+
+  # The cache store backing sessions and introspection results. Must satisfy the
+  # ActiveSupport::Cache::Store contract (`read`/`write`/`delete` with
+  # `expires_in:`). Defaults to an in-process MemoryStore; a real deployment
+  # should set this to `Rails.cache` (or any shared store) so sessions survive
+  # across Puma workers.
+  #
+  # @return [ActiveSupport::Cache::Store, #read]
+  attr_accessor :cache_store
+
+  # @return [Integer] session sliding-TTL in seconds.
+  attr_accessor :session_ttl
+
+  # --- filtering -------------------------------------------------------------
+
+  # Escapes LIKE wildcards in `matches` / `does_not_match` filter values so they
+  # match literally. Must respond to `sanitize_sql_like(string)`. Defaults to the
+  # ActiveRecord-backed McpToolkit::SqlSanitizer; a non-Rails host (or a test) can
+  # inject its own.
+  #
+  # @return [#sanitize_sql_like]
+  attr_accessor :sql_sanitizer
+
+  # --- 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 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
+  # ActionController::Base (NOT ::API) — e.g. for a logstasher `helper_method`
+  # hook — by setting `c.parent_controller = "ApplicationController"`.
+  #
+  # @return [String]
+  attr_accessor :parent_controller
+
+  # Header / meta-key constants. Vendor-neutral defaults; an app on a specific
+  # central authority can rename them to match that authority's convention.
+  # These are the selectors a superuser/multi-account token uses to pin the
+  # active account.
+  #
+  # @return [String]
+  attr_accessor :account_meta_key
+  # @return [String]
+  attr_accessor :account_id_header
+
+  # The resource registry for this configuration. Each config carries its own so
+  # tests (and, in principle, multiple mounted servers) don't collide. The
+  # process-wide convenience `McpToolkit.registry` delegates to the active
+  # config's registry.
+  #
+  # @return [McpToolkit::Registry]
+  attr_accessor :registry
+
+  # 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
+
+    @serializer_base = nil # set lazily in #serializer_base to avoid load-order issues
+
+    @auth_role = :satellite
+    @central_app_url = nil
+    @introspect_path = "/mcp/tokens/introspect"
+    @introspection_cache_ttl = 45
+    @introspection_timeout = 10
+    @account_resolver = ->(synced_account_id) { synced_account_id }
+
+    @token_authenticator = nil
+
+    @cache_store = ActiveSupport::Cache::MemoryStore.new
+    @session_ttl = 3600 # 1 hour
+
+    @sql_sanitizer = McpToolkit::SqlSanitizer.new
+
+    @protocol_version = nil
+    @parent_controller = "ActionController::Base"
+    @account_meta_key = "mcp-toolkit/account-id"
+    @account_id_header = "X-MCP-Account-ID"
+
+    @registry = McpToolkit::Registry.new
+  end
+
+  # The serializer base, lazily defaulting to the gem's bundled DSL base. Lazy so
+  # `McpToolkit::Serializer::Base` is referenced after it has been required,
+  # regardless of file load order.
+  def serializer_base
+    @serializer_base ||= McpToolkit::Serializer::Base
+  end
+
+  # @return [Boolean] whether this app introspects tokens against a central app.
+  def satellite?
+    auth_role.to_sym == :satellite || central_app_url
+  end
+
+  # @return [Boolean] whether this app authenticates tokens locally / answers
+  #   introspection.
+  def authority?
+    auth_role.to_sym == :authority
+  end
+
+  # Full introspection URL the satellite POSTs to. Raises a clear error if the
+  # central URL was never configured.
+  def introspect_url
+    raise McpToolkit::Errors::ConfigurationError, "central_app_url is not configured" if central_app_url.to_s.empty?
+
+    "#{central_app_url.chomp("/")}#{introspect_path}"
+  end
+end

data/lib/mcp_toolkit/engine.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Mountable Rails engine that draws the four MCP transport routes (defined in the
+# engine's config/routes.rb so they survive Rails' route reloads) against the
+# gem-provided McpToolkit::ServerController. A satellite mounts it in one line:
+#
+#   # config/routes.rb
+#   mount McpToolkit::Engine => "/mcp"
+#
+# yielding exactly the endpoints a hand-rolled satellite declared:
+#
+#   POST   /mcp          -> create   (JSON-RPC requests/responses)
+#   GET    /mcp          -> stream   (405; no server-initiated SSE)
+#   DELETE /mcp          -> destroy  (terminate the session)
+#   GET    /mcp/health   -> health   (unauthenticated probe)
+#
+# Loaded ONLY when Rails::Engine is available (see lib/mcp_toolkit.rb); the gem's
+# non-Rails consumers and its own unit suite never reference it.
+class McpToolkit::Engine < Rails::Engine
+  isolate_namespace McpToolkit
+end

data/lib/mcp_toolkit/errors/base.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Tool-level errors raised by executors / auth and caught at the tool boundary,
+# where they are turned into an `isError: true` MCP tool result (NOT a JSON-RPC
+# protocol error). This matches how MCP clients (and a gateway relaying the
+# satellite's `result` verbatim) expect tool failures to surface: the call
+# succeeds at the protocol level, the result carries the error.
+#
+# Base class for that family; subclasses below narrow the cause.
+class McpToolkit::Errors::Base < StandardError; end

data/lib/mcp_toolkit/errors/configuration_error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# The toolkit was used before it was configured, or a required piece of
+# configuration is missing for the operation being attempted.
+class McpToolkit::Errors::ConfigurationError < McpToolkit::Errors::Base; end

data/lib/mcp_toolkit/errors/invalid_params.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# The arguments to a tool were invalid (missing id, unknown resource, bad
+# account selection, etc.).
+class McpToolkit::Errors::InvalidParams < McpToolkit::Errors::Base; end

data/lib/mcp_toolkit/errors/unauthorized.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# The caller is not authenticated / authorized (token invalid, expired, lacks
+# the required permissions scope, or no/invalid account context).
+class McpToolkit::Errors::Unauthorized < McpToolkit::Errors::Base; end