RubyGems - mcp_toolkit - Versions diffs - 0.4.0 → 0.6.0 - Mend

mcp_toolkit 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (38) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +418 -0
data/README.md +174 -0
data/app/views/mcp_toolkit/oauth/authorize.html.erb +83 -0
data/config/routes.rb +22 -1
data/lib/mcp_toolkit/authority/controller_methods.rb +39 -0
data/lib/mcp_toolkit/authority/registry_tool_provider.rb +9 -10
data/lib/mcp_toolkit/authority/single_tool_provider.rb +25 -0
data/lib/mcp_toolkit/authority/tools/base.rb +31 -3
data/lib/mcp_toolkit/authority/tools/get.rb +2 -1
data/lib/mcp_toolkit/authority/tools/list.rb +49 -1
data/lib/mcp_toolkit/authority/tools/resource_schema.rb +10 -2
data/lib/mcp_toolkit/authority/tools/resources.rb +26 -4
data/lib/mcp_toolkit/configuration.rb +526 -7
data/lib/mcp_toolkit/dispatcher.rb +17 -3
data/lib/mcp_toolkit/engine.rb +20 -2
data/lib/mcp_toolkit/engine_controllers.rb +80 -5
data/lib/mcp_toolkit/filtering.rb +168 -23
data/lib/mcp_toolkit/gateway/aggregator.rb +25 -5
data/lib/mcp_toolkit/list_executor.rb +48 -4
data/lib/mcp_toolkit/oauth/controller_methods.rb +426 -0
data/lib/mcp_toolkit/oauth.rb +23 -0
data/lib/mcp_toolkit/resource.rb +55 -6
data/lib/mcp_toolkit/resource_schema.rb +125 -16
data/lib/mcp_toolkit/serializer/association_descriptor.rb +11 -0
data/lib/mcp_toolkit/serializer/target_ref.rb +7 -0
data/lib/mcp_toolkit/session.rb +2 -2
data/lib/mcp_toolkit/tool_reference_rewriter.rb +33 -0
data/lib/mcp_toolkit/tools/authority_base.rb +23 -2
data/lib/mcp_toolkit/tools/base.rb +23 -3
data/lib/mcp_toolkit/tools/get.rb +1 -1
data/lib/mcp_toolkit/tools/list.rb +27 -9
data/lib/mcp_toolkit/tools/resource_schema.rb +12 -3
data/lib/mcp_toolkit/tools/resources.rb +30 -7
data/lib/mcp_toolkit/usage_metering/recorder.rb +28 -2
data/lib/mcp_toolkit/version.rb +1 -1
data/lib/mcp_toolkit.rb +8 -2
metadata +8 -1

data/app/views/mcp_toolkit/oauth/authorize.html.erb ADDED Viewed

