otto 2.9.0 → 2.10.0

data/lib/otto/mcp/rate_limiting.rb

@@ -5,44 +5,152 @@
 require 'json'
 
 require_relative '../security/rate_limiting'
-
-begin
-  require 'rack/attack'
-rescue LoadError
-  # rack-attack is optional - graceful fallback
-end
+require_relative 'endpoint'
 
 class Otto
   module MCP
     # Rate limiter for MCP protocol endpoints
+    #
+    # Rack::Attack configuration is process-global and a throttle is keyed by
+    # name alone, so registering 'mcp_requests' for a second MCP app in the
+    # same process used to REPLACE the first app's throttle: the captured
+    # endpoint moved from /a to /b and /a stopped being rate limited. Each
+    # configured endpoint now gets its own throttle pair
+    # ('mcp_requests:/a', 'mcp_tool_calls:/a', ...) with its own limits, and
+    # every endpoint configured in the process is remembered in
+    # {.registered_endpoints} so the (single, global) throttled responder and
+    # log subscriber recognise all of them, not just the most recent.
+    #
+    # Known limitation: throttles are keyed by endpoint path, not by Otto
+    # instance. Two apps in one process that mount MCP on the SAME path (for
+    # example both on /_mcp behind a host or tenant dispatcher) share one
+    # throttle definition, so the limits configured last apply to both, and
+    # one set of per-client-IP counters. Use distinct endpoint paths per app.
     class RateLimiter < Otto::Security::RateLimiting
-      def self.configure_rack_attack!(config = {})
-        return unless defined?(Rack::Attack)
+      DEFAULT_HTTP_ENDPOINT = '/_mcp'
+
+      @endpoints       = Set.new
+      @endpoints_mutex = Mutex.new
+
+      class << self
+        # Every MCP endpoint configured via {.configure_rack_attack!} in this
+        # process, in configuration order.
+        # @return [Array<String>]
+        def registered_endpoints
+          @endpoints_mutex.synchronize { @endpoints.to_a }
+        end
+
+        # Forget every registered endpoint. Test isolation only: production
+        # configuration is additive for the life of the process, like
+        # Rack::Attack's own.
+        # @api private
+        def reset_endpoints!
+          @endpoints_mutex.synchronize { @endpoints.clear }
+        end
+
+        # @api private
+        def register_endpoint(endpoint)
+          return if endpoint.nil?
 
-        # Start with base configuration from general rate limiting
+          @endpoints_mutex.synchronize { @endpoints << endpoint }
+        end
+      end
+
+      def self.configure_rack_attack!(config = {})
+        # Start with base configuration from general rate limiting. The base
+        # configure_rack_attack! assigns the single Rack::Attack
+        # throttled_responder (dispatching to .throttled_response, overridden
+        # below) and calls .configure_logging (also overridden below), so this
+        # class registers no responder or subscriber of its own after super.
         super
 
-        # Add MCP-specific rules
+        register_endpoint(config[:mcp_http_endpoint])
         configure_mcp_rules(config)
