vector_mcp 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19883e6171b2fc442256036ec7841130c8ef557f7b5a58c354aa3880c6910907
-  data.tar.gz: 4e5d96fe5172319af0af30f8118704c469ccb9bfc543dead9907b4c42a0b0373
+  metadata.gz: b00aa3c214f8fcdd9906a9c349b8b871c0f3ab8fb9463d198e007d28783fe43d
+  data.tar.gz: 6053bad04ea796b29312812a4ac6e1c0dcf1ba2a9bc292cfd902e5e3793d78cb
 SHA512:
-  metadata.gz: 276a4391c46cce453ecda4cdb1582f19b0b06f762a737c30e2369bdc4a3e42f6a95f83eef46b62e9cded7e4be28095f780bf0bc8edcfe2f533fea449cabd9e6e
-  data.tar.gz: d57ebbcbd8d8bc3cbbbf110aa3b669ef54ba41fbdcc848f3dd06b2f3bc1610b6be7552ff67d3dd6467498d6240b9e0b761096d0f138656e5a189d4fdd48fac5f
+  metadata.gz: b5eec0da560953e468c81b7af75dd5f3274dce64617e287f085a70327c83ff2085ed6a30012cf9fbd27638c1e415ce8b40e77fb6f61b20a779b5b9bd48f1c47b
+  data.tar.gz: ff5cd45eb8237ccddc953811fafa1912c0dbd4b0a0afd03bd373107614e1552a675e2e710d43aefd4f8dd693e46c3e89fd16d964917012e5a6379ff813ff2948

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## [0.7.1] – 2026-08-16
+
+### Security
+
+* Authentication now covers `prompts/get` and all tool, resource, prompt, and root catalog list requests when authentication is enabled.
+* Prompt/root authorization policies are enforced; list policies filter denied catalog entries without disclosing them.
+* HTTP Stream POST bodies are capped at 16 MiB by default, with a configurable `max_body_bytes:` limit and `413 Payload Too Large` responses.
+* Authentication is enforced at the shared dispatcher for every registered request and notification handler except the explicit public handshake methods (`initialize`, `ping`, and `initialized`). HTTP GET/DELETE operations also require credentials outside OAuth resource-server mode.
+* The unsupported `prompts/subscribe` placeholder and its unbounded retained-session array were removed.
+* Authentication can now enable a bounded, thread-safe failure limiter with `rate_limit:`. It tracks client IPs and credential fingerprints, emits structured security events, resets matching counters after success, and returns `429`/`Retry-After` after repeated failures.
+
 ## [0.7.0] – 2026-08-15
 
 ### Removed (deprecated in 0.6.0)

data/README.md

@@ -188,7 +188,8 @@ VectorMCP keeps security opt-in, but the primitives are built in:
 ```ruby
 server.enable_authentication!(
   strategy: :api_key,
-  keys: ["your-secret-key"]
+  keys: [ENV.fetch("MCP_API_KEY")],
+  rate_limit: { max_attempts: 10, window_seconds: 60 }
 )
 
 server.enable_authorization! do
@@ -208,6 +209,10 @@ server.enable_authentication!(strategy: :custom) do |request|
 end
 ```
 
+When authentication is enabled, VectorMCP applies it centrally to built-in and custom request/notification handlers. Only `initialize`, `ping`, and the `initialized` notification are public; HTTP GET streams and DELETE session requests also require credentials.
+
+For public deployments, enable authentication failure limiting with `rate_limit: true` (10 attempts per 60 seconds by default), or provide `max_attempts`, `window_seconds`, and `max_entries`. Repeated failures are tracked by client IP and a one-way credential fingerprint; blocked requests return HTTP `429`, JSON-RPC `-32029`, and `Retry-After`. The limiter is in-process, so multi-process or distributed deployments should also enforce a shared limit at the proxy or gateway. Generate API keys with at least 256 bits of entropy—for example, `ruby -rsecurerandom -e 'puts SecureRandom.hex(32)'`—and load them from a secret manager or environment variable.
+
 For MCP clients that speak OAuth 2.1 (e.g. Claude Desktop), pass a `resource_metadata_url:` to turn on RFC 9728 discovery. Unauthenticated requests to `/mcp` return `401` with a `WWW-Authenticate` header pointing at the configured metadata document, and the client drives the rest of the OAuth dance automatically. See [docs/oauth_resource_server.md](./docs/oauth_resource_server.md) for the feature reference and [docs/rails_oauth_integration.md](./docs/rails_oauth_integration.md) for a full Rails + Doorkeeper recipe.
 
 Middleware can hook into tool, resource, prompt, sampling, auth, and transport events, including `before_auth`, `after_auth`, `on_auth_error`, `before_request`, `after_response`, and `on_transport_error`.
@@ -237,6 +242,8 @@ anonymizer.install_on(server)
 - `DELETE /mcp` terminates the session
 - The server advertises MCP protocol `2025-11-25` and accepts `2025-03-26` and `2024-11-05` headers for compatibility
 - Default allowed origins are restricted to localhost and loopback addresses
+- POST bodies are capped at 16 MiB by default; configure `max_body_bytes:` on `run` or `rack_app` when needed
+- For mounted Rack apps, configure the same limit in the fronting web server or reverse proxy so requests are rejected before Rack buffering
 
 Initialize a session with curl:
 

data/lib/vector_mcp/errors.rb

@@ -4,6 +4,16 @@ module VectorMCP
   # Base error class for all VectorMCP specific errors.
   class Error < StandardError; end
 
+  # Raised when an HTTP request body exceeds the transport's configured limit.
+  class PayloadTooLargeError < Error
+    attr_reader :max_bytes
+
+    def initialize(max_bytes)
+      @max_bytes = max_bytes
+      super("Request body exceeds the maximum allowed size of #{max_bytes} bytes")
+    end
+  end
+
   # Base class for **all** JSON-RPC 2.0 errors that the VectorMCP library can
   # emit.  It mirrors the structure defined by the JSON-RPC spec and adds a
   # flexible `details` field that implementers may use to attach structured,
