administrate-mcp 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4da1e224450ced4f0f0e209279bf8f07e3e863b8cc54d53deb20071e09c162f5
-  data.tar.gz: 7299ecaabb67efa26432087c689d6291d7b839692a97855997f0a5aa94ea8e5c
+  metadata.gz: c22f6f3b6febbe8e86b8cb721e30f63e4e9232edbd668a3a311e44ff180b9117
+  data.tar.gz: cd60a0dad70e15f8235e1ed6c3c2385b5d8cc56efe2a66e1b84a18b3b5fe4087
 SHA512:
-  metadata.gz: 52016172bf5d81384da02d845c2a7e491ad88859b414ce20b1732804deeff46f930a4df8e4d73b254721c31c39fe8bf2907cda7e56c32dd7b1728641993025ae
-  data.tar.gz: 78e0e4ac8f02ce53a3c4603d5bcb8d95ace6976192fed36519a0df092fa2a0b7bec2ac1fc071e3fcc2862e60f81195377943bd2c7693060c488d5ea4b4548a5a
+  metadata.gz: 65ea611de7b893d7b4aaec605cc91a3bd742187ca3ff2ef340229009daa130a7bc7abb79e1f4bda2d4995670ff0dadfce95252f659366ada2713458a4d70a60c
+  data.tar.gz: 23a0677acecdb975efeb760a6f797f9319e0ae95b607be57db1dd5a5be5c1db21141aaa3cfcfbf90625472059b65a3263ae8b10ec0ab00d002414e19d5c67215

data/CHANGELOG.md