@@ -0,0 +1,83 @@
+<%#
+  The bridge's only human-facing surface: paste an access token you already hold.
+  Rendered with `layout: false`, so this is a whole document and carries its own
+  styles inline — it must not depend on the host's asset pipeline. A host that
+  wants its own branding defines app/views/mcp_toolkit/oauth/authorize.html.erb
+  in its own tree, which takes precedence over this one.
+  The authorization parameters ride through as hidden fields because the bridge
+  keeps no state between the two legs. They are re-validated on POST — the
+  redirect_uri against the allowlist — so a tampered field cannot widen anything.
+%>
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="robots" content="noindex, nofollow">
+    <title>Connect to <%= McpToolkit.config.server_name %></title>
+    <style>
+      :root { color-scheme: light dark; }
+      body {
+        margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center;
+        padding: 1.5rem; box-sizing: border-box;
+        font-family: system-ui, -apple-system, "Segoe UI", sans-serif; line-height: 1.5;
+        background: #f4f4f5; color: #18181b;
+      }
+      main { width: 100%; max-width: 26rem; background: #fff; border-radius: 0.75rem; padding: 2rem;
+             box-shadow: 0 1px 3px rgb(0 0 0 / 0.1), 0 8px 24px rgb(0 0 0 / 0.06); }
+      h1 { margin: 0 0 0.5rem; font-size: 1.25rem; }
+      p { margin: 0 0 1.5rem; color: #52525b; font-size: 0.9375rem; }
+      label { display: block; margin-bottom: 0.375rem; font-size: 0.875rem; font-weight: 600; }
+      input[type="password"] {
+        width: 100%; box-sizing: border-box; padding: 0.625rem 0.75rem; font-size: 1rem;
+        font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+        border: 1px solid #d4d4d8; border-radius: 0.375rem; background: #fff; color: inherit;
+      }
+      input[type="password"]:focus { outline: 2px solid #2563eb; outline-offset: 1px; border-color: #2563eb; }
+      button {
+        width: 100%; margin-top: 1.25rem; padding: 0.625rem 1rem; font-size: 0.9375rem; font-weight: 600;
+        color: #fff; background: #18181b; border: 0; border-radius: 0.375rem; cursor: pointer;
+      }
+      button:hover { background: #3f3f46; }
+      .error {
+        margin: 0 0 1.25rem; padding: 0.75rem; border-radius: 0.375rem; font-size: 0.875rem;
+        background: #fef2f2; border: 1px solid #fecaca; color: #991b1b;
+      }
+      @media (prefers-color-scheme: dark) {
+        body { background: #18181b; color: #fafafa; }
+        main { background: #27272a; box-shadow: none; border: 1px solid #3f3f46; }
+        p { color: #a1a1aa; }
+        input[type="password"] { background: #18181b; border-color: #52525b; }
+        button { background: #fafafa; color: #18181b; }
+        button:hover { background: #d4d4d8; }
+        .error { background: #450a0a; border-color: #7f1d1d; color: #fecaca; }
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>Connect to <%= McpToolkit.config.server_name %></h1>
+      <p>Paste your access token to finish connecting. It is not shown again after this step.</p>
+      <% if @mcp_oauth_error.present? %>
+        <div class="error" role="alert"><%= @mcp_oauth_error %></div>
+      <% end %>
+      <%= form_tag request.path, method: :post do %>
+        <%= hidden_field_tag :redirect_uri, params[:redirect_uri] %>
+        <%= hidden_field_tag :state, params[:state] %>
+        <%= hidden_field_tag :code_challenge, params[:code_challenge] %>
+        <%= hidden_field_tag :code_challenge_method, params[:code_challenge_method] %>
+        <label for="access_token">Access token</label>
+        <%= password_field_tag :access_token, nil, id: "access_token", autocomplete: "off",
+                               autocapitalize: "off", autocorrect: "off", spellcheck: false,
+                               autofocus: true, required: true %>
+        <button type="submit">Connect</button>
+      <% end %>
+    </main>
+  </body>
+</html>

data/config/routes.rb CHANGED Viewed

@@ -2,7 +2,7 @@
 # Engine routes, drawn through Rails' routes_reloader so they survive route
 # reloads (a class-body `routes.draw` is wiped when the app re-draws the engine's
-# route set on boot/reload). Mounted by a satellite via:
+# route set on boot/reload). Mounted by a satellite or an authority via:
 #
 #   mount McpToolkit::Engine => "/mcp"
 #
@@ -30,4 +30,25 @@ McpToolkit::Engine.routes.draw do
   # is true whenever `auth_role == :authority`). The controller also fails safe
   # (no `token_authenticator` => `{ valid: false }`), so this is defence in depth.
   post "tokens/introspect", to: "tokens#introspect" if McpToolkit.config.authority?
+  # The OAuth authorization bridge (McpToolkit::Oauth::ControllerMethods). Drawn
+  # only when the bridge is configured — `oauth_bridge?` is authority-only AND
+  # requires a redirect-uri allowlist — so a satellite, or any host that has not
+  # opted in, gets no such routes at all. Same reasoning as the introspection
+  # route above: the routes file is evaluated through the routes_reloader, after
+  # the host's initializers/to_prepare, so the config is already set.
+  #
+  # The two metadata documents are NOT here: a client looks for them at the origin
+  # root, which an engine mounted under a path cannot draw. The host draws them
+  # with `McpToolkit.draw_oauth_metadata_routes(self)`.
+  # `format: false` on each, as on the metadata routes the host draws: without it
+  # Rails' optional `(.:format)` segment matches, so `/mcp/oauth/authorize.json`
+  # reaches the action, finds no JSON template, and 500s — an unauthenticated
+  # error on a public endpoint, for a format the bridge never speaks.
+  if McpToolkit.config.oauth_bridge?
+    get "oauth/authorize", to: "oauth#authorize", format: false
+    post "oauth/authorize", to: "oauth#approve", format: false
+    post "oauth/token", to: "oauth#token", format: false
+    post "oauth/register", to: "oauth#register", format: false
+  end
 end

data/lib/mcp_toolkit/authority/controller_methods.rb CHANGED Viewed

@@ -247,12 +247,27 @@ module McpToolkit::Authority::ControllerMethods
   # ---- request handling -----------------------------------------------
   def mcp_handle_batch(requests)
+    mcp_enforce_batch_limit!(requests)
     responses = requests.filter_map { |req| mcp_process_single_request(req) }
     return head :accepted if responses.empty?
     mcp_render_response(responses)
   end
+  # Rejects an oversized JSON-RPC batch BEFORE any element runs. Rate limiting is
+  # a per-HTTP-request before_action, so without this an authenticated caller
+  # could fan out unbounded work (N tool executions / N blocking upstream calls)
+  # under a single rate-limit tick. Raised as a boundary Protocol::Error →
+  # rendered as a JSON-RPC error envelope (null id) by the rescue_from hook.
+  # `config.max_batch_size = nil` disables the cap.
+  def mcp_enforce_batch_limit!(requests)
+    max = mcp_config.max_batch_size
+    return if max.nil? || requests.size <= max
+    raise McpToolkit::Protocol::InvalidRequest,
+          "JSON-RPC batch too large: #{requests.size} requests exceeds the maximum of #{max}"
+  end
   def mcp_handle_single(request_data)
     response_data = mcp_process_single_request(request_data)
     return head :accepted if response_data.nil?
@@ -366,6 +381,7 @@ module McpToolkit::Authority::ControllerMethods
   # ---- error renders --------------------------------------------------
   def mcp_render_unauthorized(message)
+    mcp_set_authenticate_challenge
     render json: {
       jsonrpc: McpToolkit::Protocol::JSONRPC_VERSION,
       id: nil,
@@ -376,6 +392,29 @@ module McpToolkit::Authority::ControllerMethods
     }, status: :unauthorized
   end
+  # Points an unauthenticated caller at the OAuth bridge's protected-resource
+  # metadata (RFC 9728). This header is what a hosted MCP client waits for before
+  # it will start an authorization flow at all — without it, a 401 is just a
+  # failure. It also makes the metadata's location OURS to state rather than the
+  # client's to guess: RFC 9728 has the client fetch this URL directly, so the
+  # path-scoped location is found without probing the origin's bare well-known
+  # path. Emitted only when the bridge is configured, so a host that has not opted
+  # in keeps its 401 byte-identical.
+  #
+  # `request.base_url` honours `X-Forwarded-Host`, so it is caller-influenced and
+  # cannot be interpolated into a quoted-string parameter unescaped: a host
+  # carrying a `"` would close the quotes and let a caller append auth-params of
+  # their own. A URL has no business containing one, so refuse rather than escape
+  # — an origin that odd is a misconfiguration to notice, not to render.
+  def mcp_set_authenticate_challenge
+    return unless mcp_config.oauth_bridge?
+    metadata_url = "#{request.base_url}#{mcp_config.oauth_protected_resource_path}"
+    return if metadata_url.include?('"')
+    response.headers["WWW-Authenticate"] = %(Bearer resource_metadata="#{metadata_url}")
+  end
   def mcp_render_session_not_found
     render json: {
       jsonrpc: McpToolkit::Protocol::JSONRPC_VERSION,

data/lib/mcp_toolkit/authority/registry_tool_provider.rb CHANGED Viewed

@@ -20,11 +20,13 @@ class McpToolkit::Authority::RegistryToolProvider
   # actually advertised in `tools/list` and matched in `tools/call` is this base
   # name PREFIXED with `config.generic_tool_name_prefix` (empty by default, so the
   # bare base name), letting a host namespace its generic tools.
+  # Alphabetical by base name — the order tools/list advertises them in
+  # (matches the pre-gem contract adopting hosts' clients observed).
   TOOLS = {
-    "resources" => McpToolkit::Authority::Tools::Resources,
-    "resource_schema" => McpToolkit::Authority::Tools::ResourceSchema,
     "get" => McpToolkit::Authority::Tools::Get,
-    "list" => McpToolkit::Authority::Tools::List
+    "list" => McpToolkit::Authority::Tools::List,
+    "resource_schema" => McpToolkit::Authority::Tools::ResourceSchema,
+    "resources" => McpToolkit::Authority::Tools::Resources
   }.freeze
   def initialize(config:)
@@ -32,9 +34,11 @@ class McpToolkit::Authority::RegistryToolProvider
   end
   # The four static generic tool definitions (context-independent), each advertised
-  # under its PREFIXED name so `tools/list` shows the host's namespaced names.
+  # under its PREFIXED name so `tools/list` shows the host's namespaced names. The
+  # prefix is threaded into each definition so sibling-tool references in the
+  # description / input schema name the prefixed tools too (see Tools::Base.definition).
   def tool_definitions(_context)
-    TOOLS.map { |base_name, klass| klass.definition.merge(name: prefixed(base_name)) }
+    TOOLS.map { |_base_name, klass| klass.definition(name_prefix: prefix, config: @config) }
   end
   # A tool instance bound to this provider's config, or nil for an unknown name.
@@ -54,11 +58,6 @@ class McpToolkit::Authority::RegistryToolProvider
     @config.generic_tool_name_prefix.to_s
   end
-  # The advertised name for a base tool: the configured prefix followed by the base.
-  def prefixed(base_name)
-    "#{prefix}#{base_name}"
-  end
   # Recovers the base tool name from an advertised name by stripping the configured
   # prefix, or nil when the name does not carry the (non-empty) prefix.
   def base_name_for(name)

data/lib/mcp_toolkit/authority/single_tool_provider.rb ADDED Viewed

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+# A `tool_provider` serving exactly one bespoke authority tool alongside the
+# generic Registry-backed ones — the shape every host with a single custom tool
+# would otherwise hand-roll. Used automatically by the composed default
+# provider for bare tool classes in `config.extra_tool_providers`.
+#
+# The tool must expose `.definition` (the tools/list entry) and `.tool_name`,
+# and itself satisfy the dispatcher's tool contract (`required_permissions_scope`
+# + `call`) — e.g. a class built on McpToolkit::Tools::AuthorityBase. It is
+# advertised unconditionally; its scope/authorization gates are enforced at
+# call time (by the dispatcher and the tool itself).
+class McpToolkit::Authority::SingleToolProvider
+  def initialize(tool)
+    @tool = tool
+  end
+  def tool_definitions(_context)
+    [@tool.definition]
+  end
+  def find(name)
+    name.to_s == @tool.tool_name ? @tool : nil
+  end
+end

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

@@ -43,9 +43,26 @@ class McpToolkit::Authority::Tools::Base
     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 }
+    # (part of `tools/list`). Generic and context-independent. `name_prefix` is
+    # the host's `config.generic_tool_name_prefix`: it prefixes the advertised
+    # name AND is threaded through every sibling-tool reference in the
+    # description / input schema (see McpToolkit::ToolReferenceRewriter).
+    # `config` lets a tool adapt its prose to host configuration (see
+    # .description_text) — served docs must describe the behavior the host
+    # actually configured.
+    def definition(name_prefix: "", config: nil)
+      {
+        name: "#{name_prefix}#{tool_name}",
+        description: McpToolkit::ToolReferenceRewriter.rewrite(description_text(config), name_prefix),
+        inputSchema: McpToolkit::ToolReferenceRewriter.rewrite(input_schema, name_prefix)
+      }
+    end
+    # Hook for a tool whose description depends on host configuration
+    # (Tools::List swaps its bare-value grammar per
+    # config.bare_filter_value_semantics). Default: the static description.
+    def description_text(_config)
+      _description
     end
   end
@@ -119,4 +136,15 @@ class McpToolkit::Authority::Tools::Base
   rescue McpToolkit::Errors::InvalidParams => e
     raise McpToolkit::Protocol::InvalidParams, e.message
   end
+  # Rejects tool arguments outside the declared input schema (-32602) instead of
+  # silently ignoring them — a typo'd argument name should surface, not no-op.
+  # `list` deliberately does NOT use this: its extra top-level arguments are the
+  # resource-specific custom filters. (`account_id` is consumed by the
+  # transport's account resolution, so every tool tolerates it explicitly.)
+  def reject_unknown_arguments!(extra)
+    return if extra.empty?
+    raise McpToolkit::Protocol::InvalidParams, "unknown argument(s): #{extra.keys.join(", ")}"
+  end
 end

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

@@ -45,7 +45,8 @@ class McpToolkit::Authority::Tools::Get < McpToolkit::Authority::Tools::Base
     }
   )
-  def call(context:, resource: nil, id: nil, fields: nil, **_args)
+  def call(context:, resource: nil, id: nil, fields: nil, **extra)
+    reject_unknown_arguments!(extra.except(:account_id))
     descriptor = resolve_descriptor(resource)
     ensure_resource_accessible!(descriptor, context)
     ensure_scope!(descriptor, context)

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

@@ -7,6 +7,35 @@
 # custom filters, pagination, and sparse fieldsets are all handled by the reused
 # McpToolkit::ListExecutor.
 class McpToolkit::Authority::Tools::List < McpToolkit::Authority::Tools::Base
+  # The bare-value grammar bullet, per config.bare_filter_value_semantics: the
+  # served description must state the semantics the host ACTUALLY configured —
+  # advertising comma/"null" tokenization to clients of a :literal host would
+  # send them filters that silently match nothing. The :tokenized text is the
+  # exact bullet embedded in the static description below (spec-pinned), so
+  # .description_text can swap it by plain substring substitution; both use
+  # `<<-` (no dedent) to carry the description's rendered 2-space indentation.
+  BARE_VALUE_GRAMMAR = {
+    tokenized: <<-TEXT.rstrip,
+  - A bare value matches by equality. A comma-separated string or an array of scalars
+    matches ANY of the values (IN), e.g. { "status": "booked,canceled" } or
+    { "status": ["booked", "canceled"] }. The string "null" (or a JSON null) matches
+    records where the value is NULL.
+    TEXT
+    literal: <<-TEXT.rstrip
+  - A bare value matches by equality, LITERALLY: a comma-separated string is a single
+    value and the string "null" is the literal string. A JSON null matches records
+    where the value is NULL. An array of scalars matches ANY of its values (IN).
+    TEXT
+  }.freeze
+  # Swaps the bare-value bullet for the host's configured semantics; the rest
+  # of the description is mode-independent.
+  def self.description_text(config)
+    return _description unless config && config.bare_filter_value_semantics == :literal
+    _description.sub(BARE_VALUE_GRAMMAR[:tokenized], BARE_VALUE_GRAMMAR[:literal])
+  end
   tool_name "list"
   description <<~DESC.strip
     Fetch a paginated list of records from a read-only resource. Pass the resource name as
@@ -23,6 +52,22 @@ class McpToolkit::Authority::Tools::List < McpToolkit::Authority::Tools::Base
       - filter: an object of { <key>: <value> } filters, applied ON TOP of the account scope
         (they can only narrow, never widen). Each resource advertises its available filter keys
         and operators via `resource_schema`. Unknown keys are rejected.
+      - A bare value matches by equality. A comma-separated string or an array of scalars
+        matches ANY of the values (IN), e.g. { "status": "booked,canceled" } or
+        { "status": ["booked", "canceled"] }. The string "null" (or a JSON null) matches
+        records where the value is NULL.
+      - An operator condition is an object { "op": <operator>, "value": <value> }, e.g.
+        { "price": { "op": "gteq", "value": 100 } }. An array of conditions ANDs them into a
+        range: { "price": [{ "op": "gteq", "value": 100 }, { "op": "lt", "value": 200 }] }.
+        Each attribute's supported operators are listed in `resource_schema`.
+      - Some filter keys require a companion key (e.g. a polymorphic id and its type) —
+        `resource_schema` advertises these under a relationship's `filter.requires`; pass
+        both keys together.
+    Resource-specific filters:
+      - Some resources accept additional filters advertised in `resource_schema` under
+        `resource_filters`. Pass each as a TOP-LEVEL argument (NOT inside `filter`), e.g.
+        { "resource": "...", "<name>": <value> }.
     Sparse fieldset:
       - fields: names of the attributes and/or relationships to include in each record, as an
@@ -67,7 +112,10 @@ class McpToolkit::Authority::Tools::List < McpToolkit::Authority::Tools::Base
                        "field. Include \"id\" if you need it. Unknown names are rejected."
         }
       },
-      required: ["resource"]
+      required: ["resource"],
+      # Resource-specific filters (resource_schema's `resource_filters`) arrive as
+      # top-level arguments, so the schema must not advertise a closed shape.
+      additionalProperties: true
     }
   )

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

@@ -16,7 +16,14 @@ class McpToolkit::Authority::Tools::ResourceSchema < McpToolkit::Authority::Tool
       - relationships: associated resources emitted in the record's `links`; each names the
         `target_resource` it resolves to (callable via `list`/`get`)
       - standard_filters: ids, updated_since, limit, offset (accepted by the `list` tool)
-      - filters: the per-attribute equality filter keys the `list` tool accepts
+      - filters: the per-attribute equality/operator filter keys the `list` tool accepts in
+        its `filter` argument
+      - resource_filters: resource-specific filters, if any — each is passed as a TOP-LEVEL
+        argument of the `list` tool (NOT inside `filter`), e.g. { "resource": "...",
+        "<name>": <value> }
+      - filter_examples: ready-to-use `filter` payloads for this resource
+    A relationship's `filter` block lists the keys that filter by it; when it names a
+    `requires` key (e.g. a polymorphic id needing its type), pass BOTH keys together.
     The `attributes` and `relationships` names are also the valid values for the `fields` sparse
     fieldset argument on `get` / `list`. Call this before `list` to learn a resource's shape.
   DESC
@@ -34,7 +41,8 @@ class McpToolkit::Authority::Tools::ResourceSchema < McpToolkit::Authority::Tool
     }
   )
-  def call(context:, resource: nil, **_args)
+  def call(context:, resource: nil, **extra)
+    reject_unknown_arguments!(extra.except(:account_id))
     descriptor = resolve_descriptor(resource)
     ensure_resource_accessible!(descriptor, context)
     ensure_scope!(descriptor, context)

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

@@ -11,15 +11,23 @@ class McpToolkit::Authority::Tools::Resources < McpToolkit::Authority::Tools::Ba
   tool_name "resources"
   description <<~DESC.strip
     List all read-only resources available via the `list` and `get` tools. Returns each
-    resource's name and a short description. Call this once at the start of a session to learn
-    what exists, then use `resource_schema` for a specific resource's attributes and
-    relationships.
+    resource's name, a short description, whether it accepts filters (`filterable`) and — when
+    present — a usage `note` (read it before interpreting the resource's data). Call this once
+    at the start of a session to learn what exists, then use `resource_schema` for a specific
+    resource's attributes, relationships and filters.
   DESC
+  # Unlike get / resource_schema (strict kwargs pre-gem), the pre-gem resources
+  # tool tolerated ANY extra argument — so this one stays tolerant.
   def call(context:, **_args)
     {
       resources: visible_resources(context).map do |resource|
-        { name: resource.name, description: resource.description }
+        {
+          name: resource.name,
+          description: resource.description,
+          filterable: filterable?(resource),
+          note: resource.note
+        }.compact
       end
     }
   end
@@ -30,4 +38,18 @@ class McpToolkit::Authority::Tools::Resources < McpToolkit::Authority::Tools::Ba
   def visible_resources(context)
     registry.resources.reject { |resource| resource.superusers_only? && !context.superuser? }
   end
+  # Whether the resource can be filtered at all — via the generic allowlist OR a
+  # resource-specific custom filter. Reading `filterable_columns` resolves a
+  # lazily-declared allowlist, which may run host code (e.g. a DB-backed column
+  # list). One resource's failing resolution must not take down the whole
+  # discovery index — this is the tool every session calls first — so a raise
+  # degrades to nil (the `filterable` key is omitted for that resource) and the
+  # unresolved source is retried on the next read (see Resource#filterable).
+  def filterable?(resource)
+    resource.filterable_columns.any? || resource.custom_filters.any?
+  rescue StandardError => e
+    config.logger&.warn("mcp_toolkit: filterable resolution failed for #{resource.name}: #{e.message}")
+    nil
+  end
 end