@@ -187,6 +197,24 @@ module VectorMCP
     end
   end
 
+  # Represents an authentication attempt blocked by the configured limiter (-32029).
+  class RateLimitExceededError < ServerError
+    attr_reader :retry_after
+
+    # @param message [String] The error message.
+    # @param retry_after [Integer] Seconds until the caller should retry.
+    # @param request_id [String, Integer, nil] The ID of the originating request.
+    def initialize(message = "Too many authentication attempts", retry_after:, request_id: nil)
+      @retry_after = retry_after
+      super(
+        message,
+        code: -32_029,
+        details: { retry_after: retry_after },
+        request_id: request_id
+      )
+    end
+  end
+
   # Represents an authorization failed error (-32403).
   # Indicates the authenticated user does not have permission to perform the requested action.
   class ForbiddenError < ProtocolError

data/lib/vector_mcp/handlers/core.rb

@@ -4,6 +4,7 @@ require "json"
 require "uri"
 require "json-schema"
 require_relative "../middleware"
+require_relative "../security/request_authenticator"
 
 module VectorMCP
   module Handlers
@@ -28,13 +29,16 @@ module VectorMCP
       # Handles the `tools/list` request.
       #
       # @param _params [Hash] The request parameters (ignored).
-      # @param _session [VectorMCP::Session] The current session (ignored).
+      # @param session [VectorMCP::Session] The current session.
       # @param server [VectorMCP::Server] The server instance.
       # @return [Hash] A hash containing an array of tool definitions.
       #   Example: `{ tools: [ { name: "my_tool", ... } ] }`
-      def self.list_tools(_params, _session, server)
+      def self.list_tools(_params, session, server)
+        session_context = authenticate_request!(session, server, operation_type: :tool_list, operation_name: "tools/list")
+        tools = filter_authorized_items(server.tools.values, session_context, server)
+
         {
-          tools: server.tools.values.map(&:as_mcp_definition)
+          tools: tools.map(&:as_mcp_definition)
         }
       end
 
@@ -79,13 +83,16 @@ module VectorMCP
       # Handles the `resources/list` request.
       #
       # @param _params [Hash] The request parameters (ignored).
-      # @param _session [VectorMCP::Session] The current session (ignored).
+      # @param session [VectorMCP::Session] The current session.
       # @param server [VectorMCP::Server] The server instance.
       # @return [Hash] A hash containing an array of resource definitions.
       #   Example: `{ resources: [ { uri: "memory://data", name: "My Data", ... } ] }`
-      def self.list_resources(_params, _session, server)
+      def self.list_resources(_params, session, server)
+        session_context = authenticate_request!(session, server, operation_type: :resource_list, operation_name: "resources/list")
+        resources = filter_authorized_items(server.resources.values, session_context, server)
+
         {
-          resources: server.resources.values.map(&:as_mcp_definition)
+          resources: resources.map(&:as_mcp_definition)
         }
       end
 
@@ -129,14 +136,17 @@ module VectorMCP
       # If the server supports dynamic prompt lists, this clears the `listChanged` flag.
       #
       # @param _params [Hash] The request parameters (ignored).
-      # @param _session [VectorMCP::Session] The current session (ignored).
+      # @param session [VectorMCP::Session] The current session.
       # @param server [VectorMCP::Server] The server instance.
       # @return [Hash] A hash containing an array of prompt definitions.
       #   Example: `{ prompts: [ { name: "my_prompt", ... } ] }`
-      def self.list_prompts(_params, _session, server)
+      def self.list_prompts(_params, session, server)
+        session_context = authenticate_request!(session, server, operation_type: :prompt_list, operation_name: "prompts/list")
+        prompts = filter_authorized_items(server.prompts.values, session_context, server)
+
         # Once the list is supplied, clear the listChanged flag
         result = {
-          prompts: server.prompts.values.map(&:as_mcp_definition)
+          prompts: prompts.map(&:as_mcp_definition)
         }
         server.clear_prompts_list_changed if server.respond_to?(:clear_prompts_list_changed)
         result
@@ -146,38 +156,28 @@ module VectorMCP
       # Returns the list of available roots and clears the `listChanged` flag.
       #
       # @param _params [Hash] The request parameters (ignored).
-      # @param _session [VectorMCP::Session] The current session (ignored).
+      # @param session [VectorMCP::Session] The current session.
       # @param server [VectorMCP::Server] The server instance.
       # @return [Hash] A hash containing an array of root definitions.
       #   Example: `{ roots: [ { uri: "file:///path/to/dir", name: "My Project" } ] }`
-      def self.list_roots(_params, _session, server)
+      def self.list_roots(_params, session, server)
+        session_context = authenticate_request!(session, server, operation_type: :root_list, operation_name: "roots/list")
+        roots = filter_authorized_items(server.roots.values, session_context, server)
+
         # Once the list is supplied, clear the listChanged flag
         result = {
-          roots: server.roots.values.map(&:as_mcp_definition)
+          roots: roots.map(&:as_mcp_definition)
         }
         server.clear_roots_list_changed if server.respond_to?(:clear_roots_list_changed)
         result
       end
 
-      # Handles the `prompts/subscribe` request (placeholder).
-      # This implementation is a simple acknowledgement.
-      #
-      # @param _params [Hash] The request parameters (ignored).
-      # @param session [VectorMCP::Session] The current session.
-      # @param server [VectorMCP::Server] The server instance.
-      # @return [Hash] An empty hash.
-      def self.subscribe_prompts(_params, session, server)
-        # Use private helper via send to avoid making it public
-        server.send(:subscribe_prompts, session) if server.respond_to?(:send)
-        {}
-      end
-
       # Handles the `prompts/get` request.
       # Validates arguments and the structure of the prompt handler's response.
       #
       # @param params [Hash] The request parameters.
       #   Expected keys: "name" (String), "arguments" (Hash, optional).
-      # @param _session [VectorMCP::Session] The current session (ignored).
+      # @param session [VectorMCP::Session] The current session.
       # @param server [VectorMCP::Server] The server instance.
       # @return [Hash] The result from the prompt's handler, which should conform to MCP's GetPromptResult.
       # @raise [VectorMCP::NotFoundError] if the prompt name is not found.