@@ -8,6 +8,66 @@ minor release may change behaviour a host depends on; the entry says so when it
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-02
+
+### Changed
+
+- **Behaviour change for clients:** two failures of `admin_resource_list_resources`,
+  `admin_resource_list` and `admin_resource_show` now return HTTP 200 with a tool error
+  (`result.isError: true`) instead of HTTP 403 with `X-Auth-Error: forbidden` and JSON-RPC code
+  -32003. Clients such as Claude showed that 403 as an authentication failure and dropped the message:
+  - An unknown resource name. The message says the name is not registered and lists up to five
+    close registered names, taken only from the resources the caller can read.
+  - A registered resource the caller may not read. The message is "Resource `<name>` exists but you
+    are not authorized to list it" (or "show it"), followed by the authorization adapter's own
+    message when the host wrote one. The old 403 body already told the two cases apart
+    (`Unknown resource: …` against `Not authorized to show? <Model>`); the difference is that
+    clients now display it.
+
+  A tool-level refusal, a missing OAuth scope or a required role, is still a 403 for now
+  ([#11](https://github.com/sorare/administrate-mcp/issues/11)). The per-resource denial is raised
+  as `Administrate::MCP::ResourceForbiddenError`, a subclass of `UnauthorizedError`, so host code
+  that rescues `UnauthorizedError` still catches it.
+
+### Fixed
+
+- A `subscriptions/listen` request no longer raises `NoMethodError` in the host's Rack stack. The
+  `mcp` gem answers it with a streaming SSE body meant to stay open, which the engine's controller
+  cannot serve; the transport is now built with `serve_subscriptions_listen: false`, so the method
+  is answered with HTTP 404 and JSON-RPC error `-32601` like any unimplemented method, and
+  `server/discover` stops advertising the `listChanged` and `subscribe` capability flags.
+
+## [0.2.0] - 2026-09-22
+
+### Added
+
+- The admin console for the engine's own tables: the `Administrate::MCP::ApiKeyDashboard` and
+  `Administrate::MCP::FeedbackDashboard` base dashboards, and the `Administrate::MCP::ApiKeysAdmin`
+  and `Administrate::MCP::FeedbacksAdmin` controller concerns. A host subclasses each dashboard
+  under the name its own inflections give `administrate_mcp_api_key_dashboard.rb`, which differs
+  between an application that registers MCP as an acronym and one that does not. The concern goes in
+  a controller of the host's own, which keeps its base controller, authentication and policies; the
+  engine supplies the resource wiring, key generation, the one-time plaintext in the flash, and
+  revocation. Write-enabled keys are refused until the host overrides `mcp_write_access_allowed?`.
+- `config.admin_foreign_key`, defaulting to `:admin_id`, so a host whose admin table already has a
+  differently named foreign key can keep that column name instead of renaming it. The association
+  stays called `admin` everywhere in the engine's API; only the column it reads and writes changes.
+- `config.persist_feedback`, defaulting to `false`, so a host can use `report_mcp_improvement` and
+  `on_feedback` as a plain signal without carrying the `administrate_mcp_feedbacks` table, its model
+  or its migration. Set it to `true` for the previous behaviour: the report is persisted before
+  `on_feedback` runs, and the dashboard and `CleanOldFeedbacks` housekeeping become meaningful.
+- `config.feedback_tool`, defaulting to `true`, to stop publishing `report_mcp_improvement`
+  altogether.
+
+### Changed
+
+- `on_feedback` is now called with a `FeedbackReport`, a plain value object, instead of a persisted
+  `Feedback` record. A host reading attributes off the argument (`category`, `suggestion`,
+  `resource_name`, `admin`, `api_key`) sees no difference; a host that relied on it being an
+  `ActiveRecord` instance, for example calling `.save`, `.update` or `.reload` on it, or expecting
+  `.persisted?` to be true, must update its `on_feedback` hook. When `config.persist_feedback` is
+  `true` the persisted record is still reachable, as `report.record`.
+
 ## [0.1.0] - 2026-09-22
 
 ### Added
@@ -57,5 +117,7 @@ minor release may change behaviour a host depends on; the entry says so when it
   took the gem from git before 0.1.0 must reinstall its migrations rather than migrate
   incrementally.
 
-[Unreleased]: https://github.com/sorare/administrate-mcp/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/sorare/administrate-mcp/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/sorare/administrate-mcp/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/sorare/administrate-mcp/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/sorare/administrate-mcp/releases/tag/v0.1.0

data/README.md

@@ -23,6 +23,7 @@ permissions the admin UI enforces.
 - [Dashboard declarations](#dashboard-declarations)
 - [Authentication](#authentication)
 - [OAuth](#oauth)
+- [Improving the server from its own use](#improving-the-server-from-its-own-use)
 - [Rate limiting](#rate-limiting)
 - [Admin integration](#admin-integration)
 - [Development](#development)
@@ -53,8 +54,14 @@ about your application; everything host-specific goes through `Administrate::MCP
   as the admin UI, so a resource an admin cannot see in the browser is not exposed over MCP either.
 - Search, filters and field selection built from the dashboard's own declarations, plus foreign key
   filters that need no declaration at all.
-- A feedback tool, `report_mcp_improvement`, so users can report what the server got wrong, and a
-  housekeeping method to clean up old feedback records.
+- A feedback tool, `report_mcp_improvement`, so the client can tell you which of your descriptions,
+  filters and fields let it down, and you can fix them. See
+  [Improving the server from its own use](#improving-the-server-from-its-own-use). The signal is
+  always available through `config.on_feedback`; storing it, the dashboard and the clean-up service
+  are a batteries-included option a host turns on with `config.persist_feedback`.
+- The admin console for its own tables, as two dashboards and two controller concerns you include
+  in controllers of your own: issuing an API key, revoking one, and reading the feedback, without
+  giving up your base controller, your authentication or your policies.
 - Optional Sidekiq introspection tools, `sidekiq_stats` and `sidekiq_retries`, wired to a stats
   provider object you supply.
 - No reference to a constant it does not own: field serializers are keyed on class names, dashboards
@@ -151,13 +158,20 @@ bin/rails db:migrate
 
 The tables are `administrate_mcp_api_keys`, `administrate_mcp_feedbacks`,
 `administrate_mcp_oauth_applications`, `administrate_mcp_oauth_access_grants` and
-`administrate_mcp_oauth_access_tokens`. They use uuid primary keys and a uuid `admin_id` column
-that is indexed but carries no foreign key constraint, so the engine works with any admin table.
+`administrate_mcp_oauth_access_tokens`. They use uuid primary keys and a uuid column, `admin_id` by
+default, that is indexed but carries no foreign key constraint, so the engine works with any admin
+table. Set `config.admin_foreign_key` before running the migrations if the host's own admin table
+already uses a different column name and renaming it is not an option, for example a live
+credentials table.
+
+`administrate_mcp_feedbacks` is only needed when `config.persist_feedback` is `true`; leave it
+`false`, the default, and the migration ships but the table is never read from or written to.
 
 ## Quick start
 
 The smallest configuration that works. Save it as `config/initializers/administrate_mcp.rb`; it
-must run before the engine's models load, because the `admin` association reads `admin_class_name`:
+must run before the engine's models load, because the `admin` association reads `admin_class_name`
+and `admin_foreign_key`:
 
 ```ruby
 Administrate::MCP.configure do |c|
@@ -218,6 +232,35 @@ with the gem for hosts that run edge-managed OAuth in front of the application:
 The built-in OAuth 2.1 server, what turning it off with `c.oauth = false` changes, and when a host
 should: [docs/oauth.md](docs/oauth.md).
 
+## Improving the server from its own use
+
+Every tool here is built from your dashboards: the resource names, the field lists, the filters and
+the `MCP_DESCRIPTION` you wrote. The client calling those tools is the one that gets misled when any
+of it is wrong, and it is the only party that knows which call it was trying to make. The engine has
+no way to detect this on its own: a vague description is not an error, it is a successful call that
+returned the wrong thing or a query the caller gave up on.
+
+`report_mcp_improvement` is how the client tells you. Its categories are deliberately not free text.
+Each one names a change you make in a dashboard:
+
+| Category | What it points at |
+| --- | --- |
+| `description` | `MCP_DESCRIPTION` is missing, vague or actively misleading |
+| `missing_filter` | the query needed a filter the dashboard does not declare |
+| `missing_field` | a field the caller needed is not on the show page |
+| `missing_resource` | a dashboard is not exposed, or does not exist |
+| `serialization` | a field came back unreadable and needs a serializer registered |
+| `other` | anything the categories above do not cover |
+
+A report arrives with the category, the resource it concerns and the client's own account of what it
+wanted, which is most of a change request already. Wire `config.on_feedback` to somewhere your team
+will actually read, work through what arrives, and the next caller gets a server that describes
+itself better. Turning on `config.persist_feedback` keeps the reports in a table so you can triage a
+batch at a time rather than react to each one.
+
+This is the loop the tool exists for. It is worth running deliberately rather than waiting for
+complaints: point a client at the server, give it real tasks, and collect what it could not do.
+
 ## Rate limiting
 
 The rack-attack throttles recommended for the OAuth endpoints, and the helper that registers them
@@ -225,8 +268,9 @@ for you: [docs/oauth.md#rate-limiting](docs/oauth.md#rate-limiting).
 
 ## Admin integration
 
-Exposing the engine's own tables (API keys, feedback) in your host admin, customising the consent
-screen, and cleaning up old feedback: [docs/admin-integration.md](docs/admin-integration.md).
+Including the API key and feedback consoles the engine ships, what a host overrides in them,
+listing the engine's own tables over the protocol, customising the consent screen, and cleaning up
+old feedback: [docs/admin-integration.md](docs/admin-integration.md).
 
 ## Development
 

data/app/controllers/concerns/administrate/mcp/api_keys_admin.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Administrate console for the API keys admins authenticate to the MCP server with. The host
+    # keeps its own base controller, authentication and policies; this supplies the resource wiring
+    # and the two actions a write-once credential needs, because the plaintext key exists only in
+    # the response that creates it.
+    #
+    # A host that lets some admins mint write-enabled keys overrides `mcp_write_access_allowed?`.
+    module ApiKeysAdmin
+      extend ActiveSupport::Concern
+      include ResourceController
+
+      TOKEN_PREFIX_LENGTH = 13
+      WRITE_ACCESS_REFUSAL = 'Only administrators allowed to grant write access can create write-enabled API keys.'
+
+      included do
+        administrate_mcp_resource Administrate::MCP::ApiKey
+      end
+
+      def create
+        token = Administrate::MCP::ApiKey.generate_token
+        api_key = build_mcp_api_key(token)
+        authorize_mcp_resource(api_key)
+
+        if api_key.write_access? && !mcp_write_access_allowed?
+          return render_mcp_form_error(api_key, WRITE_ACCESS_REFUSAL)
+        end
+
+        if api_key.save
+          redirect_to_mcp_index("MCP API key created. Copy it now, it is not shown again: #{token}")
+        else
+          render_mcp_form_error(api_key, api_key.errors.full_messages.join(', '))
+        end
+      end
+
+      def destroy
+        api_key = requested_resource
+        authorize_mcp_resource(api_key)
+        api_key.revoke!
+
+        redirect_to_mcp_index("API key '#{api_key.name}' has been revoked.")
+      end
+
+      private
+
+      def build_mcp_api_key(token)
+        Administrate::MCP::ApiKey.new(
+          admin: mcp_api_key_owner,
+          token_digest: Administrate::MCP::ApiKey.digest_token(token),
+          token_prefix: token[0, TOKEN_PREFIX_LENGTH],
+          name: mcp_api_key_name,
+          write_access: mcp_write_access_requested?
+        )
+      end
+
+      def mcp_api_key_owner
+        Administrate::MCP.config.current_admin.call(self)
+      end
+
+      def mcp_api_key_name
+        params.dig(resource_name, :name).presence || 'Unnamed key'
+      end
+
+      def mcp_write_access_requested?
+        ActiveModel::Type::Boolean.new.cast(params.dig(resource_name, :write_access)) || false
+      end
+
+      # A write-enabled key carries every write tool, so granting one is a decision the host makes.
+      def mcp_write_access_allowed?
+        false
+      end
+
+      def authorize_mcp_resource(api_key)
+        authorize(api_key) if respond_to?(:authorize, true)
+      end
+
+      def redirect_to_mcp_index(notice)
+        redirect_to({ action: :index }, notice:, status: :see_other)
+      end
+
+      def render_mcp_form_error(api_key, message)
+        flash.now[:error] = message
+        render :new, locals: { page: Administrate::Page::Form.new(dashboard, api_key) }, status: :unprocessable_content
+      end
+
+      def scoped_resource
+        super.order(created_at: :desc)
+      end
+    end
+  end
+end

data/app/controllers/concerns/administrate/mcp/feedbacks_admin.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Administrate console for the improvement reports `report_mcp_improvement` stores. Reading them
+    # is the whole point, so no action is overridden beyond the resource wiring and the ordering:
+    # the newest report is the one a maintainer has not acted on yet.
+    #
+    # Only meaningful with `config.persist_feedback` on; without it nothing writes to the table.
+    module FeedbacksAdmin
+      extend ActiveSupport::Concern
+      include ResourceController
+
+      included do
+        administrate_mcp_resource Administrate::MCP::Feedback
+      end
+
+      private
+
+      def scoped_resource
+        super.order(created_at: :desc)
+      end
+    end
+  end
+end

data/app/controllers/concerns/administrate/mcp/resource_controller.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Points an Administrate controller at a model the engine owns, rather than at the one
+    # Administrate would infer from the controller's own name.
+    #
+    # The dashboard is left alone on purpose. Administrate finds it by camelizing the controller's
+    # name, and a host that registers MCP as an inflection acronym spells that constant differently
+    # from one that does not. Naming it here would be right in one host and an autoloading error in
+    # the other, so each host declares its own dashboard, usually a subclass of the engine's.
+    module ResourceController
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :mcp_resource_class, :mcp_dashboard_class
+      end
+
+      class_methods do
+        # `dashboard` is only needed for a dashboard Administrate cannot find from the controller's
+        # own name.
+        def administrate_mcp_resource(resource_class, dashboard: nil)
+          self.mcp_resource_class = resource_class
+          self.mcp_dashboard_class = dashboard
+        end
+      end
+
+      def resource_class
+        mcp_resource_class
+      end
+
+      private
+
+      def resource_resolver
+        @resource_resolver ||=
+          Administrate::MCP::ResourceResolver.new(
+            controller_path,
+            resource_class: mcp_resource_class,
+            dashboard_class: mcp_dashboard_class
+          )
+      end
+    end
+  end
+end

data/app/dashboards/administrate/mcp/api_key_dashboard.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'administrate/base_dashboard'
+
+module Administrate
+  module MCP
+    # Default Administrate dashboard for the engine's API keys. A host that wants other columns
+    # subclasses it and redefines the constants it cares about.
+    #
+    # Nothing here is registered as an MCP resource: the registry only reads the host's own
+    # dashboard directory, so a host that wants the keys listed over the protocol declares a
+    # subclass there with an `MCP_DESCRIPTION`.
+    class ApiKeyDashboard < Administrate::BaseDashboard
+      ATTRIBUTE_TYPES = {
+        id: Field::String.with_options(searchable: false),
+        admin: Field::BelongsTo.with_options(class_name: Administrate::MCP.config.admin_class_name),
+        name: Field::String,
+        token_prefix: Field::String,
+        write_access: Field::Boolean,
+        last_used_at: Field::DateTime,
+        revoked_at: Field::DateTime,
+        created_at: Field::DateTime,
+        updated_at: Field::DateTime
+      }.freeze
+
+      COLLECTION_ATTRIBUTES = %i[name admin token_prefix write_access last_used_at revoked_at].freeze
+
+      SHOW_PAGE_ATTRIBUTES = %i[
+        id
+        admin
+        name
+        token_prefix
+        write_access
+        last_used_at
+        revoked_at
+        created_at
+        updated_at
+      ].freeze
+
+      FORM_ATTRIBUTES = %i[name write_access].freeze
+
+      COLLECTION_FILTERS = {}.freeze
+
+      def self.model
+        Administrate::MCP::ApiKey
+      end
+
+      def display_resource(api_key)
+        "#{api_key.name} (#{api_key.token_prefix}...)"
+      end
+    end
+  end
+end

data/app/dashboards/administrate/mcp/feedback_dashboard.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'administrate/base_dashboard'
+
+module Administrate
+  module MCP
+    # Default Administrate dashboard for the improvement reports the feedback tool stores. A host
+    # that wants other columns subclasses it and redefines the constants it cares about.
+    class FeedbackDashboard < Administrate::BaseDashboard
+      ATTRIBUTE_TYPES = {
+        id: Field::String.with_options(searchable: false),
+        admin: Field::BelongsTo.with_options(class_name: Administrate::MCP.config.admin_class_name),
+        api_key: Field::BelongsTo.with_options(class_name: 'Administrate::MCP::ApiKey'),
+        category: Field::Select.with_options(collection: -> { Administrate::MCP::Feedback.categories.keys }),
+        resource_name: Field::String,
+        suggestion: Field::Text,
+        status: Field::Select.with_options(collection: -> { Administrate::MCP::Feedback.statuses.keys }),
+        created_at: Field::DateTime,
+        updated_at: Field::DateTime
+      }.freeze
+
+      COLLECTION_ATTRIBUTES = %i[category resource_name status admin created_at].freeze
+
+      SHOW_PAGE_ATTRIBUTES = %i[id admin api_key category resource_name suggestion status created_at updated_at].freeze
+
+      # Triaging a report is the one edit worth making from the console.
+      FORM_ATTRIBUTES = %i[status].freeze
+
+      COLLECTION_FILTERS = {
+        status: ->(resources, status) { resources.where(status:) },
+        category: ->(resources, category) { resources.where(category:) }
+      }.freeze
+
+      def self.model
+        Administrate::MCP::Feedback
+      end
+
+      def display_resource(feedback)
+        "#{feedback.category} on #{feedback.resource_name.presence || 'the server'}"
+      end
+    end
+  end
+end

data/app/lib/administrate/mcp/admin_dashboard_tool.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
+require 'did_you_mean'
+
 module Administrate
   module MCP
     # Base class for MCP tools that operate on Administrate dashboard resources.
     class AdminDashboardTool < BaseTool
       LISTED_VALID_VALUES = 40
+      MAX_SUGGESTIONS = 5
+      ACTION_VERBS = { index?: 'list', show?: 'show' }.freeze
 
       class << self
         def policy_action
@@ -14,7 +18,7 @@ module Administrate
         def check_roles!(admin, resource: nil, **)
           return unless resource && policy_action
 
-          entry = find_dashboard_entry!(resource)
+          entry = find_dashboard_entry!(admin, resource)
           authorize_resource!(admin, entry.model_class, policy_action)
         end
 
@@ -22,15 +26,57 @@ module Administrate
           Administrate::MCP.config.authorization.authorized?(admin, model_class, action)
         end
 
+        # The adapter is the host's and raises a plain UnauthorizedError. Re-raised here so a denial on
+        # one resource reaches the caller as a tool error instead of a 403 on the whole response. A
+        # message the host wrote is kept, since it may say why; the adapters' generic one adds nothing.
         def authorize_resource!(admin, model_class, action)
           Administrate::MCP.config.authorization.authorize!(admin, model_class, action)
+        rescue UnauthorizedError => e
+          verb = ACTION_VERBS.fetch(action.to_sym) { action.to_s.delete_suffix('?') }
+          message = "Resource `#{model_class.name.underscore}` exists but you are not authorized to #{verb} it."
+          reason = e.message unless e.message == Authorization::Base.denial_message(action, model_class.name)
+          raise ResourceForbiddenError, [message, reason].compact.join(' ')
         end
 
-        def find_dashboard_entry!(resource_name)
+        def find_dashboard_entry!(admin, resource_name)
           entry = DashboardRegistry.find(resource_name)
           return entry if entry
 
-          raise UnauthorizedError, "Unknown resource: #{resource_name}"
+          raise InvalidArgumentError, unknown_resource_message(admin, resource_name)
+        end
+
+        def unknown_resource_message(admin, resource_name)
+          message = "Unknown resource: #{resource_name}. This name is not registered."
+          suggestions = resource_suggestions(admin, resource_name)
+          return "#{message} Call admin_resource_list_resources for the catalog." if suggestions.empty?
+
+          "#{message} Closest registered names: #{suggestions.join(', ')}"
+        end
+
+        # Only names the caller can read are suggested, as in the catalog, so a typo does not reveal
+        # hidden resources.
+        def resource_suggestions(admin, resource_name)
+          suggestion_candidates(resource_name).lazy.select { |name| readable?(admin, name) }.first(MAX_SUGGESTIONS)
+        end
+
+        # Matches on the last path segment too, so a bare "order" finds "shop/order".
+        def suggestion_candidates(resource_name)
+          key = resource_name.to_s.underscore.singularize
+          names = DashboardRegistry.resource_names
+          by_segment = names.group_by { |name| name.split('/').last }
+          segment = key.split('/').last.to_s
+          close_segments = DidYouMean::SpellChecker.new(dictionary: by_segment.keys).correct(segment)
+
+          (
+            by_segment.fetch(segment, []) +
+              DidYouMean::SpellChecker.new(dictionary: names).correct(key) +
+              close_segments.flat_map { |name| by_segment[name] }
+          ).uniq
+        end
+
+        def readable?(admin, resource_name)
+          entry = DashboardRegistry.find(resource_name)
+          entry && authorized?(admin, entry.model_class, :index?)
         end
 
         def reject_unknown!(kind, given, allowed)

data/app/lib/administrate/mcp/base_tool.rb

@@ -5,6 +5,7 @@ module Administrate
     # Base class for all MCP tools — provides role gating, auditing, and response helpers.
     class BaseTool < ::MCP::Tool
       UnauthorizedError = Administrate::MCP::UnauthorizedError
+      ResourceForbiddenError = Administrate::MCP::ResourceForbiddenError
       InvalidArgumentError = Administrate::MCP::InvalidArgumentError
 
       class << self
@@ -26,11 +27,11 @@ module Administrate
 
         def call(server_context:, **args)
           instrument(server_context) { call_with_context(server_context, **args) }
+        rescue ResourceForbiddenError, InvalidArgumentError => e
+          error_response(e.message)
         rescue UnauthorizedError => e
           (server_context[:authorization_errors] ||= []).push(e.message)
           error_response(e.message)
-        rescue InvalidArgumentError => e
-          error_response(e.message)
         rescue StandardError => e
           error_response("Internal error: #{e.message}")
         end

data/app/lib/administrate/mcp/feedback_categories.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # The category list behind `Feedback#category` and the `report_mcp_improvement` schema, kept
+    # independent of the model so validation and the tool's input schema work whether or not the
+    # `administrate_mcp_feedbacks` table exists.
+    module FeedbackCategories
+      CATEGORIES = {
+        'description' => 0,
+        'missing_filter' => 1,
+        'missing_field' => 2,
+        'missing_resource' => 3,
+        'serialization' => 4,
+        'other' => 5
+      }.freeze
+    end
+  end
+end

data/app/lib/administrate/mcp/feedback_report.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Administrate
+  module MCP
+    # Plain report of an MCP improvement suggestion, handed to `config.on_feedback` whether or not
+    # `config.persist_feedback` is on. `record` and `api_key` are only set when it is, so a host that
+    # wants the persisted row can reach it; the report itself never needs the `Feedback` table to
+    # exist.
+    FeedbackReport = Struct.new(:admin, :category, :suggestion, :resource_name, :api_key, :record, keyword_init: true)
+  end
+end

data/app/lib/administrate/mcp/report_improvement.rb

@@ -2,9 +2,12 @@
 
 module Administrate
   module MCP
-    # Persists an MCP improvement suggestion and hands it to the host's `on_feedback` hook.
+    # Validates an MCP improvement suggestion and hands a plain report to the host's `on_feedback`
+    # hook. Persisting the report to the `Feedback` table is opt-in through `config.persist_feedback`;
+    # when that is off, nothing here touches `Feedback` or `ApiKey`, so a host that never turns it on
+    # need not carry the table at all.
     class ReportImprovement
-      Result = Struct.new(:success?, :feedback, :errors, keyword_init: true)
+      Result = Struct.new(:success?, :report, :errors, keyword_init: true)
 
       def self.call(...)
         new(...).call
@@ -19,11 +22,11 @@ module Administrate
 
       def call
         errors = validation_errors
-        return Result.new(success?: false, feedback: nil, errors:) if errors.any?
+        return Result.new(success?: false, report: nil, errors:) if errors.any?
 
-        feedback = create_feedback
-        notify(feedback)
-        Result.new(success?: true, feedback:, errors: [])
+        report = build_report
+        notify(report)
+        Result.new(success?: true, report:, errors: [])
       end
 
       private
@@ -32,13 +35,22 @@ module Administrate
 
       def validation_errors
         errors = []
-        unless Feedback.categories.key?(category.to_s)
-          errors << "category must be one of: #{Feedback.categories.keys.join(', ')}"
+        unless FeedbackCategories::CATEGORIES.key?(category.to_s)
+          errors << "category must be one of: #{FeedbackCategories::CATEGORIES.keys.join(', ')}"
         end
         errors << "suggestion can't be blank" if suggestion.blank?
         errors
       end
 
+      def build_report
+        record = create_feedback if persist_feedback?
+        FeedbackReport.new(admin:, category:, suggestion:, resource_name:, record:, api_key: record&.api_key)
+      end
+
+      def persist_feedback?
+        Administrate::MCP.config.persist_feedback
+      end
+
       def create_feedback
         Feedback.create!(admin:, api_key: latest_api_key, category:, resource_name:, suggestion:)
       end
@@ -47,9 +59,8 @@ module Administrate
         ApiKey.active.where(admin:).order(last_used_at: :desc).first
       end
 
-      # The feedback is already persisted; a broken notifier must not take the report down with it.
-      def notify(feedback)
-        Administrate::MCP.config.on_feedback.call(feedback)
+      def notify(report)
+        Administrate::MCP.config.on_feedback.call(report)
       rescue StandardError => e
         Administrate::MCP.config.on_error.call(e)
       end