-        configure_mcp_responses
-        configure_mcp_logging
+      end
+
+      # Resolve the MCP endpoint a Rack::Attack throttle should match against.
+      #
+      # Rack::Attack is mounted by the hosting app OUTSIDE Otto and runs before
+      # every Otto middleware, including the proc that sets
+      # env['otto.mcp_http_endpoint'], so inside a throttle that env key is
+      # absent. The endpoint therefore has to arrive with the configuration
+      # (Server#apply_rate_limits publishes it as :mcp_http_endpoint). The env
+      # key is kept as a fallback for callers that run Rack::Attack inside
+      # Otto's own stack, and the documented default closes the chain.
+      #
+      # @param configured [String, nil] endpoint from the rate limiting config
+      # @param env [Hash] the request env
+      # @return [String]
+      def self.mcp_endpoint_for(configured, env)
+        configured || env['otto.mcp_http_endpoint'] || DEFAULT_HTTP_ENDPOINT
+      end
+
+      # Whether a request targets ANY MCP endpoint configured in this process.
+      #
+      # Used by the throttled responder and the log subscriber, which are
+      # global (the last configuration wins) and so cannot capture a single
+      # endpoint the way a per-endpoint throttle can. Consults the registry at
+      # call time, then the env key, then the default when nothing is
+      # configured at all. A request matches only the exact endpoint path the
+      # router would dispatch to the MCP handler (see Otto::MCP.endpoint_path?),
+      # never a sibling that merely shares the prefix.
+      #
+      # Compares PATH_INFO, not Rack::Request#path (SCRIPT_NAME + PATH_INFO):
+      # the router dispatches on PATH_INFO, so under `map '/api' { run otto }`
+      # the MCP request for an endpoint at /_mcp arrives as SCRIPT_NAME=/api,
+      # PATH_INFO=/_mcp and the full path /api/_mcp never equals the endpoint.
+      #
+      # @param request [Rack::Attack::Request, #path_info, #env]
+      # @return [Boolean]
+      def self.mcp_request?(request)
+        candidates = registered_endpoints
+        env_endpoint = request.env['otto.mcp_http_endpoint']
+        candidates << env_endpoint if env_endpoint
+        candidates << DEFAULT_HTTP_ENDPOINT if candidates.empty?
+
+        candidates.any? { |endpoint| Otto::MCP.endpoint_path?(request.path_info, endpoint) }
+      end
+
+      # Name of the Rack::Attack throttle for +rule+ on +endpoint+.
+      #
+      # The endpoint is part of the name so that two MCP apps in one process
+      # get independent throttles (and independent counters: Rack::Attack keys
+      # the cache by throttle name). Without a configured endpoint the bare
+      # rule name is used and the block resolves the endpoint per request.
+      #
+      # @param rule [String] 'mcp_requests' or 'mcp_tool_calls'
+      # @param endpoint [String, nil]
+      # @return [String]
+      def self.throttle_name(rule, endpoint)
+        endpoint ? "#{rule}:#{endpoint}" : rule
       end
 
       def self.configure_mcp_rules(config)
-        # MCP endpoint requests - 60 per minute by default
+        # Captured once, outside the blocks: they run per request, long after
+        # this configuration hash is gone.
+        configured_endpoint = config[:mcp_http_endpoint]
+
+        # MCP endpoint requests - 60 per minute by default. Only the exact
+        # endpoint path counts: the router dispatches the MCP route by literal
+        # match, so a prefix match here would let /admin traffic exhaust (and be
+        # refused by) the counter for an endpoint at /a. PATH_INFO, not #path:
+        # a mount prefix (SCRIPT_NAME) is invisible to the router and must be
+        # invisible here too, or a mounted Otto is never throttled.
         mcp_requests_limit = config[:mcp_requests_per_minute] || 60
 
-        Rack::Attack.throttle('mcp_requests', limit: mcp_requests_limit, period: 60) do |request|
-          endpoint = request.env['otto.mcp_http_endpoint'] || '/_mcp'
-          request.ip if request.path.start_with?(endpoint)
+        Rack::Attack.throttle(throttle_name('mcp_requests', configured_endpoint),
+                              limit: mcp_requests_limit, period: 60) do |request|
+          endpoint = mcp_endpoint_for(configured_endpoint, request.env)
+          request.ip if Otto::MCP.endpoint_path?(request.path_info, endpoint)
         end
 
         # Tool calls are more expensive - 20 per minute by default
         tool_calls_limit = config[:tool_calls_per_minute] || 20
 
-        Rack::Attack.throttle('mcp_tool_calls', limit: tool_calls_limit, period: 60) do |request|
-          endpoint = request.env['otto.mcp_http_endpoint'] || '/_mcp'
-          if request.path.start_with?(endpoint) && request.post?
+        Rack::Attack.throttle(throttle_name('mcp_tool_calls', configured_endpoint),
+                              limit: tool_calls_limit, period: 60) do |request|
+          endpoint = mcp_endpoint_for(configured_endpoint, request.env)
+          if Otto::MCP.endpoint_path?(request.path_info, endpoint) && request.post?
             begin
               body = request.body.read
               data = JSON.parse(body)