@@ -196,30 +196,8 @@ module VectorMCP
           metadata: { start_time: Time.now }
         )
 
-        # Execute before_prompt_get hooks
-        context = server.middleware_manager.execute_hooks(:before_prompt_get, context)
-        return handle_middleware_error(context) if context.error?
-
         begin
-          context_params = context.params
-          prompt_name = context_params["name"] || prompt_name
-          prompt = fetch_prompt(prompt_name, server)
-
-          arguments = context_params["arguments"] || {}
-          validate_prompt_arguments!(prompt_name, prompt, arguments)
-
-          # Call the registered handler after arguments were validated
-          result_data = prompt.handler.call(arguments)
-
-          validate_prompt_response!(prompt_name, result_data, server)
-
-          # Set result in context
-          context.result = result_data
-
-          # Execute after_prompt_get hooks
-          context = server.middleware_manager.execute_hooks(:after_prompt_get, context)
-
-          context.result
+          execute_prompt_request(context, prompt_name, session, server)
         rescue StandardError => e
           # Set error in context and execute error hooks
           context.error = e
@@ -405,13 +383,7 @@ module VectorMCP
       # @param session [VectorMCP::Session] The current session
       # @return [VectorMCP::RequestContext] Request context for security middleware
       def self.extract_auth_credentials(session)
-        # All sessions should have a request_context - this is enforced by Session initialization
-        unless session.respond_to?(:request_context) && session.request_context
-          raise VectorMCP::InternalError,
-                "Session missing request_context - transport layer integration error. Session ID: #{session.id}"
-        end
-
-        session.request_context
+        VectorMCP::Security::RequestAuthenticator.request_context_for(session)
       end
       private_class_method :extract_auth_credentials
 
@@ -452,23 +424,12 @@ module VectorMCP
 
       # Authenticate the current request and return the caller's identity.
       def self.authenticate_request!(session, server, operation_type:, operation_name:)
-        request = extract_auth_credentials(session)
-        # before_auth middleware hooks see (and may modify) the request as a hash;
-        # AuthManager coerces it back into a RequestContext at its boundary.
-        context = create_auth_context(operation_type, operation_name, request.to_h, session, server)
-        context = server.middleware_manager.execute_hooks(:before_auth, context)
-        raise context.error if context.error?
-
-        session_context = server.security_middleware.authenticate_request(context.params)
-        session.security_context = session_context
-
-        raise VectorMCP::UnauthorizedError, "Authentication required" if server.auth_manager.required? && !session_context.authenticated?
-
-        context.result = session_context
-        server.middleware_manager.execute_hooks(:after_auth, context)
-        session_context
-      rescue StandardError => e
-        handle_auth_error(e, context, server)
+        VectorMCP::Security::RequestAuthenticator.authenticate!(
+          session,
+          server,
+          operation_type: operation_type,
+          operation_name: operation_name
+        )
       end
 
       # Execute tool handler with proper arity handling
@@ -525,6 +486,35 @@ module VectorMCP
         raise VectorMCP::ForbiddenError, "Access denied"
       end
 
+      # Filter catalog entries through their registered authorization policy.
+      # Listing intentionally omits denied items instead of revealing their existence.
+      def self.filter_authorized_items(items, session_context, server)
+        items.select do |item|
+          server.security_middleware.authorize_action(session_context, :list, item)
+        end
+      end
+
+      # Authenticate, authorize, validate, and execute a prompt request.
+      def self.execute_prompt_request(context, prompt_name, session, server)
+        session_context = authenticate_request!(session, server, operation_type: :prompt_get, operation_name: prompt_name)
+
+        context = server.middleware_manager.execute_hooks(:before_prompt_get, context)
+        return handle_middleware_error(context) if context.error?
+
+        context_params = context.params
+        prompt_name = context_params["name"] || prompt_name
+        prompt = fetch_prompt(prompt_name, server)
+        authorize_action!(session_context, :get, prompt, server)
+
+        arguments = context_params["arguments"] || {}
+        validate_prompt_arguments!(prompt_name, prompt, arguments)
+        result_data = prompt.handler.call(arguments)
+        validate_prompt_response!(prompt_name, result_data, server)
+
+        context.result = result_data
+        server.middleware_manager.execute_hooks(:after_prompt_get, context).result
+      end
+
       # Execute resource handler with proper arity handling.
       # The second argument is the per-request invocation, which also exposes
       # the SessionContext auth API for handlers written against the legacy
@@ -555,32 +545,11 @@ module VectorMCP
         context.result
       end
 
-      # Create middleware context for authentication hooks.
-      def self.create_auth_context(operation_type, operation_name, request, session, server)
-        VectorMCP::Middleware::Context.new(
-          operation_type: operation_type,
-          operation_name: operation_name,
-          params: request,
-          session: session,
-          server: server,
-          metadata: { start_time: Time.now }
-        )
-      end
-
-      # Run auth error hooks and re-raise the original error.
-      def self.handle_auth_error(error, context, server)
-        return raise error unless context
-
-        context.error = error
-        server.middleware_manager.execute_hooks(:on_auth_error, context)
-        raise error
-      end
-
       private_class_method :handle_middleware_error, :create_tool_context, :find_tool!, :authenticate_request!,
                            :execute_tool_handler, :build_tool_result, :handle_tool_error, :create_resource_context,
-                           :find_resource!, :authorize_action!, :execute_resource_handler,
-                           :process_resource_content, :handle_resource_error, :create_auth_context,
-                           :handle_auth_error
+                           :find_resource!, :authorize_action!, :filter_authorized_items, :execute_prompt_request,
+                           :execute_resource_handler,
+                           :process_resource_content, :handle_resource_error
     end
   end
 end

data/lib/vector_mcp/invocation.rb

@@ -29,7 +29,7 @@ module VectorMCP
     attr_reader :request_context
 
     # @return [VectorMCP::Security::SessionContext] the security context resolved for this request
