mcp_authorization 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68b3436ab106d889c6ec4c889e9fef24235db5a5fcd64d840a0365fa3fa3b313
-  data.tar.gz: 36946f67a327d9f7ab7a2cea555fb35b16d12d0afab370bdfe80a9dc3b20f5db
+  metadata.gz: b01924de48adcd82456518091bcfb6309908158c118fe0865e600417a70be766
+  data.tar.gz: 59ec07c72ae70fd00a77ff4e935b0c9feb03b5344e080b3d83aecfecf799390c
 SHA512:
-  metadata.gz: 873fd4f953cfcf45d561b897da001d54155315a3f1add2fab2785b4abc11018af972c8aaeaf6b196031ecac8dad44e1ba52d33b0c945d63309beac0b2332c092
-  data.tar.gz: 8da192fdc1e11c65dc84bfbc0ec4c5ed80042279283c784bfa7d7fe55958ce11f216b10ec7b523aa3723b23e685ae3eac67e8f73f3e3466266c65916daeead12
+  metadata.gz: b603364bfb0c0aa3174e714f321b99c11394c938ccffd930aed01c950af91e60ab224a91565feafa3d1ee600a3327ec2c4c6d5d3420f69baf6f2e8b0ace25f02
+  data.tar.gz: a090369d9fe2da4276327b72ac3cf59f9e1626148c980093b42d6d3f85f0486bf496d3a9b6b5a906b1cec5d02e1d53b6b5e920c26c3d604c504655b522305cb5

data/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to this gem are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
 adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.9.0]