@@ -56,91 +164,59 @@ class Otto
         end
       end
 
-      def self.configure_mcp_responses
-        # Override throttled responder to provide JSON-RPC formatted responses for MCP requests
-        Rack::Attack.throttled_responder = lambda do |request|
-          match_data = request.env['rack.attack.match_data']
-          now        = match_data[:epoch_time]
-
-          headers = {
-            'content-type' => 'application/json',
-            'retry-after' => (match_data[:period] - (now % match_data[:period])).to_s,
-          }
-
-          # Check if this is an MCP request
-          endpoint = request.env['otto.mcp_http_endpoint'] || '/_mcp'
-          if request.path.start_with?(endpoint)
-            # JSON-RPC error response for MCP
-            error_response = {
-              jsonrpc: '2.0',
-              id: nil,
-              error: {
-                code: -32_000,
-                message: 'Rate limit exceeded',
-                data: {
-                  retry_after: headers['retry-after'].to_i,
-                  limit: match_data[:limit],
-                  period: match_data[:period],
-                },
-              },
-            }
-            [429, headers, [JSON.generate(error_response)]]
-          else
-            # Use the general rate limiting response for non-MCP requests
-            # Route's response_type takes precedence over Accept header
-            route_def = request.env['otto.route_definition']
-            wants_json = (route_def&.response_type == 'json') ||
-                         request.env['HTTP_ACCEPT'].to_s.include?('application/json')
-
-            if wants_json
-              error_response = {
-                error: 'Rate limit exceeded',
-                message: 'Too many requests',
-                retry_after: headers['retry-after'].to_i,
-                limit: match_data[:limit],
-                period: match_data[:period],
-              }
-              [429, headers, [JSON.generate(error_response)]]
-            else
-              body                    = "Rate limit exceeded. Retry after #{headers['retry-after']} seconds."
-              headers['content-type'] = 'text/plain'
-              [429, headers, [body]]
-            end
-          end
-        end
+      # JSON-RPC formatted 429 for MCP requests; the general Otto response
+      # (route response_type, then Accept header) for everything else.
+      def self.throttled_response(request)
+        return super unless mcp_request?(request)
+
+        match_data = request.env['rack.attack.match_data']
+        headers    = throttle_headers(match_data)
+
+        error_response = {
+          jsonrpc: '2.0',
+          id: nil,
+          error: {
+            code: -32_000,
+            message: 'Rate limit exceeded',
+            data: {
+              retry_after: headers['retry-after'].to_i,
+              limit: match_data[:limit],
+              period: match_data[:period],
+            },
+          },
+        }
+        [429, headers, [JSON.generate(error_response)]]
       end
 
-      def self.configure_mcp_logging
+      # Keep one MCP-aware subscriber while allowing it to recognize every
+      # endpoint registered in this process.
+      def self.configure_logging
         return unless defined?(ActiveSupport::Notifications)
 
-        # Masked address only — see the note on the sibling subscriber in
-        # Otto::Security::RateLimiting.configure_rack_attack! (issue #219).
-        ActiveSupport::Notifications.subscribe('rack.attack') do |_name, _start, _finish, _request_id, payload|
-          req      = payload[:request]
-          endpoint = req.env['otto.mcp_http_endpoint'] || '/_mcp'
-          ip       = Otto::LoggingHelpers.privacy_safe_ip(req.env, req.ip)
-
-          if req.path.start_with?(endpoint)
-            Otto.logger.warn "[MCP] Rate limit #{payload[:match_type]} for #{ip}: #{payload[:matched]}"
-          else
-            Otto.logger.warn "[Otto] Rate limit #{payload[:match_type]} for #{ip}: #{payload[:matched]}"
-          end
+        ActiveSupport::Notifications.unsubscribe(@log_subscriber) if @log_subscriber
+        @log_subscriber = ActiveSupport::Notifications.subscribe('rack.attack') do |_name, _start, _finish, _request_id, payload|
+          log_throttled_request(payload)
         end
       end