-    attr_accessor :security_context
+    attr_reader :security_context
 
     def_delegators :@session,
                    :id, :server, :transport, :data,
@@ -53,6 +53,19 @@ module VectorMCP
       @session = session
       @request_context = request_context ? RequestContext.coerce(request_context) : session.request_context
       @security_context = Security::SessionContext.anonymous
+      @authentication_resolved = false
+    end
+
+    # Store the identity resolved for this invocation. Assigning a context marks
+    # authentication as complete even when the resolved identity is anonymous.
+    def security_context=(context)
+      @security_context = context
+      @authentication_resolved = true
+    end
+
+    # @return [Boolean] whether authentication has run for this invocation
+    def authentication_resolved?
+      @authentication_resolved
     end
 
     # Replace this request's context (e.g. from middleware).
@@ -90,9 +103,8 @@ module VectorMCP
       @request_context.param(name)
     end
 
-    # Invocations compare by their underlying session, so collections that
-    # deduplicate sessions (e.g. prompt subscribers) treat every request
-    # view of one session as the same subscriber.
+    # Invocations compare by their underlying session so request-scoped views
+    # retain the identity semantics of that shared session.
     def ==(other)
       other_session = other.is_a?(Invocation) ? other.session : other
       @session == other_session

data/lib/vector_mcp/security/authentication_rate_limiter.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "../errors"
+require_relative "../request_context"
+
+module VectorMCP
+  module Security
+    # In-process limiter for repeated authentication failures.
+    #
+    # Attempts are tracked independently by transport-provided remote address
+    # and by a SHA-256 fingerprint of the presented credential. Raw credentials
+    # are never retained. Storage is bounded to avoid turning the limiter into a
+    # memory-exhaustion primitive.
+    class AuthenticationRateLimiter
+      DEFAULT_MAX_ATTEMPTS = 10
+      DEFAULT_WINDOW_SECONDS = 60
+      DEFAULT_MAX_ENTRIES = 10_000
+
+      CREDENTIAL_HEADERS = %w[Authorization X-API-Key X-JWT-Token].freeze
+      CREDENTIAL_PARAMS = %w[api_key apikey jwt_token token].freeze
+
+      attr_reader :max_attempts, :window_seconds, :max_entries
+
+      # @param max_attempts [Integer] failures allowed per identifier and window
+      # @param window_seconds [Numeric] rolling failure window in seconds
+      # @param max_entries [Integer] maximum number of tracked identifiers
+      # @param clock [#call, nil] monotonic time source (primarily for testing)
+      def initialize(max_attempts: DEFAULT_MAX_ATTEMPTS,
+                     window_seconds: DEFAULT_WINDOW_SECONDS,
+                     max_entries: DEFAULT_MAX_ENTRIES,
+                     clock: nil)
+        validate_positive_integer!(:max_attempts, max_attempts)
+        validate_positive_number!(:window_seconds, window_seconds)
+        validate_positive_integer!(:max_entries, max_entries)
+
+        @max_attempts = max_attempts
+        @window_seconds = window_seconds
+        @max_entries = max_entries
+        @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        @attempts = {}
+        @mutex = Mutex.new
+        @logger = VectorMCP.logger_for("security.auth_rate_limit")
+      end
+
+      # Atomically reserve an attempt, raising when any request identifier is blocked.
+      # @param request [VectorMCP::RequestContext, Hash] incoming request context
+      # @return [void]
+      # @raise [VectorMCP::RateLimitExceededError]
+      def check!(request)
+        context = VectorMCP::RequestContext.coerce(request)
+        current_time = now
+        identifiers = request_identifiers(context)
+        retry_after = @mutex.synchronize do
+          blocked_for = identifiers.filter_map do |identifier|
+            timestamps = active_timestamps(identifier, current_time)
+            next unless timestamps.length >= @max_attempts
+
+            timestamps.first + @window_seconds - current_time
+          end.max
+          unless blocked_for
+            identifiers.each do |identifier|
+              timestamps = active_timestamps(identifier, current_time)
+              timestamps << current_time
+              store(identifier, timestamps)
+            end
+          end
+          blocked_for
+        end
+        return unless retry_after
+
+        seconds = [retry_after.ceil, 1].max
+        log_rate_limit(context, seconds)
+        raise VectorMCP::RateLimitExceededError.new(retry_after: seconds)
+      end
+
+      # Record an unsuccessful authentication result for the reserved attempt.
+      # @param request [VectorMCP::RequestContext, Hash] incoming request context
+      # @return [void]
+      def record_failure(request)
+        context = VectorMCP::RequestContext.coerce(request)
+        current_time = now
+        threshold_reached = @mutex.synchronize do
+          request_identifiers(context).filter_map do |identifier|
+            timestamps = active_timestamps(identifier, current_time)
+            identifier_scope(identifier) if timestamps.length == @max_attempts
+          end
+        end
+
+        log_failure_threshold(context, threshold_reached) unless threshold_reached.empty?
+      end
+
+      # Clear failure history after successful authentication.
+      # @param request [VectorMCP::RequestContext, Hash] incoming request context
+      # @return [void]
+      def record_success(request)
+        identifiers = request_identifiers(VectorMCP::RequestContext.coerce(request))
+        @mutex.synchronize { identifiers.each { |identifier| @attempts.delete(identifier) } }
+      end
+
+      # @return [Hash] non-sensitive limiter status
+      def status
+        tracked_entries = @mutex.synchronize { @attempts.length }
+        {
+          enabled: true,
+          max_attempts: @max_attempts,
+          window_seconds: @window_seconds,
+          max_entries: @max_entries,
+          tracked_entries: tracked_entries
+        }
+      end
+
+      private
+
+      def now
+        @clock.call
+      end
+
+      def request_identifiers(context)
+        identifiers = []
+        remote_addr = context.metadata("remote_addr").to_s.strip
+        identifiers << "ip:#{remote_addr}" unless remote_addr.empty?
+
+        credential = extract_credential(context)
+        identifiers << "credential:#{Digest::SHA256.hexdigest(credential)}" if credential
+
+        identifiers.empty? ? ["source:unknown"] : identifiers
+      end
+
+      def extract_credential(context)
+        credential_values = context.headers.filter_map do |name, item|
+          item if CREDENTIAL_HEADERS.any? { |credential_header| credential_header.casecmp?(name) }
+        end
+        value = credential_values.find { |item| !item.strip.empty? }
+        value ||= CREDENTIAL_PARAMS.filter_map { |name| context.param(name) }.find { |item| !item.strip.empty? }
+        value&.strip
+      end
+
+      def active_timestamps(identifier, current_time)
+        cutoff = current_time - @window_seconds
+        (@attempts[identifier] || []).drop_while { |timestamp| timestamp <= cutoff }
+      end
+
+      def store(identifier, timestamps)
+        @attempts.delete(identifier)
+        @attempts.shift while @attempts.length >= @max_entries
+        @attempts[identifier] = timestamps.last(@max_attempts)
+      end
+
+      def identifier_scope(identifier)
+        identifier.split(":", 2).first
+      end
+
+      def log_failure_threshold(context, scopes)
+        @logger.security(
+          "Repeated authentication failures reached configured limit",
+          event: "authentication_failure_limit_reached",
+          remote_addr: context.metadata("remote_addr"),
+          scopes: scopes.uniq.join(","),
+          max_attempts: @max_attempts,
+          window_seconds: @window_seconds
+        )
+      end
+
+      def log_rate_limit(context, retry_after)
+        @logger.security(
+          "Authentication attempt rate limited",
+          event: "authentication_rate_limited",
+          remote_addr: context.metadata("remote_addr"),
+          retry_after: retry_after
+        )
+      end
+
+      def validate_positive_integer!(name, value)
+        return if value.is_a?(Integer) && value.positive?
+
+        raise ArgumentError, "#{name} must be a positive Integer"
+      end
+
+      def validate_positive_number!(name, value)
+        return if value.is_a?(Numeric) && value.positive?
+
+        raise ArgumentError, "#{name} must be a positive number"
+      end
+    end
+  end
+end