+
+Top-level params outside the caller's input schema are rejected instead of
+silently dropped. Behavior change on by default — opt out with
+`config.reject_unknown_input_keys = false`.
+
+### Changed
+- **`RbsSchemaCompiler.filter_input` raises `McpAuthorization::UnknownInputKeysError`** when the params carry a top-level key that is not in the caller's compiled input schema. Previously every such key was dropped by the closed-by-default projection, so a `tools/call` with an invented filter (`list_applicants(stage_id:, data: { booked_meeting: "true" }, limit: 100)`) returned `success: true` with the *unfiltered* page — and the calling agent moved every applicant on it, reporting the filter as applied. The same projection let a non-admin's `force: true` through as a silent no-op the agent then reported as done. The caller's schema is now the contract: a key the tool never declared and a key gated behind a predicate this caller fails are both outside it and are both rejected. The handler never runs, so a gated field is still never applied for a caller who lacks it. The error's `unknown_keys` / `accepted_keys` and its message name the offending keys and the params in this caller's schema — nothing `tools/list` did not already show that caller. Keys nested inside a declared object param are still projected silently; this release covers the top level only.
+- **The message is written for the model that reads it.** It states that nothing was executed, lists the accepted params, and tells the caller not to re-run the call without the rejected parameter (the result would be unfiltered) and not to approximate it with another one. A message that said "retry with accepted parameters" would have reproduced the incident.
+- **Materialized tools return the rejection in-band.** `Tool.materialize_for`'s `call` rescues `UnknownInputKeysError` and returns `MCP::Tool::Response.new([...], error: true)` with the text `<tool_name>: <message>`, rather than the SDK wrapping it as a JSON-RPC `-32603` that names the facade instead of the tool. Facade dispatch reaches the target's materialized `call`, so a facade caller — which only ever saw `arguments: object` — gets the same in-band error naming the inner tool. The non-materialized `Tool.call` lets the error propagate.
+- **Facade dispatch rejects keys beside `tool_name` and `arguments`.** The facade schema declares only those two, and dispatch read only `arguments`, so `{ tool_name:, arguments:, data: {...}, limit: 100 }` ran the target unfiltered and returned success. The facade now answers in-band naming itself. Its guidance differs from a tool's on purpose: a flattened parameter is supported and merely misplaced, so the caller is told to re-send it inside `arguments`, not to give up on it. `reject_unknown_input_keys = false` restores the old behavior here too.
+- **A facade `arguments` that is not an object is rejected instead of dropped.** `coerce_arguments` returned `{}` for an array, a scalar, a raw JSON blob of either, or `nil`, so the target ran with no arguments at all and the unfiltered default came back as a success — the same shape as the incident above, on the same surface.
+- **An `arguments.server_context` can no longer replace the request's context.** Dispatch splatted the caller's arguments *after* the `server_context:` keyword, and a later duplicate keyword wins in Ruby, so a caller-supplied `server_context` key bound the context used to compile the schema. Every predicate then ran against that object and fell open, admitting `@requires`/`@feature`-gated fields. The keyword is now passed last. Present since facades shipped in 0.7.0; direct (non-facade) calls were never affected, since the SDK passes `server_context:` last.
+- **An unroutable `tool_name` and a malformed `arguments` JSON blob come back in-band** with the facade's name and the list of tools the caller may use, instead of raising out of band.
+
+### Added
+- **`config.reject_unknown_input_keys`** (default `true`). `false` restores the 0.8 drop-everything behavior for both unknown and gated keys.
+- **`config.ignored_input_keys`** (default `[]`). Names the envelope keys a host's client attaches to every call — a UI annotation, not a tool parameter — which are dropped rather than rejected. Applied wherever a key is checked against a schema: beside `tool_name` and `arguments` on a facade call, and at the top level of any tool's params. A client that annotates every call reaches a flat domain directly, where there is no facade to exempt it, so one setting covers both surfaces.
+
+### Migration notes
+- **Check what your client puts beside `tool_name` and `arguments` before upgrading.** A client that annotates every facade call with an envelope key had it silently ignored through 0.8 and now has every call rejected. Name the key in `config.ignored_input_keys`, or declare it on the tools. Measuring the model's tool calls is not enough to find these: a host's own envelope is added by code, so it rides beside `arguments` where a survey of invented parameter names cannot see it, and a call the host makes on its own behalf may never appear in the conversation log at all. Read the client's source.
+- **Migrating a tool onto this gem is now a contract change.** A tool that used to be served by a hand-rolled endpoint, where an unknown key fell into a permit list and vanished, starts rejecting whatever its caller adds. When that caller is code rather than a model there is nobody to read the error and retry, so the key has to be declared or ignored in the same change that migrates the tool.
+- `reject_unknown_input_keys = false` does not cover the non-object `arguments` rejection: `arguments` is `required` in the facade schema, so an array, scalar or `nil` is rejected whatever the flag says. A host that leaves the MCP SDK's `validate_tool_call_arguments` on never reaches it, because the SDK rejects first.
+- A host that overrides `materialize_for` (or calls `filter_input` directly) must `rescue McpAuthorization::UnknownInputKeysError` and build its own error response. Until it does, the rejection still happens, but what the caller receives depends on the MCP SDK version — an in-band `Internal error calling tool <name>` response on some, a JSON-RPC internal error on others — and the host's exception reporter fires on every model typo.
+- Any client or test that relied on a top-level extra key being ignored — invented or gated — now sees an error. That reliance was the bug this release removes. A client that sends the full field set regardless of the caller's permissions must send only the fields in that caller's `tools/list` schema.
+
 ## [0.8.0]
 
 A supported seam for tool classes the host generates at runtime instead of

data/README.md

@@ -18,7 +18,7 @@ The gem gives you three independent controls over what each user sees:
 | Layer | Mechanism | Effect |
 |---|---|---|
 | **Tool visibility** | `authorization :manage_workflows` (RBAC) or `gate :feature, :sms` (any predicate) on the tool class | Tool hidden entirely from users who fail any check |