+
+      # Masked address only — see the note on the base implementation in
+      # Otto::Security::RateLimiting (issue #219).
+      def self.log_throttled_request(payload)
+        req = payload[:request]
+        return super unless mcp_request?(req)
+
+        ip = Otto::LoggingHelpers.privacy_safe_ip(req.env, req.ip)
+        Otto.logger.warn "[MCP] Rate limit #{payload[:match_type]} for #{ip}: #{payload[:matched]}"
+      end
     end
 
     # Middleware for applying rate limits to MCP protocol endpoints
     class RateLimitMiddleware < Otto::Security::RateLimitMiddleware
       def initialize(app, security_config = nil)
-        @app                    = app
-        @security_config        = security_config
-        @rate_limiter_available = defined?(Rack::Attack)
-
-        if @rate_limiter_available
-          configure_mcp_rate_limiting
-        else
-          Otto.logger.warn '[MCP] rack-attack not available - rate limiting disabled'
-        end
+        @app             = app
+        @security_config = security_config
+
+        configure_mcp_rate_limiting
       end
 
       private
@@ -149,11 +225,13 @@ class Otto
         # Get base configuration from security config
         base_config = @security_config&.rate_limiting_config || {}
 
-        # Add MCP-specific defaults
-        mcp_config = base_config.merge({
-                                         mcp_requests_per_minute: 60,
+        # MCP defaults, overridden by anything the security config carries
+        # (Server#apply_rate_limits publishes the configured limits and the
+        # endpoint there).
+        mcp_config = {
+          mcp_requests_per_minute: 60,
           tool_calls_per_minute: 20,
-                                       })
+        }.merge(base_config)
 
         RateLimiter.configure_rack_attack!(mcp_config)
       end

data/lib/otto/mcp/registry.rb

@@ -3,6 +3,7 @@
 # frozen_string_literal: true
 
 require_relative '../security/constant_resolver'
+require_relative 'errors'
 
 class Otto
   module MCP
@@ -57,24 +58,23 @@ class Otto
         resource = @resources[uri]
         return nil unless resource
 
-        begin
-          content = resource[:handler].call
-          {
-            contents: [{
-              uri: uri,
-              mimeType: resource[:mimeType],
-              text: content.to_s,
-            }],
-          }
-        rescue StandardError => e
-          Otto.logger.error "[MCP] Resource read error for #{uri}: #{e.message}"
-          nil
-        end
+        # A handler that blows up propagates: it is an execution fault
+        # (-32603/500), not a missing resource (-32001/404). Returning nil
+        # here previously made the two indistinguishable to the protocol,
+        # which owns the logging (Protocol#handle_resources_read).
+        content = resource[:handler].call
+        {
+          contents: [{
+            uri: uri,
+            mimeType: resource[:mimeType],
+            text: content.to_s,
+          }],
+        }
       end
 
       def call_tool(name, arguments, env)
         tool = @tools[name]
-        raise "Tool not found: #{name}" unless tool
+        raise ToolNotFoundError, "Tool not found: #{name}" unless tool
 
         handler = tool[:handler]
         if handler.respond_to?(:call)

data/lib/otto/mcp/schema_validation.rb

@@ -4,11 +4,8 @@
 
 require 'json'
 
-begin
-  require 'json_schemer'
-rescue LoadError
-  # json_schemer is optional - graceful fallback
-end
+require_relative '../optional_dependency'
+require_relative 'endpoint'
 
 class Otto
   module MCP
@@ -16,14 +13,24 @@ class Otto
 
     # JSON Schema validator for MCP protocol requests
     class Validator