data/lib/vector_mcp/security/middleware.rb

@@ -6,6 +6,7 @@ module VectorMCP
     # Integrates with transport layers to provide security controls
     class Middleware
       attr_reader :auth_manager, :authorization
+      attr_accessor :authentication_rate_limiter
 
       # Initialize middleware with auth components
       # @param auth_manager [AuthManager] the authentication manager
@@ -20,8 +21,13 @@ module VectorMCP
       # @param strategy [Symbol] optional authentication strategy override
       # @return [SessionContext] the session context for the request
       def authenticate_request(request, strategy: nil)
+        request_context = rate_limit_request_context(request)
+        @authentication_rate_limiter&.check!(request_context) if request_context
+
         auth_result = @auth_manager.authenticate(request, strategy: strategy)
-        SessionContext.from_auth_result(auth_result)
+        session_context = SessionContext.from_auth_result(auth_result)
+        update_rate_limit(request_context, session_context)
+        session_context
       end
 
       # Check if a session is authorized for an action on a resource
@@ -86,7 +92,8 @@ module VectorMCP
           authentication: {
             enabled: @auth_manager.required?,
             strategies: @auth_manager.available_strategies,
-            default_strategy: @auth_manager.default_strategy
+            default_strategy: @auth_manager.default_strategy,
+            rate_limit: @authentication_rate_limiter&.status || { enabled: false }
           },
           authorization: {
             enabled: @authorization.required?,
@@ -94,6 +101,26 @@ module VectorMCP
           }
         }
       end
+
+      private
+
+      def rate_limit_request_context(request)
+        return unless @authentication_rate_limiter
+
+        VectorMCP::RequestContext.coerce(request)
+      rescue ArgumentError
+        VectorMCP::RequestContext.minimal("unknown")
+      end
+
+      def update_rate_limit(request, session_context)
+        return unless @authentication_rate_limiter
+
+        if session_context.authenticated?
+          @authentication_rate_limiter.record_success(request)
+        else
+          @authentication_rate_limiter.record_failure(request)
+        end
+      end
     end
   end
 end

data/lib/vector_mcp/security/request_authenticator.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative "../middleware"
+require_relative "../request_context"
+
+module VectorMCP
+  module Security
+    # Authenticates one request-scoped invocation and runs the auth middleware hooks.
+    # The resolved identity is cached only on Invocation, never on the shared Session.
+    class RequestAuthenticator
+      OPERATION_TYPES = {
+        "tools/list" => :tool_list,
+        "tools/call" => :tool_call,
+        "resources/list" => :resource_list,
+        "resources/read" => :resource_read,
+        "prompts/list" => :prompt_list,
+        "prompts/get" => :prompt_get,
+        "roots/list" => :root_list
+      }.freeze
+
+      OPERATION_NAME_PARAMS = {
+        "tools/call" => "name",
+        "resources/read" => "uri",
+        "prompts/get" => "name"
+      }.freeze
+
+      class << self
+        # Authenticate a protocol message using operation metadata derived from its method.
+        def authenticate_message!(method, params, session, server)
+          operation_type = OPERATION_TYPES.fetch(method, :request)
+          name_param = OPERATION_NAME_PARAMS[method]
+          operation_name = name_param ? params[name_param] || params[name_param.to_sym] : method
+
+          authenticate!(session, server, operation_type: operation_type, operation_name: operation_name)
+        end
+
+        # Authenticate the current request and return its resolved identity.
+        def authenticate!(session, server, operation_type:, operation_name:)
+          return session.security_context if authentication_resolved?(session)
+
+          context = nil
+          request = request_context_for(session)
+          context = auth_context(operation_type, operation_name, request.to_h, session, server)
+          context = server.middleware_manager.execute_hooks(:before_auth, context)
+          raise context.error if context.error?
+
+          session_context = server.security_middleware.authenticate_request(context.params)
+          session.security_context = session_context
+
+          raise VectorMCP::UnauthorizedError, "Authentication required" if server.auth_manager.required? && !session_context.authenticated?
+
+          context.result = session_context
+          server.middleware_manager.execute_hooks(:after_auth, context)
+          session_context
+        rescue StandardError => e
+          handle_auth_error(e, context, server)
+        end
+
+        # Extract the immutable request context carried by the invocation/session.
+        def request_context_for(session)
+          unless session.respond_to?(:request_context) && session.request_context
+            raise VectorMCP::InternalError,
+                  "Session missing request_context - transport layer integration error. Session ID: #{session.id}"
+          end
+
+          session.request_context
+        end
+
+        private
+
+        def authentication_resolved?(session)
+          session.respond_to?(:authentication_resolved?) && session.authentication_resolved?
+        end
+
+        def auth_context(operation_type, operation_name, request, session, server)
+          VectorMCP::Middleware::Context.new(
+            operation_type: operation_type,
+            operation_name: operation_name,
+            params: request,
+            session: session,
+            server: server,
+            metadata: { start_time: Time.now }
+          )
+        end
+
+        def handle_auth_error(error, context, server)
+          if context
+            context.error = error
+            server.middleware_manager.execute_hooks(:on_auth_error, context)
+          end
+
+          raise error
+        end
+      end
+    end
+  end
+end