-| **Input fields** | `@requires(:backward_routing)` or `@feature(:sms)` on a param in `#:` annotation | Field excluded from the input schema *and* stripped from inbound params at call time |
+| **Input fields** | `@requires(:backward_routing)` or `@feature(:sms)` on a param in `#:` annotation | Field excluded from the input schema; a top-level one sent anyway is rejected at call time, a nested one is stripped |
 | **Output variants** | `@requires(:backward_routing)` or `@feature(:sms)` on a variant in `@rbs type output` | Variant excluded from the `oneOf` *and* fields projected out of the handler's return value before it crosses the wire |
 
 Tool-level `authorization :perm` is RBAC (calls `current_user.can?`). Tool-level `gate :predicate, :value` and the field-level annotations are generic — any predicate name works, as long as the server context implements `{predicate}?(value)`. See [Generic predicate tags](#generic-predicate-tags) below.
@@ -27,7 +27,13 @@ Tool-level `authorization :perm` is RBAC (calls `current_user.can?`). Tool-level
 
 `@requires` is a security boundary, not a hint. At tool-call time the gem:
 
-- **Filters inbound params** against the user's compiled input schema. Gated fields, and any keys not declared in the schema at all, are dropped before the handler's `#call` is invoked. A handler that takes `force:` gated behind `@requires(:admin)` will see `force: false` (its default) for non-admins even if the MCP client sends `force: true` in the raw JSON-RPC payload.
+- **Rejects inbound params outside the caller's compiled input schema.** The schema the caller received from `tools/list` is the contract. A top-level key outside it — one the tool never declared, or one gated behind a predicate this caller fails — does not exist from the caller's point of view. Such a key used to be dropped silently, which returned a success-shaped result that ignored part of the request: an LLM that never saw the per-tool schema (e.g. behind a [facade](#tool-grouping-facades)) invented a filter, got the *unfiltered* page back as `success: true`, and acted on it; a non-admin sending `force: true` was told the flag was applied. So `filter_input` raises `McpAuthorization::UnknownInputKeysError` and the materialized tool returns it as an in-band tool error (`isError: true`). The text is written for a model that will read it as a tool result:
+
+  ```
+  list_applicants: Unknown parameters: data, limit. Nothing was executed. Accepted parameters: funnel_id, page, per_page, query, stage_id. If your task depends on a rejected parameter (for example filtering by it), do not re-run this call without it: the result would be unfiltered. Do not substitute another parameter to approximate it. Use a tool that supports it, or tell the user it is not possible.
+  ```
+
+  Both lists come from the caller's own schema, so the message reveals nothing `tools/list` did not already show that caller. The handler never runs, so a gated field is still never applied for a caller who lacks it — the boundary holds, it just stops being silent. A facade call is checked twice: a key beside `tool_name` and `arguments` is rejected by the facade, which tells the caller to re-send it inside `arguments` (a flattened parameter is supported, just misplaced), and a key inside `arguments` by the target tool, which tells it not to re-run without the parameter. Name a client's envelope key in `config.ignored_input_keys` to have it dropped instead, on both surfaces. Keys nested inside a declared object param are still projected silently. With `strict_schema` on, the compiled root carries `additionalProperties: false`, so an MCP SDK that validates arguments (`validate_tool_call_arguments`, on by default in the `mcp` gem) rejects the call with its own generic message before this one is produced; turn that validation off on the server if the model must read the guidance. Set `config.reject_unknown_input_keys = false` to restore the pre-0.9 drop-everything behavior. A host that overrides `materialize_for` or calls `filter_input` directly must rescue `UnknownInputKeysError` itself; unrescued it surfaces as a JSON-RPC internal error carrying the same message. The non-materialized `Tool.call` lets it propagate.
 - **Projects the handler's return value** onto the user's compiled output schema. A variant hidden by `@requires` has its shape unavailable, so if the handler erroneously emits that variant's extra fields, they are stripped before serialization. A handler bug or refactor accident cannot leak admin-only fields to a non-admin.
 
 This means handler authors don't have to remember to re-check `can?` at every branch -- the schema *is* the boundary. `can?` inside `#call` is still useful for logic that changes behavior (not just field visibility), but it is no longer load-bearing for security.
@@ -76,6 +82,8 @@ end
 | `context_builder` | *required* | `(request) -> context` |
 | `cli_context_builder` | `nil` | `(domain:, role:) -> context` for rake tasks |
 | `strict_schema` | `false` | Emit stricter compiled schemas |
+| `reject_unknown_input_keys` | `true` | Reject a `tools/call` carrying a top-level param outside the caller's compiled input schema (undeclared, or gated behind a predicate the caller fails) instead of silently dropping it — see [Enforcement, not just shaping](#enforcement-not-just-shaping) |
+| `ignored_input_keys` | `[]` | Envelope keys a client attaches to every call, dropped rather than rejected — beside `tool_name`/`arguments` on a facade, and at the top level on any tool |
 | `tools_list_cache` | `nil` | `:memory`, `:redis`, or any object responding to `get`/`set` — see [Caching `tools/list`](#caching-toolslist) |
 | `tools_list_cache_ttl` | `3600` | Per-entry TTL in seconds |
 | `tools_list_cache_redis` | `nil` | Explicit Redis client for the `:redis` store |

data/lib/mcp_authorization/configuration.rb

@@ -100,6 +100,25 @@ module McpAuthorization
     #: bool
     attr_accessor :strict_schema
 
+    # When true (the default), a +tools/call+ whose params carry a top-level
+    # key outside the caller's compiled input schema is rejected with
+    # +McpAuthorization::UnknownInputKeysError+ instead of having the key
+    # silently dropped. A field gated by a predicate this caller fails is
+    # outside that schema and is rejected the same way — the caller's
+    # schema is the contract. Set to false to restore the pre-0.9
+    # drop-everything behavior.
+    #: bool
+    attr_accessor :reject_unknown_input_keys
+
+    # Keys a host's client attaches to every call as an envelope — a UI
+    # annotation, not a tool parameter — which are dropped rather than
+    # rejected. Empty by default. Applied wherever a key is checked against a
+    # schema: beside +tool_name+ and +arguments+ on a facade call, and at the
+    # top level of any tool's params, so the same envelope is exempt on a
+    # facade and on a flat domain alike.
+    #: Array[String]
+    attr_accessor :ignored_input_keys
+
     # Cache for the +tools/list+ response. Opt-in; defaults to no caching.
     # Accepts:
     #   nil / false  — no caching (default)
@@ -179,6 +198,8 @@ module McpAuthorization
       @context_builder = nil
       @cli_context_builder = nil
       @strict_schema = false
+      @reject_unknown_input_keys = true
+      @ignored_input_keys = []
       @tools_list_cache = nil
       @tools_list_cache_ttl = 3600
       @tools_list_cache_redis = nil

data/lib/mcp_authorization/facade_builder.rb

@@ -25,9 +25,19 @@ module McpAuthorization
     # registered tool name. Renaming the category is the fix.
     class FacadeNameCollisionError < StandardError; end
 
+    # A facade call the caller can fix from the error alone: an unroutable
+    # +tool_name+, a malformed +arguments+, or a key beside the two the
+    # facade declares. Returned in-band so the message reaches the model.
+    # Raised only before dispatch reaches the target, so it never relabels a
+    # target's own error with the facade's name.
+    class FacadeCallError < ArgumentError; end
+
     # Fallback group for uncategorized tools (default mode).
     FALLBACK_CATEGORY = :uncategorized #: Symbol
 
+    # The only two keys a facade's inputSchema declares.
+    FACADE_KEYS = %w[arguments tool_name].freeze #: Array[String]
+
     class << self
       # All facades for a domain, one per non-empty group the caller has at
       # least one permitted tool in. Empty groups produce no facade — which
@@ -153,6 +163,9 @@ module McpAuthorization
 
           define_singleton_method(:call) do |server_context: nil, **params|
             builder.send(:dispatch, domain, advertised, params, server_context || ctx)
+          rescue McpAuthorization::FacadeBuilder::FacadeCallError => e
+            # Raised before the target runs, so the facade's name is the right label.
+            MCP::Tool::Response.new([{ type: "text", text: "#{name}: #{e.message}" }], error: true)
           end
         end
       end
@@ -235,10 +248,12 @@ module McpAuthorization
       #    the same code path as a direct call.
       #: (String, Set[String], Hash[Symbol, untyped], untyped) -> untyped
       def dispatch(domain, advertised, params, server_context)
+        reject_unknown_facade_keys!(params)
         tool_name = (params[:tool_name] || params["tool_name"]).to_s
         unless advertised.include?(tool_name)
-          raise ArgumentError,
-            "unknown tool_name #{tool_name.inspect}; expected one of #{advertised.to_a.sort.inspect}"
+          raise FacadeCallError,
+            "unknown tool_name #{tool_name.inspect}. Nothing was executed. " \
+            "Available tools: #{advertised.to_a.sort.join(", ")}."
         end
 
         candidates = McpAuthorization::ToolRegistry.tools_by_domain[domain] || []
@@ -249,7 +264,46 @@ module McpAuthorization
         raise McpAuthorization::Tool::NotAuthorizedError unless original && target
 
         arguments = coerce_arguments(original, params[:arguments] || params["arguments"], server_context)
-        target.call(server_context: server_context, **arguments)
+        reject_reserved_argument_keys!(arguments)
+        # server_context last: a later duplicate keyword wins in Ruby, so an
+        # `arguments.server_context` cannot replace the request's own context.
+        target.call(**arguments, server_context: server_context)
+      end
+
+      # The facade schema declares only tool_name and arguments; a sibling key
+      # is outside every caller's contract and was silently ignored, the same
+      # gap filter_input closes for the target tool. The guidance differs from
+      # the target's: a flattened parameter is supported, it is just in the
+      # wrong place, so the caller is told to nest it rather than to give up.
+      # +config.ignored_input_keys+ names host envelope keys to drop instead.
+      #: (Hash[Symbol, untyped]) -> void
+      def reject_unknown_facade_keys!(params)
+        return unless McpAuthorization.config.reject_unknown_input_keys
+
+        ignored = McpAuthorization.config.ignored_input_keys.map(&:to_s)
+        unknown = params.keys.map(&:to_s) - FACADE_KEYS - ignored
+        return if unknown.empty?
+
+        list = unknown.join(", ")
+        raise FacadeCallError,
+          "Unknown parameter#{"s" if unknown.size > 1}: #{list}. Nothing was executed. " \
+          "This tool accepts only tool_name and arguments; a tool's own parameters go " \
+          "inside arguments. Re-send with #{list} inside arguments if the tool declares " \
+          "#{unknown.size > 1 ? "them" : "it"}, and omit #{unknown.size > 1 ? "them" : "it"} otherwise."
+      end
+
+      # +server_context+ binds the target's own keyword, so it can never be a
+      # tool parameter and +filter_input+ never sees it. Rejecting it keeps the
+      # release's guarantee — no key outside the schema is quietly ignored —
+      # and makes the caller's intent visible rather than silently discarded.
+      #: (Hash[Symbol, untyped]) -> void
+      def reject_reserved_argument_keys!(arguments)
+        return unless McpAuthorization.config.reject_unknown_input_keys
+        return unless arguments.key?(:server_context)
+
+        raise FacadeCallError,
+          "server_context is not a tool parameter and cannot be supplied by a caller. " \
+          "Nothing was executed. Remove it from arguments and re-send."
       end
 
       # Coerce a facade's +arguments+ blob against the target tool's
@@ -257,12 +311,19 @@ module McpAuthorization
       # objects as JSON strings; the facade's own contract only knows
       # `arguments: object`, so string blobs are parsed here — both the
       # blob itself and any top-level value whose target type is an object
-      # or array. Unknown / permission-gated fields are then stripped by
-      # the target's filter_input as in a direct call.
+      # or array. Keys outside the target's schema are then rejected by the
+      # target's filter_input as in a direct call.
       #: (singleton(McpAuthorization::Tool), untyped, untyped) -> Hash[Symbol, untyped]
       def coerce_arguments(tool_class, raw, server_context)
         parsed = raw.is_a?(String) ? parse_json_blob(raw, "arguments") : raw
-        return {} unless parsed.is_a?(Hash)
+        # An empty hash here used to mean "call the target with no arguments",
+        # so a caller that sent an array, a scalar or nil got the unfiltered
+        # default result reported as a success.
+        unless parsed.is_a?(Hash)
+          raise FacadeCallError,
+            "arguments must be an object mapping parameter names to values; got " \
+            "#{parsed.nil? ? "null" : parsed.class.name.downcase}. Nothing was executed."
+        end
 
         schema = tool_class.dynamic_input_schema(server_context: server_context)
         properties = schema.is_a?(Hash) ? (schema[:properties] || schema["properties"] || {}) : {}
@@ -282,7 +343,8 @@ module McpAuthorization
       def parse_json_blob(string, field)
         JSON.parse(string)
       rescue JSON::ParserError => e
-        raise ArgumentError, "#{field} was sent as a string but is not valid JSON: #{e.message}"
+        raise FacadeCallError,
+          "#{field} was sent as a string but is not valid JSON: #{e.message}. Nothing was executed."
       end
     end
   end

data/lib/mcp_authorization/rbs_schema_compiler.rb

@@ -42,6 +42,31 @@ require "rbs/parser_aux"
 require_relative "diagnostics"
 
 module McpAuthorization
+  # Raised by +RbsSchemaCompiler.filter_input+ when the caller sent a
+  # top-level param outside its compiled input schema. +unknown_keys+ are
+  # the offending names; +accepted_keys+ are the names in the caller's
+  # schema. The message is written for an LLM that will read it as a tool
+  # result: it must not suggest re-running without the parameter, because
+  # for a filter that means acting on an unfiltered result.
+  class UnknownInputKeysError < ArgumentError
+    attr_reader :unknown_keys, :accepted_keys
+
+    #: (Array[String], Array[String]) -> void
+    def initialize(unknown_keys, accepted_keys)
+      @unknown_keys = unknown_keys
+      @accepted_keys = accepted_keys
+      accepted = accepted_keys.empty? ? "none" : accepted_keys.join(", ")
+      super(
+        "Unknown parameter#{"s" if unknown_keys.size > 1}: #{unknown_keys.join(", ")}. " \
+        "Nothing was executed. Accepted parameters: #{accepted}. " \
+        "If your task depends on a rejected parameter (for example filtering by it), " \
+        "do not re-run this call without it: the result would be unfiltered. " \
+        "Do not substitute another parameter to approximate it. " \
+        "Use a tool that supports it, or tell the user it is not possible."
+      )
+    end
+  end
+
   # Compiles RBS-style type annotations in Ruby source files into JSON Schema,
   # with per-request filtering based on +@requires+ permission tags.
   #
@@ -127,10 +152,16 @@ module McpAuthorization
 
       # Filter incoming params against the user's compiled input schema.
       #
-      # Any key that is not in the schema for this user is dropped — including
-      # +@requires+-gated fields the user lacks permission for, and any
-      # unknown fields not declared in the schema. This is the runtime
-      # enforcement counterpart to the input-shaping that +compile_input+ did.
+      # This is the runtime enforcement counterpart to the input-shaping
+      # that +compile_input+ did. The caller's schema is the contract: a
+      # top-level key outside it — whether the tool never declared it or
+      # declared it behind a predicate this caller fails — does not exist
+      # from the caller's point of view. Such a key used to be dropped
+      # silently, which returned a successful-looking result that ignored
+      # part of the request (an invented filter, a gated flag). By default
+      # it now raises +UnknownInputKeysError+; see
+      # +config.reject_unknown_input_keys+. Keys nested inside a declared
+      # object param are still projected silently.
       #
       # @param handler_class [Class]
       # @param params [Hash] Params as received from the MCP client.
@@ -141,9 +172,27 @@ module McpAuthorization
         return params unless params.is_a?(Hash)
         schema = compile_input_for_filter(handler_class, server_context: server_context)
         return params unless schema
+        reject_unknown_input_keys!(params, schema) if McpAuthorization.config.reject_unknown_input_keys
         project_against_schema(params, schema, defs_from(schema))
       end
 
+      # Raise when +params+ carries a top-level key outside +schema+'s
+      # properties. Both the unknown and the accepted names come from the
+      # caller's own schema, so the message reveals nothing +tools/list+ did
+      # not already show this caller. A host's envelope key named in
+      # +config.ignored_input_keys+ is dropped here as it is on a facade: a
+      # client that annotates every call reaches a flat domain directly, where
+      # there is no facade to exempt it.
+      #: (Hash[untyped, untyped], Hash[Symbol, untyped]) -> void
+      def reject_unknown_input_keys!(params, schema)
+        accepted = (schema[:properties] || {}).keys.map(&:to_s)
+        ignored = McpAuthorization.config.ignored_input_keys.map(&:to_s)
+        unknown = params.keys.map(&:to_s) - accepted - ignored
+        return if unknown.empty?
+
+        raise UnknownInputKeysError.new(unknown, accepted.sort)
+      end
+
       # Filter the handler's return value against the user's compiled output
       # schema. Any field/variant not visible to this user is stripped from
       # the result.

data/lib/mcp_authorization/tool.rb

@@ -215,9 +215,10 @@ module McpAuthorization
       # Create an anonymous MCP::Tool subclass with this user's schemas baked in.
       #
       # The materialized +call+ enforces the compiled schema at runtime:
-      # input params are stripped of unknown or permission-gated fields
-      # before reaching the handler, and the handler's return value is
-      # projected onto the user's output schema before being serialized.
+      # a top-level param outside the caller's input schema is rejected
+      # in-band (+UnknownInputKeysError+ → +isError: true+) before the
+      # handler runs, and the handler's return value is projected onto the
+      # user's output schema before being serialized.
       #: (untyped) -> Class?
       def materialize_for(server_context)
         defn = to_mcp_definition(server_context: server_context)
@@ -236,9 +237,16 @@ module McpAuthorization
 
           define_singleton_method(:call) do |server_context: nil, **params|
             effective_ctx = server_context || ctx
-            filtered_params = McpAuthorization::RbsSchemaCompiler.filter_input(
-              handler, params, server_context: effective_ctx
-            )
+            begin
+              filtered_params = McpAuthorization::RbsSchemaCompiler.filter_input(
+                handler, params, server_context: effective_ctx
+              )
+            rescue McpAuthorization::UnknownInputKeysError => e
+              # In-band tool error (isError: true), not a JSON-RPC failure, so the
+              # model reads the guidance. tool_name, not defn[:name]: a host may
+              # rename the materialized class, and the caller knows the new name.
+              next MCP::Tool::Response.new([{ type: "text", text: "#{tool_name}: #{e.message}" }], error: true)
+            end
             raw = handler.new(server_context: effective_ctx).call(**symbolize.call(filtered_params))
             result = McpAuthorization::RbsSchemaCompiler.filter_output(
               handler, raw, server_context: effective_ctx

data/lib/mcp_authorization/version.rb

@@ -1,3 +1,3 @@
 module McpAuthorization
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mcp_authorization
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - AndyGauge
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-11 00:00:00.000000000 Z
+date: 2026-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -128,7 +128,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.3.27
 signing_key:
 specification_version: 4
 summary: Rails engine for MCP tools with per-request schema discrimination