+      JSON_SCHEMER_REQUIREMENT = '~> 2.0'
+
+      def self.ensure_available!
+        Otto::OptionalDependency.require!(
+          'json_schemer',
+          JSON_SCHEMER_REQUIREMENT,
+          require_path: 'json_schemer',
+          feature: 'MCP JSON Schema validation',
+          alternative: 'Or pass `enable_validation: false` when enabling MCP.'
+        )
+      end
+
       def initialize
-        @schemas                = {}
-        @json_schemer_available = defined?(JSONSchemer)
+        self.class.ensure_available!
+        @schemas = {}
       end
 
       def validate_request(data)
-        return true unless @json_schemer_available
-
         schema            = mcp_request_schema
         validation_errors = schema.validate(data).to_a
 
@@ -36,7 +43,7 @@ class Otto
       end
 
       def validate_tool_arguments(tool_name, arguments, schema)
-        return true unless @json_schemer_available && schema
+        return true unless schema
 
         schemer           = JSONSchemer.schema(schema)
         validation_errors = schemer.validate(arguments).to_a
@@ -100,10 +107,11 @@ class Otto
 
       private
 
+      # Exact endpoint only, normalized as the router normalizes it (see
+      # Otto::MCP.endpoint_path?); sibling paths are never parsed or rejected.
       def mcp_endpoint?(env)
         endpoint = env['otto.mcp_http_endpoint'] || '/_mcp'
-        path     = env['PATH_INFO'].to_s
-        path.start_with?(endpoint)
+        Otto::MCP.endpoint_path?(env['PATH_INFO'], endpoint)
       end
 
       def validation_error_response(id, message)

data/lib/otto/mcp/server.rb

@@ -8,6 +8,7 @@ require_relative 'route_parser'
 require_relative 'auth/token'
 require_relative 'schema_validation'
 require_relative 'rate_limiting'
+require_relative 'options'
 require_relative '../security/constant_resolver'
 
 class Otto
@@ -16,18 +17,67 @@ class Otto
     class Server
       attr_reader :protocol, :otto_instance
 
+      # Normalize raw options into the canonical MCP option hash.
+      #
+      # @param opts [Hash] raw options
+      # @param scope [Symbol] :explicit (strict, for #enable_mcp!) or
+      #   :constructor (ignores non-MCP keys, for Otto.new)
+      # @see Otto::MCP::Options.normalize
+      def self.normalize_options(opts = {}, scope = :explicit)
+        Otto::MCP::Options.normalize(opts, scope)
+      end
+
       def initialize(otto_instance)
         @otto_instance = otto_instance
         @protocol      = Protocol.new(otto_instance)
         @enabled       = false
       end
 
+      # Warning emitted when the MCP HTTP endpoint is exposed with no token
+      # authentication. Unconditional (not gated on Otto.debug): an
+      # unauthenticated MCP endpoint lets any caller invoke every registered
+      # tool, so it must be visible in normal boot output.
+      UNAUTHENTICATED_WARNING = <<~MSG.gsub(/\s+/, ' ').strip.freeze
+        [MCP] HTTP endpoint %s is enabled without authentication:
+        any caller can list and invoke MCP tools and resources.
+        Pass auth_tokens: ['<token>'] to require a bearer token, or
+        allow_unauthenticated: true to acknowledge this intentionally.
+      MSG
+
+      # Enable the MCP server.
+      #
+      # Enabling is one-shot. Each call appends a route, an endpoint-setting
+      # proc and the MCP middleware to the Otto instance without removing the
+      # previous set, so a second call with a different endpoint would leave
+      # the first endpoint routed but guarded by nothing (the auth middleware
+      # only matches the newest endpoint). Rather than try to unwind that,
+      # a second call raises.
+      #
+      # @param options [Hash] canonical or aliased options; normalized via
+      #   {.normalize_options}, so both the canonical keys (:http_endpoint,
+      #   :auth_tokens, ...) and their mcp_-prefixed spellings
+      #   (:mcp_endpoint, :mcp_auth_tokens, ...) are accepted.
+      # @raise [ArgumentError] if the server is already enabled
       def enable!(options = {})