data/lib/vector_mcp/server/capabilities.rb

@@ -54,13 +54,6 @@ module VectorMCP
         send_list_changed_notification("roots") if @roots_list_changed
       end
 
-      # Registers a session as a subscriber to prompt list changes.
-      # @api private
-      def subscribe_prompts(session)
-        @prompt_subscribers << session unless @prompt_subscribers.include?(session)
-        # Session subscribed to prompt list changes
-      end
-
       private
 
       # Sends a `notifications/<kind>/list_changed` notification to the transport.

data/lib/vector_mcp/server/message_handling.rb

@@ -1,9 +1,14 @@
 # frozen_string_literal: true
 
+require_relative "../security/request_authenticator"
+
 module VectorMCP
   class Server
     # Handles message processing and request/notification dispatching
     module MessageHandling
+      PUBLIC_REQUEST_METHODS = %w[initialize ping].freeze
+      PUBLIC_NOTIFICATION_METHODS = %w[initialized].freeze
+
       # --- Message Handling Logic (primarily called by transports) ---
 
       # Handles an incoming JSON-RPC message (request or notification).
@@ -76,11 +81,7 @@ module VectorMCP
       # @api private
       def handle_request(id, method, params, session)
         validate_session_initialization(id, method, params, session)
-
-        handler = @request_handlers[method]
-        raise VectorMCP::MethodNotFoundError.new(method, request_id: id) unless handler
-
-        execute_request_handler(id, method, params, session, handler)
+        execute_request_handler(id, method, params, session)
       end
 
       # Validates that the session is properly initialized for the given request.
@@ -97,8 +98,14 @@ module VectorMCP
 
       # Executes the request handler with proper error handling and tracking.
       # @api private
-      def execute_request_handler(id, method, params, session, handler)
+      def execute_request_handler(id, method, params, session)
         @in_flight_requests[id] = { method: method, params: params, session: session, start_time: Time.now }
+
+        authenticate_message!(method, params, session) unless PUBLIC_REQUEST_METHODS.include?(method)
+
+        handler = @request_handlers[method]
+        raise VectorMCP::MethodNotFoundError.new(method, request_id: id) unless handler
+
         result = handler.call(params, session, self)
         result
       rescue VectorMCP::ProtocolError => e
@@ -133,6 +140,7 @@ module VectorMCP
         handler = @notification_handlers[method]
         if handler
           begin
+            authenticate_message!(method, params, session) unless PUBLIC_NOTIFICATION_METHODS.include?(method)
             handler.call(params, session, self)
           rescue StandardError => e
             logger.error("Error executing notification handler '#{method}': #{e.message}\nBacktrace (top 5):\n  #{e.backtrace.first(5).join("\n  ")}")
@@ -155,7 +163,6 @@ module VectorMCP
         on_request("resources/read", &Handlers::Core.method(:read_resource))
         on_request("prompts/list", &Handlers::Core.method(:list_prompts))
         on_request("prompts/get", &Handlers::Core.method(:get_prompt))
-        on_request("prompts/subscribe", &Handlers::Core.method(:subscribe_prompts))
         on_request("roots/list", &Handlers::Core.method(:list_roots))
 
         # Core Notifications
@@ -173,6 +180,12 @@ module VectorMCP
           session.public_send(method_name, params)
         end
       end
+
+      def authenticate_message!(method, params, session)
+        return unless auth_manager.required?
+
+        VectorMCP::Security::RequestAuthenticator.authenticate_message!(method, params, session, self)
+      end
     end
   end
 end

data/lib/vector_mcp/server.rb

@@ -11,6 +11,7 @@ require_relative "server/registry"
 require_relative "server/capabilities"
 require_relative "server/message_handling"
 require_relative "security/auth_manager"
+require_relative "security/authentication_rate_limiter"
 require_relative "security/authorization"
 require_relative "security/middleware"
 require_relative "security/session_context"
@@ -72,7 +73,8 @@ module VectorMCP
     SUPPORTED_PROTOCOL_VERSIONS = %w[2025-11-25 2025-03-26 2024-11-05].freeze
 
     attr_reader :logger, :name, :version, :protocol_version, :tools, :resources, :prompts, :roots, :in_flight_requests,
-                :auth_manager, :authorization, :security_middleware, :middleware_manager, :oauth_resource_metadata_url
+                :auth_manager, :authorization, :security_middleware, :middleware_manager, :oauth_resource_metadata_url,
+                :authentication_rate_limiter
     attr_accessor :transport
 
     # Initializes a new VectorMCP server.
@@ -112,7 +114,6 @@ module VectorMCP
       @notification_handlers = {}
       @in_flight_requests = {}
       @prompts_list_changed = false
-      @prompt_subscribers = []
       @roots_list_changed = false
 
       # Configure sampling capabilities
