vector_mcp 0.3.4 → 0.5.0

data/lib/vector_mcp/server/registry.rb

@@ -29,6 +29,38 @@ module VectorMCP
         self
       end
 
+      # Registers one or more class-based tool definitions with the server.
+      #
+      # Each argument must be a subclass of +VectorMCP::Tool+ that declares
+      # its metadata via the class-level DSL (+tool_name+, +description+,
+      # +param+) and implements +#call+.
+      #
+      # @param tool_classes [Array<Class>] One or more +VectorMCP::Tool+ subclasses.
+      # @return [self] The server instance, for chaining.
+      # @raise [ArgumentError] If any argument is not a +VectorMCP::Tool+ subclass.
+      #
+      # @example Register a single tool
+      #   server.register(ListProviders)
+      #
+      # @example Register multiple tools
+      #   server.register(ListProviders, CreateProvider, UpdateProvider)
+      def register(*tool_classes)
+        tool_classes.each do |tool_class|
+          unless tool_class.is_a?(Class) && tool_class < VectorMCP::Tool
+            raise ArgumentError, "#{tool_class.inspect} is not a VectorMCP::Tool subclass"
+          end
+
+          definition = tool_class.to_definition
+          register_tool(
+            name: definition.name,
+            description: definition.description,
+            input_schema: definition.input_schema,
+            &definition.handler
+          )
+        end
+        self
+      end
+
       # Registers a new resource with the server.
       #
       # @param uri [String, URI] The unique URI for the resource.
@@ -99,114 +131,74 @@ module VectorMCP
       end
 
       # Helper method to register an image resource from a file path.
+      # Thin wrapper: delegates schema-building to Definitions::Resource.from_image_file,
+      # then stores the result via register_resource.
       #
       # @param uri [String] Unique URI for the resource.
       # @param file_path [String] Path to the image file.
       # @param name [String, nil] Human-readable name (auto-generated if nil).
       # @param description [String, nil] Description (auto-generated if nil).
-      # @return [VectorMCP::Definitions::Resource] The registered resource.
+      # @return [self]
       # @raise [ArgumentError] If the file doesn't exist or isn't a valid image.
       def register_image_resource(uri:, file_path:, name: nil, description: nil)
         resource = VectorMCP::Definitions::Resource.from_image_file(
-          uri: uri,
-          file_path: file_path,
-          name: name,
-          description: description
-        )
-
-        register_resource(
-          uri: resource.uri,
-          name: resource.name,
-          description: resource.description,
-          mime_type: resource.mime_type,
-          &resource.handler
+          uri: uri, file_path: file_path, name: name, description: description
         )
+        register_resource(uri: resource.uri, name: resource.name,
+                          description: resource.description, mime_type: resource.mime_type, &resource.handler)
       end
 
       # Helper method to register an image resource from binary data.
+      # Thin wrapper: delegates to Definitions::Resource.from_image_data.
       #
       # @param uri [String] Unique URI for the resource.
       # @param image_data [String] Binary image data.
       # @param name [String] Human-readable name.
       # @param description [String, nil] Description (auto-generated if nil).
       # @param mime_type [String, nil] MIME type (auto-detected if nil).
-      # @return [VectorMCP::Definitions::Resource] The registered resource.
-      # @raise [ArgumentError] If the data isn't valid image data.
+      # @return [self]
       def register_image_resource_from_data(uri:, image_data:, name:, description: nil, mime_type: nil)
         resource = VectorMCP::Definitions::Resource.from_image_data(
-          uri: uri,
-          image_data: image_data,
-          name: name,
-          description: description,
-          mime_type: mime_type
-        )
-
-        register_resource(
-          uri: resource.uri,
-          name: resource.name,
-          description: resource.description,
-          mime_type: resource.mime_type,
-          &resource.handler
+          uri: uri, image_data: image_data, name: name, description: description, mime_type: mime_type
         )
+        register_resource(uri: resource.uri, name: resource.name,
+                          description: resource.description, mime_type: resource.mime_type, &resource.handler)
       end
 
       # Helper method to register a tool that accepts image inputs.
+      # Thin wrapper: delegates schema-building to Definitions::Tool.with_image_support.
       #
       # @param name [String] Unique name for the tool.
       # @param description [String] Human-readable description.
       # @param image_parameter [String] Name of the image parameter (default: "image").
       # @param additional_parameters [Hash] Additional JSON Schema properties.
       # @param required_parameters [Array<String>] List of required parameter names.