-        @enabled              = true
-        @http_endpoint        = options.fetch(:http_endpoint, '/_mcp')
-        @auth_tokens          = options[:auth_tokens] || []
-        @enable_validation    = options.fetch(:enable_validation, true)
-        @enable_rate_limiting = options.fetch(:enable_rate_limiting, true)
+        if @enabled
+          raise ArgumentError,
+                "MCP server is already enabled on #{@http_endpoint}; pass all MCP options " \
+                'in a single Otto.new or enable_mcp! call'
+        end
+
+        options = self.class.normalize_options(options)
+
+        Validator.ensure_available! if options[:enable_validation]
+        Otto::Security::RateLimiting.ensure_available! if options[:enable_rate_limiting]
+
+        @enabled               = true
+        @http_endpoint         = options[:http_endpoint]
+        @auth_tokens           = options[:auth_tokens]
+        @enable_validation     = options[:enable_validation]
+        @enable_rate_limiting  = options[:enable_rate_limiting]
+        @allow_unauthenticated = options[:allow_unauthenticated]
+
+        apply_rate_limits(options)
 
         # Configure middleware
         configure_middleware(options)
@@ -35,6 +85,8 @@ class Otto
         # Add MCP endpoint route to Otto
         add_mcp_endpoint_route
 
+        warn_if_unauthenticated!
+
         Otto.logger.info "[MCP] Server enabled with HTTP endpoint: #{@http_endpoint}" if Otto.debug
       end
 
@@ -53,42 +105,82 @@ class Otto
 
       private
 
+      # Publish the per-minute limits under the keys RateLimitMiddleware /
+      # RateLimiter.configure_rack_attack! already read, via Otto's sanctioned
+      # rate-limiting configuration entry point. Before this, the values passed
+      # to enable! were dead and the hardcoded 60/20 always won.
+      #
+      # The endpoint travels with them. Rack::Attack is mounted by the host app
+      # OUTSIDE Otto and runs before any of Otto's middleware, so the
+      # env['otto.mcp_http_endpoint'] set by add_mcp_endpoint_route is not yet
+      # present when the throttles are evaluated; without this, a custom
+      # endpoint was compared against the '/_mcp' fallback and never throttled.
+      def apply_rate_limits(options)
+        return unless @enable_rate_limiting
+
+        @otto_instance.configure_rate_limiting(
+          mcp_http_endpoint: @http_endpoint,
+          mcp_requests_per_minute: options[:requests_per_minute],
+          tool_calls_per_minute: options[:tools_per_minute]
+        )
+      end
+
+      def warn_if_unauthenticated!
+        return if @auth_tokens.any? || @allow_unauthenticated
+
+        Otto.logger.warn format(UNAUTHENTICATED_WARNING, @http_endpoint)
+      end
+
       def configure_middleware(_options)
-        # Configure middleware in security-optimal order using explicit positioning:
-        # 1. Rate limiting (reject excessive requests early) - position: :first
-        # 2. Authentication (validate credentials before parsing) - default append
-        # 3. Validation (expensive JSON schema validation last) - position: :last
+        # Target EXECUTION order (outermost first, i.e. what a request meets in
+        # turn), security-optimal:
+        #   1. Rate limiting  — shed excessive load before spending any work
+        #   2. Authentication — reject anonymous callers before parsing bodies
+        #   3. Validation     — expensive JSON schema check only on requests
+        #                       that already proved themselves
+        #
+        # MiddlewareStack stores entries in the REVERSE of execution order
+        # (#wrap folds with reduce, so a later array entry is a further-out
+        # wrapper). Registration therefore runs innermost-first: validation is
+        # pinned :innermost, then auth is appended, then rate limiting. The
+        # previous code read the positions as execution order and produced the
+        # exact inverse — validation ran ahead of auth, so unauthenticated
+        # callers reached the schema validator.
 
         middleware = @otto_instance.instance_variable_get(:@middleware)
 