@@ -123,6 +124,7 @@ module VectorMCP
       @authorization = Security::Authorization.new
       @security_middleware = Security::Middleware.new(@auth_manager, @authorization)
       @oauth_resource_metadata_url = nil
+      @authentication_rate_limiter = nil
 
       # Initialize middleware manager
       @middleware_manager = Middleware::Manager.new
@@ -195,10 +197,13 @@ module VectorMCP
     #   enabling MCP clients (e.g. Claude Desktop) to discover the authorization server and
     #   initiate an OAuth 2.1 flow. When omitted (default), auth failures continue to surface
     #   as JSON-RPC +-32401+ errors — existing behavior is preserved for non-OAuth deployments.
+    # @option options [Hash, Boolean] :rate_limit Optional authentication failure limiter.
+    #   Pass +true+ for defaults or configure +:max_attempts+, +:window_seconds+, and +:max_entries+.
     # @return [void]
     def enable_authentication!(strategy: :api_key, **options, &block)
       clear_auth_strategies unless @auth_manager.strategies.empty?
       extract_oauth_metadata!(options)
+      configure_authentication_rate_limit!(options.delete(:rate_limit))
       @auth_manager.enable!(default_strategy: strategy)
       register_auth_strategy(strategy, options, block || options.delete(:handler))
       @logger.info("Authentication enabled with strategy: #{strategy}")
@@ -209,6 +214,7 @@ module VectorMCP
     def disable_authentication!
       @auth_manager.disable!
       @oauth_resource_metadata_url = nil
+      configure_authentication_rate_limit!(nil)
       @logger.info("Authentication disabled")
     end
 
@@ -318,6 +324,23 @@ module VectorMCP
       warn_on_insecure_oauth_metadata_url(@oauth_resource_metadata_url)
     end
 
+    # Configure the optional in-process authentication failure limiter.
+    # @param configuration [Hash, true, false, nil] limiter configuration
+    # @return [void]
+    def configure_authentication_rate_limit!(configuration)
+      @authentication_rate_limiter = case configuration
+                                     when true
+                                       Security::AuthenticationRateLimiter.new
+                                     when Hash
+                                       Security::AuthenticationRateLimiter.new(**configuration)
+                                     when false, nil
+                                       nil
+                                     else
+                                       raise ArgumentError, "rate_limit must be true, false, nil, or a Hash"
+                                     end
+      @security_middleware.authentication_rate_limiter = @authentication_rate_limiter
+    end
+
     # Register the appropriate auth strategy based on the strategy name
     # @param strategy [Symbol] the strategy type
     # @param options [Hash] strategy-specific options

data/lib/vector_mcp/transport/http_stream.rb

@@ -41,9 +41,10 @@ module VectorMCP
     # @attr_reader host [String] The hostname or IP address the server will bind to
     # @attr_reader port [Integer] The port number the server will listen on
     # @attr_reader path_prefix [String] The base URL path for MCP endpoints
+    # @attr_reader max_body_bytes [Integer] Maximum accepted POST body size
     # rubocop:disable Metrics/ClassLength
     class HttpStream
-      attr_reader :logger, :server, :host, :port, :path_prefix
+      attr_reader :logger, :server, :host, :port, :path_prefix, :max_body_bytes
 
       # Default configuration values
       DEFAULT_HOST = "localhost"
@@ -54,6 +55,8 @@ module VectorMCP
       DEFAULT_REQUEST_TIMEOUT = 30 # Default timeout for server-initiated requests
       DEFAULT_MIN_THREADS = 4
       DEFAULT_MAX_THREADS = 32
+      # Accommodates the 10 MiB ImageUtil limit after base64 expansion and JSON framing.
+      DEFAULT_MAX_BODY_BYTES = 16 * 1024 * 1024
 
       # Default allowed origins — restrict to localhost by default for security.
       DEFAULT_ALLOWED_ORIGINS = %w[
@@ -76,6 +79,7 @@ module VectorMCP
       # @option options [Integer] :event_retention (100) Number of events to retain for resumability
       # @option options [Integer] :min_threads (4) Minimum Puma thread pool size
       # @option options [Integer] :max_threads (32) Maximum Puma thread pool size
+      # @option options [Integer] :max_body_bytes (16777216) Maximum POST body size in bytes
       # @option options [Array<String>] :allowed_origins Allowed origins for CORS validation.
       #   Defaults to localhost origins only. Pass ["*"] to allow all origins (NOT recommended for production).
       def initialize(server, options = {})
@@ -268,7 +272,13 @@ module VectorMCP
       #
       # @return [void]
       def start_puma_server
-        @puma_server = Puma::Server.new(self, nil, min_threads: @min_threads, max_threads: @max_threads)
+        @puma_server = Puma::Server.new(
+          self,
+          nil,
+          min_threads: @min_threads,
+          max_threads: @max_threads,
+          http_content_length_limit: @max_body_bytes
+        )
         @puma_server.add_tcp_listener(@host, @port)
 
         @running = true
@@ -349,7 +359,7 @@ module VectorMCP
       # Validates origin and dispatches to the appropriate handler by HTTP method.
       def validate_and_dispatch(method, env)
         return forbidden_response("Origin not allowed") unless valid_origin?(env)
-        return unauthorized_oauth_response(env) if oauth_gate_should_reject?(env)
+        return unauthorized_transport_response(env) if transport_gate_should_reject?(env, method)
 
         case method
         when "POST"
@@ -361,16 +371,20 @@ module VectorMCP
         else
           method_not_allowed_response(%w[POST GET DELETE])
         end
+      rescue VectorMCP::RateLimitExceededError => e
+        rate_limit_response(e)
       end
 
-      # True when OAuth 2.1 resource server mode is enabled and the incoming
-      # request has not successfully authenticated. Opt-in: only activates when the
-      # server was configured with a +resource_metadata_url+ via +enable_authentication!+.
+      # OAuth resource-server mode authenticates every MCP transport request.
+      # Other authentication modes authenticate GET/DELETE here because those
+      # operations do not pass through the JSON-RPC message dispatcher.
       #
       # @param env [Hash] The Rack environment
+      # @param method [String] The HTTP method
       # @return [Boolean]
-      def oauth_gate_should_reject?(env)
-        return false unless oauth_resource_server_enabled?
+      def transport_gate_should_reject?(env, method)
+        return false unless @server.auth_manager.required?
+        return false unless oauth_resource_server_enabled? || %w[GET DELETE].include?(method)
 
         !authenticate_transport_request(env).authenticated?
       end
@@ -395,6 +409,8 @@ module VectorMCP
       def authenticate_transport_request(env)
         request_context = VectorMCP::RequestContext.from_rack_env(env, "http_stream")
         @server.security_middleware.authenticate_request(request_context)
+      rescue VectorMCP::RateLimitExceededError
+        raise
       rescue StandardError => e
         VectorMCP.logger_for("security").warn do
           "OAuth transport auth strategy raised #{e.class}: #{e.message}"
@@ -427,6 +443,24 @@ module VectorMCP
          [body]]
       end
 