-      # @param block [Proc] The tool handler block.
-      # @return [VectorMCP::Definitions::Tool] The registered tool.
-      def register_image_tool(name:, description:, image_parameter: "image", additional_parameters: {}, required_parameters: [], &block)
-        # Build the input schema with image support
-        image_property = {
-          type: "string",
-          description: "Base64 encoded image data or file path to image",
-          contentEncoding: "base64",
-          contentMediaType: "image/*"
-        }
-
-        properties = { image_parameter => image_property }.merge(additional_parameters)
-
-        input_schema = {
-          type: "object",
-          properties: properties,
-          required: required_parameters
-        }
-
-        register_tool(
-          name: name,
-          description: description,
-          input_schema: input_schema,
-          &block
+      # @return [self]
+      def register_image_tool(name:, description:, image_parameter: "image",
+                              additional_parameters: {}, required_parameters: [], &handler)
+        tool = VectorMCP::Definitions::Tool.with_image_support(
+          name: name, description: description, image_parameter: image_parameter,
+          additional_parameters: additional_parameters, required_parameters: required_parameters, &handler
         )
+        register_tool(name: tool.name, description: tool.description,
+                      input_schema: tool.input_schema, &tool.handler)
       end
 
       # Helper method to register a prompt that supports image arguments.
+      # Thin wrapper: delegates to Definitions::Prompt.with_image_support.
       #
       # @param name [String] Unique name for the prompt.
       # @param description [String] Human-readable description.
       # @param image_argument [String] Name of the image argument (default: "image").
       # @param additional_arguments [Array<Hash>] Additional prompt arguments.
-      # @param block [Proc] The prompt handler block.
-      # @return [VectorMCP::Definitions::Prompt] The registered prompt.
-      def register_image_prompt(name:, description:, image_argument: "image", additional_arguments: [], &block)
+      # @return [self]
+      def register_image_prompt(name:, description:, image_argument: "image", additional_arguments: [], &handler)
         prompt = VectorMCP::Definitions::Prompt.with_image_support(
-          name: name,
-          description: description,
-          image_argument_name: image_argument,
-          additional_arguments: additional_arguments,
-          &block
-        )
-
-        register_prompt(
-          name: prompt.name,
-          description: prompt.description,
-          arguments: prompt.arguments,
-          &prompt.handler
+          name: name, description: description, image_argument_name: image_argument,
+          additional_arguments: additional_arguments, &handler
         )
+        register_prompt(name: prompt.name, description: prompt.description,
+                        arguments: prompt.arguments, &prompt.handler)
       end
 
       private
@@ -230,6 +222,34 @@ module VectorMCP
         raise ArgumentError, "Invalid input_schema structure: #{e.message}"
       end
 
+      # Schema for a single prompt argument definition. Each entry names the
+      # required/optional key, whether it is required, and the rule that validates
+      # its value. Rules return nil on success or an error message fragment.
+      PROMPT_ARG_SCHEMA = {
+        "name" => {
+          required: true,
+          missing_message: "missing :name",
+          rule: lambda { |v|
+            next "must be a String or Symbol. Found: #{v.class}" unless v.is_a?(String) || v.is_a?(Symbol)
+
+            "cannot be empty." if v.to_s.strip.empty?
+          }
+        },
+        "description" => {
+          required: false,
+          rule: ->(v) { "must be a String if provided. Found: #{v.class}" unless v.nil? || v.is_a?(String) }
+        },
+        "required" => {
+          required: false,
+          rule: ->(v) { "must be true or false if provided. Found: #{v.inspect}" unless [true, false].include?(v) }
+        },
+        "type" => {
+          required: false,
+          rule: ->(v) { "must be a String if provided (e.g., JSON schema type). Found: #{v.class}" unless v.nil? || v.is_a?(String) }
+        }
+      }.freeze
+      private_constant :PROMPT_ARG_SCHEMA
+
       # Validates the structure of the `arguments` array provided to {#register_prompt}.
       # @api private
       def validate_prompt_arguments(argument_defs)
@@ -238,75 +258,37 @@ module VectorMCP
         argument_defs.each_with_index { |arg, idx| validate_single_prompt_argument(arg, idx) }
       end
 
-      # Defines the keys allowed in a prompt argument definition hash.
-      ALLOWED_PROMPT_ARG_KEYS = %w[name description required type].freeze
-      private_constant :ALLOWED_PROMPT_ARG_KEYS
-
-      # Validates a single prompt argument definition hash.
+      # Validates a single prompt argument definition hash against PROMPT_ARG_SCHEMA.
       # @api private
       def validate_single_prompt_argument(arg, idx)
         raise ArgumentError, "Prompt argument definition at index #{idx} must be a Hash. Found: #{arg.class}" unless arg.is_a?(Hash)
 
-        validate_prompt_arg_name!(arg, idx)
-        validate_prompt_arg_description!(arg, idx)
-        validate_prompt_arg_required_flag!(arg, idx)
-        validate_prompt_arg_type!(arg, idx)
-        validate_prompt_arg_unknown_keys!(arg, idx)
-      end
-
-      # Validates the :name key of a prompt argument definition.
-      # @api private
-      def validate_prompt_arg_name!(arg, idx)
-        name_val = arg[:name] || arg["name"]
-        raise ArgumentError, "Prompt argument at index #{idx} missing :name" if name_val.nil?
-        unless name_val.is_a?(String) || name_val.is_a?(Symbol)
-          raise ArgumentError, "Prompt argument :name at index #{idx} must be a String or Symbol. Found: #{name_val.class}"
-        end
-        raise ArgumentError, "Prompt argument :name at index #{idx} cannot be empty." if name_val.to_s.strip.empty?
-      end
-
-      # Validates the :description key of a prompt argument definition.
-      # @api private
-      def validate_prompt_arg_description!(arg, idx)
-        return unless arg.key?(:description) || arg.key?("description")
-
-        desc_val = arg[:description] || arg["description"]
-        return if desc_val.nil? || desc_val.is_a?(String)
-
-        raise ArgumentError, "Prompt argument :description at index #{idx} must be a String if provided. Found: #{desc_val.class}"
-      end
-
-      # Validates the :required key of a prompt argument definition.
-      # @api private
-      def validate_prompt_arg_required_flag!(arg, idx)
-        return unless arg.key?(:required) || arg.key?("required")
-
-        req_val = arg[:required] || arg["required"]
-        return if [true, false].include?(req_val)
-
-        raise ArgumentError, "Prompt argument :required at index #{idx} must be true or false if provided. Found: #{req_val.inspect}"
+        PROMPT_ARG_SCHEMA.each { |key, spec| validate_prompt_arg_field(arg, idx, key, spec) }
+        validate_prompt_arg_unknown_keys(arg, idx)
       end
 
-      # Validates the :type key of a prompt argument definition.
+      # Validates a single field of a prompt argument hash against its schema spec.
       # @api private
-      def validate_prompt_arg_type!(arg, idx)
-        return unless arg.key?(:type) || arg.key?("type")
+      def validate_prompt_arg_field(arg, idx, key, spec)
+        present = arg.key?(key.to_sym) || arg.key?(key)
+        value = arg[key.to_sym] || arg[key]
 
-        type_val = arg[:type] || arg["type"]
-        return if type_val.nil? || type_val.is_a?(String)
+        raise ArgumentError, "Prompt argument at index #{idx} #{spec[:missing_message]}" if spec[:required] && value.nil?
+        return unless present
 
-        raise ArgumentError, "Prompt argument :type at index #{idx} must be a String if provided (e.g., JSON schema type). Found: #{type_val.class}"
+        error_fragment = spec[:rule].call(value)
+        raise ArgumentError, "Prompt argument :#{key} at index #{idx} #{error_fragment}" if error_fragment
       end
 
-      # Checks for any unknown keys in a prompt argument definition.
+      # Checks a prompt argument hash for keys outside PROMPT_ARG_SCHEMA.
       # @api private
-      def validate_prompt_arg_unknown_keys!(arg, idx)
-        unknown_keys = arg.transform_keys(&:to_s).keys - ALLOWED_PROMPT_ARG_KEYS
+      def validate_prompt_arg_unknown_keys(arg, idx)
+        unknown_keys = arg.transform_keys(&:to_s).keys - PROMPT_ARG_SCHEMA.keys
         return if unknown_keys.empty?
 
         raise ArgumentError,
               "Prompt argument definition at index #{idx} contains unknown keys: #{unknown_keys.join(", ")}. " \
-              "Allowed: #{ALLOWED_PROMPT_ARG_KEYS.join(", ")}."
+              "Allowed: #{PROMPT_ARG_SCHEMA.keys.join(", ")}."
       end
     end
   end

data/lib/vector_mcp/server.rb

@@ -5,8 +5,6 @@ require "logger"
 require_relative "definitions"
 require_relative "session"
 require_relative "errors"
-require_relative "transport/stdio" # Default transport
-# require_relative "transport/sse" # Load on demand to avoid async dependencies
 require_relative "handlers/core" # Default handlers
 require_relative "util" # Needed if not using Handlers::Core
 require_relative "server/registry"
@@ -26,7 +24,7 @@ module VectorMCP
   # It manages tools, resources, prompts, and handles the MCP message lifecycle.
   #
   # A server instance is typically initialized, configured with capabilities (tools,
-  # resources, prompts), and then run with a chosen transport mechanism (e.g., Stdio, SSE).
+  # resources, prompts), and then run with a chosen transport mechanism (e.g., HttpStream).
   #
   # @example Creating and running a simple server
   #   server = VectorMCP::Server.new(name: "MySimpleServer", version: "1.0")
@@ -39,7 +37,7 @@ module VectorMCP
   #     args["message"]
   #   end
   #
-  #   server.run(transport: :stdio) # Runs with Stdio transport by default
+  #   server.run # Runs with HttpStream transport by default
   #
   # @!attribute [r] logger
   #   @return [Logger] The logger instance for this server.
@@ -68,10 +66,13 @@ module VectorMCP
     include MessageHandling
 
     # The specific version of the Model Context Protocol this server implements.
-    PROTOCOL_VERSION = "2024-11-05"
+    PROTOCOL_VERSION = "2025-11-25"
+
+    # All protocol versions this server accepts via the MCP-Protocol-Version header.
+    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
+                :auth_manager, :authorization, :security_middleware, :middleware_manager, :oauth_resource_metadata_url
     attr_accessor :transport
 
     # Initializes a new VectorMCP server.
@@ -121,6 +122,7 @@ module VectorMCP
       @auth_manager = Security::AuthManager.new
       @authorization = Security::Authorization.new
       @security_middleware = Security::Middleware.new(@auth_manager, @authorization)
+      @oauth_resource_metadata_url = nil
 
       # Initialize middleware manager
       @middleware_manager = Middleware::Manager.new
@@ -134,33 +136,19 @@ module VectorMCP
 
     # Runs the server using the specified transport mechanism.
     #
-    # @param transport [:stdio, :sse, :http_stream, VectorMCP::Transport::Base] The transport to use.
-    #   Can be a symbol (`:stdio`, `:sse`, `:http_stream`) or an initialized transport instance.
-    #   If a symbol is provided, the method will instantiate the corresponding transport class.
-    #   If `:sse` is chosen, it uses Puma as the HTTP server (deprecated).
-    #   If `:http_stream` is chosen, it uses the MCP-compliant streamable HTTP transport.
-    # @param options [Hash] Transport-specific options (e.g., `:host`, `:port` for HTTP transports).
+    # @param transport [:http_stream, VectorMCP::Transport::Base] The transport to use.
+    #   Can be the symbol `:http_stream` or an initialized transport instance.
+    #   If `:http_stream` is provided, the method will instantiate the MCP-compliant streamable HTTP transport.
+    # @param options [Hash] Transport-specific options (e.g., `:host`, `:port`).
     #   These are passed to the transport's constructor if a symbol is provided for `transport`.
     # @return [void]
     # @raise [ArgumentError] if an unsupported transport symbol is given.
-    # @raise [NotImplementedError] if `:sse` transport is specified (currently a placeholder).
-    def run(transport: :stdio, **options)
+    def run(transport: :http_stream, **)
       active_transport = case transport
-                         when :stdio
-                           VectorMCP::Transport::Stdio.new(self, **options)
-                         when :sse
-                           begin
-                             require_relative "transport/sse"
-                             logger.warn("SSE transport is deprecated. Please use :http_stream instead.")
-                             VectorMCP::Transport::SSE.new(self, **options)
-                           rescue LoadError => e
-                             logger.fatal("SSE transport requires additional dependencies.")
-                             raise NotImplementedError, "SSE transport dependencies not available: #{e.message}"
-                           end
                          when :http_stream
                            begin
                              require_relative "transport/http_stream"
-                             VectorMCP::Transport::HttpStream.new(self, **options)
+                             VectorMCP::Transport::HttpStream.new(self, **)
                            rescue LoadError => e
                              logger.fatal("HttpStream transport requires additional dependencies.")
                              raise NotImplementedError, "HttpStream transport dependencies not available: #{e.message}"
@@ -176,33 +164,43 @@ module VectorMCP
       active_transport.run
     end
 
+    # Returns the MCP server as a Rack application suitable for mounting inside
+    # another Rack-based framework (e.g., Rails, Sinatra).
+    #
+    # Unlike {#run}, this method does NOT start its own HTTP server or block.
+    # The returned object responds to `#call(env)` and can be mounted directly:
+    #
+    #   # config/routes.rb (Rails)
+    #   mount MCP_APP => "/mcp"
+    #
+    # Call `server.transport.stop` on application shutdown to clean up resources.
+    #
+    # @param options [Hash] Transport options (e.g., :session_timeout, :event_retention, :allowed_origins)
+    # @return [VectorMCP::Transport::HttpStream] A Rack-compatible app
+    def rack_app(**)
+      require_relative "transport/http_stream"
+      active_transport = VectorMCP::Transport::HttpStream.new(self, mounted: true, **)
+      self.transport = active_transport
+      active_transport
+    end
+
     # --- Security Configuration ---
 
     # Enable authentication with specified strategy and configuration
     # @param strategy [Symbol] the authentication strategy (:api_key, :jwt, :custom)
     # @param options [Hash] strategy-specific configuration options
+    # @option options [String] :resource_metadata_url OAuth 2.1 protected resource metadata URL
+    #   (RFC 9728). When provided, unauthenticated requests to the HTTP Stream transport's MCP
+    #   endpoint return HTTP 401 with a +WWW-Authenticate: Bearer+ header pointing at this URL,
+    #   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.
     # @return [void]
     def enable_authentication!(strategy: :api_key, **options, &block)
-      # Clear existing strategies when switching to a new configuration
       clear_auth_strategies unless @auth_manager.strategies.empty?
-
+      extract_oauth_metadata!(options)
       @auth_manager.enable!(default_strategy: strategy)
-
-      case strategy
-      when :api_key
-        add_api_key_auth(options[:keys] || [], allow_query_params: options[:allow_query_params] || false)
-      when :jwt
-        add_jwt_auth(options)
-      when :custom
-        handler = block || options[:handler]
-        raise ArgumentError, "Custom authentication strategy requires a handler block" unless handler
-
-        add_custom_auth(&handler)
-
-      else
-        raise ArgumentError, "Unknown authentication strategy: #{strategy}"
-      end
-
+      register_auth_strategy(strategy, options, block || options.delete(:handler))
       @logger.info("Authentication enabled with strategy: #{strategy}")
     end
 
@@ -210,15 +208,16 @@ module VectorMCP
     # @return [void]
     def disable_authentication!
       @auth_manager.disable!
+      @oauth_resource_metadata_url = nil
       @logger.info("Authentication disabled")
     end
 
     # Enable authorization with optional policy configuration block
     # @param block [Proc] optional block for configuring authorization policies
     # @return [void]
-    def enable_authorization!(&block)
+    def enable_authorization!(&)
       @authorization.enable!
-      instance_eval(&block) if block_given?
+      instance_eval(&) if block_given?
       @logger.info("Authorization enabled")
     end
 
@@ -232,29 +231,29 @@ module VectorMCP
     # Add authorization policy for tools
     # @param block [Proc] policy block that receives (user, action, tool)
     # @return [void]
-    def authorize_tools(&block)
-      @authorization.add_policy(:tool, &block)
+    def authorize_tools(&)
+      @authorization.add_policy(:tool, &)
     end
 
     # Add authorization policy for resources
     # @param block [Proc] policy block that receives (user, action, resource)
     # @return [void]
-    def authorize_resources(&block)
-      @authorization.add_policy(:resource, &block)
+    def authorize_resources(&)
+      @authorization.add_policy(:resource, &)
     end
 
     # Add authorization policy for prompts
     # @param block [Proc] policy block that receives (user, action, prompt)
     # @return [void]
-    def authorize_prompts(&block)
-      @authorization.add_policy(:prompt, &block)
+    def authorize_prompts(&)
+      @authorization.add_policy(:prompt, &)
     end
 
     # Add authorization policy for roots
     # @param block [Proc] policy block that receives (user, action, root)
     # @return [void]
-    def authorize_roots(&block)
-      @authorization.add_policy(:root, &block)
+    def authorize_roots(&)
+      @authorization.add_policy(:root, &)
     end
 
     # Check if security features are enabled
@@ -311,6 +310,34 @@ module VectorMCP
 
     private
 
+    # Extract OAuth resource metadata URL from options before they reach strategy constructors
+    # @param options [Hash] the options hash (mutated — :resource_metadata_url is removed)
+    # @return [void]
+    def extract_oauth_metadata!(options)
+      @oauth_resource_metadata_url = options.delete(:resource_metadata_url)
+      warn_on_insecure_oauth_metadata_url(@oauth_resource_metadata_url)
+    end
+
+    # Register the appropriate auth strategy based on the strategy name
+    # @param strategy [Symbol] the strategy type
+    # @param options [Hash] strategy-specific options
+    # @param handler [Proc, nil] custom handler block (for :custom strategy)
+    # @return [void]
+    def register_auth_strategy(strategy, options, handler)
+      case strategy
+      when :api_key
+        add_api_key_auth(options[:keys] || [], allow_query_params: options[:allow_query_params] || false)
+      when :jwt
+        add_jwt_auth(options)
+      when :custom
+        raise ArgumentError, "Custom authentication strategy requires a handler block" unless handler
+
+        add_custom_auth(&handler)
+      else
+        raise ArgumentError, "Unknown authentication strategy: #{strategy}"
+      end
+    end
+
     # Add API key authentication strategy
     # @param keys [Array<String>] array of valid API keys
     # @param allow_query_params [Boolean] whether to accept API keys from query parameters
@@ -331,8 +358,8 @@ module VectorMCP
     # Add custom authentication strategy
     # @param handler [Proc] custom authentication handler block
     # @return [void]
-    def add_custom_auth(&block)
-      strategy = Security::Strategies::Custom.new(&block)
+    def add_custom_auth(&)
+      strategy = Security::Strategies::Custom.new(&)
       @auth_manager.add_strategy(:custom, strategy)
     end
 
@@ -343,11 +370,25 @@ module VectorMCP
         @auth_manager.remove_strategy(strategy_name)
       end
     end
+
+    # Emit a warning when the OAuth resource metadata URL is not HTTPS.
+    # We don't raise because local development against http://localhost is a valid use case.
+    # @param url [String, nil] the configured metadata URL
+    # @return [void]
+    def warn_on_insecure_oauth_metadata_url(url)
+      return if url.nil?
+      return if url.start_with?("https://")
+
+      @logger.warn do
+        "[SECURITY] resource_metadata_url is not HTTPS (#{url}). " \
+          "Use HTTPS in production; plaintext is only acceptable for local development."
+      end
+    end
   end
 
   module Transport
     # Dummy base class placeholder used only for argument validation in tests.
-    # Real transport classes (e.g., Stdio, SSE) are separate concrete classes.
+    # Real transport classes (e.g., HttpStream) are separate concrete classes.
     class Base # :nodoc:
     end
   end

data/lib/vector_mcp/session.rb

@@ -4,6 +4,7 @@ require_relative "sampling/request"
 require_relative "sampling/result"
 require_relative "errors"
 require_relative "request_context"
+require_relative "security/session_context"
 
 module VectorMCP
   # Represents the state of a single client-server connection session in MCP.
@@ -17,7 +18,7 @@ module VectorMCP
   # @attr_reader request_context [RequestContext] The request context for this session.
   class Session
     attr_reader :server_info, :server_capabilities, :protocol_version, :client_info, :client_capabilities, :server, :transport, :id, :request_context
-    attr_accessor :data # For user-defined session-specific storage
+    attr_accessor :data, :security_context # For user-defined session-specific storage and resolved auth context
 
     # Initializes a new session.
     #
@@ -33,6 +34,7 @@ module VectorMCP
       @client_info = nil
       @client_capabilities = nil
       @data = {} # Initialize user data hash
+      @security_context = Security::SessionContext.anonymous
       @logger = server.logger
 
       # Initialize request context
@@ -243,11 +245,11 @@ module VectorMCP
       send_request_kwargs = {}
       send_request_kwargs[:timeout] = timeout if timeout
 
-      # For HTTP transport, we need to use send_request_to_session to target this specific session
+      # Prefer session-targeted request sending when available
       raw_result = if @transport.respond_to?(:send_request_to_session)
                      @transport.send_request_to_session(@id, *send_request_args, **send_request_kwargs)
                    else
-                     # Fallback to generic send_request for other transports
+                     # Fallback to generic send_request for transports without session targeting
                      @transport.send_request(*send_request_args, **send_request_kwargs)
                    end