-        # Configure rate limiting first (explicit position for clarity)
-        if @enable_rate_limiting
+        # Innermost (last to execute): schema validation, closest to the app.
+        if @enable_validation
           middleware.add_with_position(
-            Otto::MCP::RateLimitMiddleware,
-            @otto_instance.security_config,
-            position: :first
+            Otto::MCP::SchemaValidationMiddleware,
+            position: :innermost
           )
-          Otto.logger.debug '[MCP] Rate limiting enabled (position: first)' if Otto.debug
+          Otto.logger.debug '[MCP] Schema validation enabled (executes last)' if Otto.debug
         end
 
-        # Configure authentication second (default append order)
+        # Middle: authentication, outside validation and inside rate limiting.
         if @auth_tokens.any?
           @auth = Otto::MCP::Auth::TokenAuth.new(@auth_tokens)
           @otto_instance.security_config.mcp_auth = @auth
-          @otto_instance.use Otto::MCP::Auth::TokenMiddleware
-          Otto.logger.debug '[MCP] Token authentication enabled' if Otto.debug
+          # Pass security_config explicitly: TokenMiddleware is not in
+          # MiddlewareStack#middleware_needs_config?, so #wrap would build it
+          # with a nil config and — now that the middleware fails closed —
+          # reject every request, valid token included.
+          @otto_instance.use Otto::MCP::Auth::TokenMiddleware, @otto_instance.security_config
+          Otto.logger.debug '[MCP] Token authentication enabled (executes after rate limiting)' if Otto.debug
         end
 
-        # Configure validation last (explicit position for clarity)
-        return unless @enable_validation
-
-        middleware.add_with_position(
-          Otto::MCP::SchemaValidationMiddleware,
-          position: :last
-        )
-        Otto.logger.debug '[MCP] Schema validation enabled (position: last)' if Otto.debug
+        # Outermost of the three (first to execute): rate limiting.
+        if @enable_rate_limiting
+          middleware.add_with_position(
+            Otto::MCP::RateLimitMiddleware,
+            @otto_instance.security_config,
+            position: :last
+          )
+          Otto.logger.debug '[MCP] Rate limiting enabled (executes first)' if Otto.debug
+        end
 
-        # Validate middleware order (should pass with explicit positioning)
+        # Validate execution order (should pass with the positioning above).
         warnings = middleware.validate_mcp_middleware_order
         warnings.each { |warning| Otto.logger.warn warning }
       end
@@ -102,13 +194,20 @@ class Otto
         @otto_instance.routes[:POST] ||= []
         @otto_instance.routes[:POST] << mcp_route
 
-        @otto_instance.routes_literal[:POST]               ||= {}
-        @otto_instance.routes_literal[:POST][@http_endpoint] = mcp_route
-
-        # Ensure env carries endpoint for middlewares
+        # Keyed by the normalized path, as the router keys every literal route
+        # and normalizes PATH_INFO before the lookup: a configured trailing
+        # slash ('/a/') or the root ('/') otherwise registers a key the lookup
+        # can never hit, while Otto::MCP.endpoint_path? still claims the path.
+        @otto_instance.routes_literal[:POST] ||= {}
+        @otto_instance.routes_literal[:POST][Otto::Utils.normalize_path(@http_endpoint)] = mcp_route
+
+        # Ensure env carries endpoint for middlewares. Close over a local copy:
+        # the proc must keep announcing the endpoint it was registered for even
+        # if the ivar is ever reassigned.
+        endpoint = @http_endpoint
         @otto_instance.use proc { |app|
           lambda { |env|
-            env['otto.mcp_http_endpoint'] = @http_endpoint
+            env['otto.mcp_http_endpoint'] = endpoint
             app.call(env)
           }
         }