+      # Returns a plain HTTP authentication challenge for non-OAuth API-key/JWT
+      # deployments. OAuth mode uses its RFC 9728 discovery response instead.
+      def unauthorized_transport_response(env)
+        return unauthorized_oauth_response(env) if oauth_resource_server_enabled?
+
+        VectorMCP.logger_for("security").info do
+          "HTTP transport 401 issued for #{env["REQUEST_METHOD"]} #{env["PATH_INFO"]}"
+        end
+
+        body = {
+          jsonrpc: "2.0",
+          id: nil,
+          error: { code: -32_401, message: "Authentication required" }
+        }.to_json
+
+        [401, { "Content-Type" => "application/json" }, [body]]
+      end
+
       # Handles POST requests (client-to-server JSON-RPC)
       #
       # @param env [Hash] The Rack environment
@@ -458,6 +492,8 @@ module VectorMCP
         end
 
         handle_single_request(parsed, session, env)
+      rescue VectorMCP::PayloadTooLargeError => e
+        payload_too_large_response(e.message)
       rescue JSON::ParserError => e
         json_error_response(nil, -32_700, "Parse error", { details: e.message })
       end
@@ -573,9 +609,15 @@ module VectorMCP
       # @param env [Hash] The Rack environment
       # @return [String] The request body
       def read_request_body(env)
+        content_length = env["CONTENT_LENGTH"].to_i
+        raise VectorMCP::PayloadTooLargeError, @max_body_bytes if content_length > @max_body_bytes
+
         input = env["rack.input"]
         input.rewind
-        input.read
+        body = input.read(@max_body_bytes + 1) || ""
+        raise VectorMCP::PayloadTooLargeError, @max_body_bytes if body.bytesize > @max_body_bytes
+
+        body
       end
 
       # Optimized JSON parsing with better error handling and performance
@@ -655,6 +697,8 @@ module VectorMCP
       end
 
       def build_protocol_error_response(env, error, session_id: nil)
+        return rate_limit_response(error) if error.is_a?(VectorMCP::RateLimitExceededError)
+
         if client_accepts_sse?(env)
           sse_error_response(error.request_id, error.code, error.message, error.details, session_id: session_id)
         else
@@ -662,6 +706,18 @@ module VectorMCP
         end
       end
 
+      def rate_limit_response(error)
+        body = {
+          jsonrpc: "2.0",
+          id: error.request_id,
+          error: { code: error.code, message: error.message, data: error.details }
+        }.to_json
+
+        [429,
+         { "Content-Type" => "application/json", "Retry-After" => error.retry_after.to_s },
+         [body]]
+      end
+
       def client_accepts_sse?(env)
         accept = env["HTTP_ACCEPT"] || ""
         accept.include?("text/event-stream")
@@ -744,6 +800,10 @@ module VectorMCP
         [406, { "Content-Type" => "text/plain" }, [message]]
       end
 
+      def payload_too_large_response(message = "Payload Too Large")
+        [413, { "Content-Type" => "text/plain", "Connection" => "close" }, [message]]
+      end
+
       # Validates the MCP-Protocol-Version header per spec.
       # Returns nil if valid, or a 400 Rack response if unsupported.
       def validate_protocol_version_header(env)
@@ -984,12 +1044,19 @@ module VectorMCP
         @event_retention = options[:event_retention] || DEFAULT_EVENT_RETENTION
         @min_threads = options[:min_threads] || DEFAULT_MIN_THREADS
         @max_threads = options[:max_threads] || DEFAULT_MAX_THREADS
+        @max_body_bytes = validate_max_body_bytes(options.fetch(:max_body_bytes, DEFAULT_MAX_BODY_BYTES))
         @allowed_origins = options[:allowed_origins] || DEFAULT_ALLOWED_ORIGINS
         @mounted = options.fetch(:mounted, false)
 
         warn_on_permissive_origins if @allowed_origins.include?("*")
       end
 
+      def validate_max_body_bytes(value)
+        raise ArgumentError, "max_body_bytes must be a positive Integer" unless value.is_a?(Integer) && value.positive?
+
+        value
+      end
+
       # Logs a security warning when wildcard origin is configured.
       def warn_on_permissive_origins
         logger.warn do

data/lib/vector_mcp/version.rb

@@ -2,5 +2,5 @@
 
 module VectorMCP
   # The current version of the VectorMCP gem.
-  VERSION = "0.7.0"
+  VERSION = "0.7.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vector_mcp
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Sergio Bayona
@@ -145,8 +145,10 @@ files:
 - lib/vector_mcp/security.rb
 - lib/vector_mcp/security/auth_manager.rb
 - lib/vector_mcp/security/auth_result.rb
+- lib/vector_mcp/security/authentication_rate_limiter.rb
 - lib/vector_mcp/security/authorization.rb
 - lib/vector_mcp/security/middleware.rb
+- lib/vector_mcp/security/request_authenticator.rb
 - lib/vector_mcp/security/session_context.rb
 - lib/vector_mcp/security/strategies/api_key.rb
 - lib/vector_mcp/security/strategies/custom.rb