actionmcp 0.60.2 → 0.71.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eee42f9c43bf618496aab880fc196bcd03620152d243de5570e85892e476372d
-  data.tar.gz: 4a8d6beee9b55bc86df336f5f9c89d90f57fce562e9b051183d6aa657558db9b
+  metadata.gz: 83f504b6f7171acf10239a3873a3cf967243ed8fa598603b72ec3e265cf9ba7a
+  data.tar.gz: 4b50494bcf216f93243d2068c2d9f211c25a9fe5166fb01f21518321716a4d54
 SHA512:
-  metadata.gz: 9b99efaeb97d77b110d5fa735e575af433b8a10d89820cd4c0260bae59c895662a95eb0df1fbec3fc89d6998946dec484412be80bcd594e056c8f3a8220c8ab3
-  data.tar.gz: 311a451a50769764ae19bc0b3460f28a58ab99c68502e0aa856f000fc22de9796c9e4a6d9b51180d34940075e904dbeaed4a825e3d84e8513d2195f5a211da20
+  metadata.gz: e2f3c857fdfd8404660d508ff620500676c71f629b5ac0a7ab0e7190248d25ea81d15eef679cbb14cba5f15ff119e882502de28d830f6c67a10c8ee7254a4301
+  data.tar.gz: 3d44ee314a37df260fbc00c5d7488330f0d0e5e637c5b200a784bf62301b2feb7b330796cd2ff0268a96de70f498d946983aa89c745e6e636e915b37f5d81587

data/README.md

@@ -30,7 +30,7 @@ ActionMCP supports **MCP 2025-06-18** (current) with backward compatibility for
 
 > **Note:** STDIO transport is not supported in ActionMCP. This gem is focused on production-ready, network-based deployments. STDIO is only suitable for desktop or script-based experimentation and is intentionally excluded.
 
-Instead of implementing MCP support from scratch, you can subclass and configure the provided **Prompt**, **Tool**, and **ResourceTemplate** classes to expose your app's functionality to LLMs. 
+Instead of implementing MCP support from scratch, you can subclass and configure the provided **Prompt**, **Tool**, and **ResourceTemplate** classes to expose your app's functionality to LLMs.
 
 ActionMCP handles the underlying MCP message format and routing, so you can adhere to the open standard with minimal effort.
 
@@ -52,12 +52,17 @@ After adding the gem, run the install generator to set up the basic ActionMCP st
 
 ```bash
 bundle install
-bin/rails action_mcp:install:migrations
-bin/rails db:migrate
-bin/rails generate action_mcp:install
+bin/rails action_mcp:install:migrations  # Copy migrations from the engine
+bin/rails generate action_mcp:install    # Creates base classes and configuration
+bin/rails db:migrate                     # Creates necessary database tables
 ```
 
-This will create the base application classes, configuration file, and necessary database tables for ActionMCP to function properly.
+The `action_mcp:install` generator will:
+- Create base application classes (ApplicationGateway, ApplicationMCPTool, etc.)
+- Generate the MCP configuration file (`config/mcp.yml`)
+- Set up the basic directory structure for MCP components
+
+Database migrations are copied separately using `bin/rails action_mcp:install:migrations`.
 
 ## Core Components
 
@@ -88,18 +93,18 @@ class AnalyzeCodePrompt < ApplicationMCPPrompt
   def perform
     render(text: "Please analyze this #{language} code for improvements:")
     render(text: code)
-    
+
     # You can add assistant messages too
     render(text: "Here are some things to focus on in your analysis:", role: :assistant)
-    
+
     # Even add resources if needed
-    render(resource: "file://documentation/#{language.downcase}_style_guide.pdf", 
-           mime_type: "application/pdf", 
+    render(resource: "file://documentation/#{language.downcase}_style_guide.pdf",
+           mime_type: "application/pdf",
            blob: get_style_guide_pdf(language))
   end
-  
+
   private
-  
+
   def get_style_guide_pdf(language)
     # Implementation to retrieve style guide as base64
   end
@@ -130,25 +135,25 @@ class CalculateSumTool < ApplicationMCPTool
   tool_name "calculate_sum"
   description "Calculate the sum of two numbers"
 
-  property :a, type: "number", description: "First number", required: true
-  property :b, type: "number", description: "Second number", required: true
-  
+  property :a, type: "number", description: "The first number", required: true
+  property :b, type: "number", description: "The second number", required: true
+
   def perform
     sum = a + b
     render(text: "Calculating #{a} + #{b}...")
     render(text: "The sum is #{sum}")
-    
+
     # You can render errors if needed
     if sum > 1000
       render(error: ["Warning: Sum exceeds recommended limit"])
     end
-    
+
     # Or even images
     render(image: generate_visualization(a, b), mime_type: "image/png")
   end
-  
+
   private
-  
+
   def generate_visualization(a, b)
     # Implementation to create a visualization as base64
   end
@@ -164,7 +169,7 @@ result = sum_tool.call
 
 ### ActionMCP::ResourceTemplate
 
-`ActionMCP::ResourceTemplate` facilitates the creation of URI templates for dynamic resources that LLMs can access. 
+`ActionMCP::ResourceTemplate` facilitates the creation of URI templates for dynamic resources that LLMs can access.
 This allows models to request specific data using parameterized URIs.
 
 **Example:**
@@ -197,23 +202,23 @@ end
 
 ```ruby
 before_resolve do |template|
-  logger.tagged("ProductsTemplate") { logger.info("Starting to resolve product: #{template.product_id}") }
+  # Starting to resolve product: #{template.product_id}
 end
 
 after_resolve do |template|
-  logger.tagged("ProductsTemplate") { logger.info("Finished resolving product resource for product: #{template.product_id}") }
+  # Finished resolving product resource for product: #{template.product_id}
 end
 
 around_resolve do |template, block|
   start_time = Time.current
-  logger.tagged("ProductsTemplate") { logger.info("Starting resolution for product: #{template.product_id}") }
+  # Starting resolution for product: #{template.product_id}
 
   resource = block.call
 
   if resource
-    logger.tagged("ProductsTemplate") { logger.info("Product #{template.product_id} resolved successfully in #{Time.current - start_time}s") }
+    # Product #{template.product_id} resolved successfully in #{Time.current - start_time}s
   else
-    logger.tagged("ProductsTemplate") { logger.info("Product #{template.product_id} not found") }
+    # Product #{template.product_id} not found
   end
 
   resource
@@ -237,36 +242,18 @@ module Tron
     config.action_mcp.version = "1.2.3"                               # defaults to "0.0.1"
     config.action_mcp.logging_enabled = true                          # defaults to true
     config.action_mcp.logging_level = :info                           # defaults to :info, can be :debug, :info, :warn, :error, :fatal
-    config.action_mcp.vibed_ignore_version = false                    # defaults to false, set to true to ignore client protocol version mismatches
   end
 end
 ```
 
 For dynamic versioning, consider adding the `rails_app_version` gem.
 
-### Protocol Version Compatibility
-
-By default, ActionMCP requires clients to use the exact protocol version supported by the server (currently "2025-03-26"). If the client specifies a different version during initialization, the request will be rejected with an error.
-
-To support clients with incompatible protocol versions, you can enable the `vibed_ignore_version` option:
-
-```ruby
-# In config/application.rb or an initializer
-Rails.application.config.action_mcp.vibed_ignore_version = true
-```
-
-When enabled, the server will ignore protocol version mismatches from clients and always use the latest supported version. This is useful for:
-- Development environments with older client libraries
-- Supporting clients that cannot be easily updated
-- Situations where protocol differences are minor and known to be compatible
-
-> **Note:** Using `vibed_ignore_version = true` in production is not recommended as it may lead to unexpected behavior if clients rely on specific protocol features that differ between versions.
 
 ### PubSub Configuration
 
 ActionMCP uses a pub/sub system for real-time communication. You can choose between several adapters:
 
-1. **SolidCable** - Database-backed pub/sub (no Redis required)
+1. **SolidMCP** - Database-backed pub/sub (no Redis required)
 2. **Simple** - In-memory pub/sub for development and testing
 3. **Redis** - Redis-backed pub/sub (if you prefer Redis)
 
@@ -275,7 +262,7 @@ ActionMCP uses a pub/sub system for real-time communication. You can choose betw
 If you were previously using ActionCable with ActionMCP, you will need to migrate to the new PubSub system. Here's how:
 
 1. Remove the ActionCable dependency from your Gemfile (if you don't need it for other purposes)
-2. Install one of the PubSub adapters (SolidCable recommended)
+2. Install one of the PubSub adapters (SolidMCP recommended)
 3. Create a configuration file at `config/mcp.yml` (you can use the generator: `bin/rails g action_mcp:config`)
 4. Run your tests to ensure everything works correctly
 
@@ -285,7 +272,7 @@ Configure your adapter in `config/mcp.yml`:
 
 ```yaml
 development:
-  adapter: solid_cable
+  adapter: solid_mcp
   polling_interval: 0.1.seconds
   # Thread pool configuration (optional)
   # min_threads: 5     # Minimum number of threads in the pool
@@ -296,10 +283,10 @@ test:
   adapter: test    # Uses the simple in-memory adapter
 
 production:
-  adapter: solid_cable
+  adapter: solid_mcp
   polling_interval: 0.5.seconds
   # Optional: connects_to: cable  # If using a separate database
-  
+
   # Thread pool configuration for high-traffic environments
   min_threads: 10     # Minimum number of threads in the pool
   max_threads: 20     # Maximum number of threads in the pool
@@ -339,7 +326,7 @@ production:
   adapter: redis
   url: <%= ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" } %>
   channel_prefix: your_app_production
-  
+
   # Thread pool configuration for high-traffic environments
   min_threads: 10     # Minimum number of threads in the pool
   max_threads: 20     # Maximum number of threads in the pool
@@ -391,7 +378,7 @@ session_store_type: volatile
 # Client-specific session store type (falls back to session_store_type if not specified)
 client_session_store_type: volatile
 
-# Server-specific session store type (falls back to session_store_type if not specified)  
+# Server-specific session store type (falls back to session_store_type if not specified)
 server_session_store_type: active_record
 ```
 
@@ -488,7 +475,7 @@ You can configure the thread pool in your `config/mcp.yml`:
 
 ```yaml
 production:
-  adapter: solid_cable
+  adapter: solid_mcp
   # Thread pool configuration
   min_threads: 10    # Minimum number of threads to keep in the pool
   max_threads: 20    # Maximum number of threads the pool can grow to
@@ -526,7 +513,7 @@ bin/rails generate action_mcp:install
 
 This will create:
 - `app/mcp/prompts/application_mcp_prompt.rb` - Base prompt class
-- `app/mcp/tools/application_mcp_tool.rb` - Base tool class  
+- `app/mcp/tools/application_mcp_tool.rb` - Base tool class
 - `app/mcp/resource_templates/application_mcp_res_template.rb` - Base resource template class
 - `app/mcp/application_gateway.rb` - Gateway for authentication
 - `config/mcp.yml` - Configuration file with example settings for all environments
@@ -557,7 +544,7 @@ class ApplicationGateway < ActionMCP::Gateway
 
     payload = ActionMCP::JwtDecoder.decode(token)
     user = resolve_user(payload)
-    
+
     raise ActionMCP::UnauthorizedError, "Unauthorized" unless user
 
     # Return a hash with all identified_by attributes
@@ -580,13 +567,13 @@ You can identify connections by multiple attributes:
 ```ruby
 class ApplicationGateway < ActionMCP::Gateway
   identified_by :user, :organization
-  
+
   protected
-  
+
   def authenticate!
     # ... authentication logic ...
-    
-    { 
+
+    {
       user: user,
       organization: user.organization
     }
@@ -654,7 +641,7 @@ Common middleware that can cause issues:
 - **Rack::Cors** - CORS headers meant for browsers
 - Any middleware assuming HTML responses or cookie-based authentication
 
-An example of a minimal `mcp_vanilla.ru` file is located in the dummy app : test/dummy/mcp_vanilla.ru. 
+An example of a minimal `mcp_vanilla.ru` file is located in the dummy app : test/dummy/mcp_vanilla.ru.
 This file is a minimal Rack application that only includes the essential middleware needed for MCP server operation, avoiding conflicts with web-specific middleware.
 But remember to add any instrumentation or logging middleware you need, as the minimal setup will not include them by default.
 
@@ -662,7 +649,7 @@ But remember to add any instrumentation or logging middleware you need, as the m
 
 ## Production Deployment of MCPS0
 
-In production, **MCPS0** (the MCP server) is a standard Rack application. You can run it using any Rack-compatible server (such as Puma, Unicorn, or Passenger). 
+In production, **MCPS0** (the MCP server) is a standard Rack application. You can run it using any Rack-compatible server (such as Puma, Unicorn, or Passenger).
 
 > **For best performance and concurrency, it is highly recommended to use a modern, synchronous server like [Falcon](https://github.com/socketry/falcon)**. Falcon is optimized for streaming and concurrent workloads, making it ideal for MCP servers. You can still use Puma, Unicorn, or Passenger, but Falcon will generally provide superior throughput and responsiveness for real-time and streaming use cases.
 
@@ -722,7 +709,7 @@ First, install ActionMCP to create base classes and configuration:
 
 ```bash
 bin/rails action_mcp:install:migrations  # to copy the migrations
-bin/rails generate action_mcp:install 
+bin/rails generate action_mcp:install
 ```
 
 This will create the base application classes, configuration file, and authentication gateway in your app directory.

data/app/controllers/action_mcp/application_controller.rb

@@ -12,6 +12,7 @@ module ActionMCP
     include ActionController::Live
     include ActionController::Instrumentation
 
+
     # Provides the ActionMCP::Session for the current request.
     # Handles finding existing sessions via header/param or initializing a new one.
     # Specific controllers/handlers might need to enforce session ID presence based on context.
@@ -46,8 +47,12 @@ module ActionMCP
         return render_not_found("Session has been terminated.")
       end
 
+      # Authenticate the request via gateway
+      authenticate_gateway!
+      return if performed?
+
       last_event_id = request.headers["Last-Event-ID"].presence
-      Rails.logger.info "Unified SSE (GET): Resuming from Last-Event-ID: #{last_event_id}" if last_event_id
+      Rails.logger.info "Unified SSE (GET): Resuming from Last-Event-ID: #{last_event_id}" if last_event_id && ActionMCP.configuration.verbose_logging
 
       response.headers["Content-Type"] = "text/event-stream"
       response.headers["X-Accel-Buffering"] = "no"
@@ -56,7 +61,7 @@ module ActionMCP
       # Add MCP-Protocol-Version header for established sessions
       response.headers["MCP-Protocol-Version"] = session.protocol_version
 
-      Rails.logger.info "Unified SSE (GET): Starting stream for session: #{session.id}"
+      Rails.logger.info "Unified SSE (GET): Starting stream for session: #{session.id}" if ActionMCP.configuration.verbose_logging
 
       sse = SSE.new(response.stream)
       listener = SSEListener.new(session)
@@ -80,12 +85,12 @@ module ActionMCP
         begin
           missed_events = session.get_sse_events_after(last_event_id.to_i)
           if missed_events.any?
-            Rails.logger.info "Unified SSE (GET): Sending #{missed_events.size} missed events for session: #{session.id}"
+            Rails.logger.info "Unified SSE (GET): Sending #{missed_events.size} missed events for session: #{session.id}" if ActionMCP.configuration.verbose_logging
             missed_events.each do |event|
               sse.write(event.to_sse)
             end
           else
-            Rails.logger.info "Unified SSE (GET): No missed events to send for session: #{session.id}"
+            Rails.logger.info "Unified SSE (GET): No missed events to send for session: #{session.id}" if ActionMCP.configuration.verbose_logging
           end
         rescue StandardError => e
           Rails.logger.error "Unified SSE (GET): Error sending missed events: #{e.message}"
@@ -111,7 +116,7 @@ module ActionMCP
             Rails.logger.warn "Unified SSE (GET): Heartbeat timed out for session: #{session.id}, closing."
             connection_active.make_false
           rescue StandardError => e
-            Rails.logger.debug "Unified SSE (GET): Heartbeat error for session: #{session.id}: #{e.message}"
+            Rails.logger.debug "Unified SSE (GET): Heartbeat error for session: #{session.id}: #{e.message}" if ActionMCP.configuration.verbose_logging
             connection_active.make_false
           end
         else
@@ -122,11 +127,11 @@ module ActionMCP
       heartbeat_task = Concurrent::ScheduledTask.execute(heartbeat_interval, &heartbeat_sender)
       sleep 0.1 while connection_active.true? && !response.stream.closed?
     rescue ActionController::Live::ClientDisconnected, IOError => e
-      Rails.logger.debug "Unified SSE (GET): Client disconnected for session: #{session&.id}: #{e.message}"
+      Rails.logger.debug "Unified SSE (GET): Client disconnected for session: #{session&.id}: #{e.message}" if ActionMCP.configuration.verbose_logging
     rescue StandardError => e
       Rails.logger.error "Unified SSE (GET): Unexpected error for session: #{session&.id}: #{e.class} - #{e.message}\n#{e.backtrace.join("\n")}"
     ensure
-      Rails.logger.debug "Unified SSE (GET): Cleaning up connection for session: #{session&.id}"
+      Rails.logger.debug "Unified SSE (GET): Cleaning up connection for session: #{session&.id}" if ActionMCP.configuration.verbose_logging
       heartbeat_active&.make_false
       heartbeat_task&.cancel
       listener&.stop
@@ -143,7 +148,7 @@ module ActionMCP
     # @route POST /mcp
     def create
       unless post_accept_headers_valid?
-        id = extract_jsonrpc_id_from_params
+        id = extract_jsonrpc_id_from_request
         return render_not_acceptable(post_accept_headers_error_message, id)
       end
 
@@ -157,10 +162,9 @@ module ActionMCP
       session = mcp_session
 
       # Validate MCP-Protocol-Version header for non-initialize requests
-      # Temporarily disabled to debug session issues
-      # return unless validate_protocol_version_header
+      return unless validate_protocol_version_header
 
-      unless is_initialize_request
+      unless initialization_related_request?(jsonrpc_params)
         if session_initially_missing
           id = jsonrpc_params.respond_to?(:id) ? jsonrpc_params.id : nil
           return render_bad_request("Mcp-Session-Id header is required for this request.", id)
@@ -178,6 +182,14 @@ module ActionMCP
         response.headers[MCP_SESSION_ID_HEADER] = session.id
       end
 
+      # Authenticate the request via gateway (skipped for initialization-related requests)
+      if initialization_related_request?(jsonrpc_params)
+        # Skipping authentication for initialization request: #{jsonrpc_params.method}
+      else
+        authenticate_gateway!
+        return if performed?
+      end
+
       # Use return mode for the transport handler when we need to capture responses
       transport_handler = Server::TransportHandler.new(session, messaging_mode: :return)
       json_rpc_handler = Server::JsonRpcHandler.new(transport_handler)
@@ -185,7 +197,7 @@ module ActionMCP
       result = json_rpc_handler.call(jsonrpc_params)
       process_handler_results(result, session, session_initially_missing, is_initialize_request)
     rescue ActionController::Live::ClientDisconnected, IOError => e
-      Rails.logger.debug "Unified SSE (POST): Client disconnected during response: #{e.message}"
+      Rails.logger.debug "Unified SSE (POST): Client disconnected during response: #{e.message}" if ActionMCP.configuration.verbose_logging
       begin
         response.stream&.close
       rescue StandardError
@@ -210,9 +222,13 @@ module ActionMCP
         return head :no_content
       end
 
+      # Authenticate the request via gateway
+      authenticate_gateway!
+      return if performed?
+
       begin
         session.close!
-        Rails.logger.info "Unified DELETE: Terminated session: #{session.id}"
+        Rails.logger.info "Unified DELETE: Terminated session: #{session.id}" if ActionMCP.configuration.verbose_logging
         head :no_content
       rescue StandardError => e
         Rails.logger.error "Unified DELETE: Error terminating session #{session.id}: #{e.class} - #{e.message}"
@@ -222,24 +238,32 @@ module ActionMCP
 
     private
 
-    # Validates the MCP-Protocol-Version header for non-initialize requests
+    # Validates the MCP-Protocol-Version header for non-initialization requests
     # Returns true if valid, renders error and returns false if invalid
     def validate_protocol_version_header
-      # Skip validation for initialize requests
-      return true if check_if_initialize_request(jsonrpc_params)
+      # Skip validation for initialization-related requests
+      return true if initialization_related_request?(jsonrpc_params)
 
-      header_version = request.headers["MCP-Protocol-Version"]
+      # Check for both case variations of the header (spec uses MCP-Protocol-Version)
+      header_version = request.headers["MCP-Protocol-Version"] || request.headers["mcp-protocol-version"]
       session = mcp_session
 
-      # If header is missing, assume 2025-03-26 for backward compatibility
+      # If header is missing, assume 2025-03-26 for backward compatibility as per spec
       if header_version.nil?
-        Rails.logger.debug "MCP-Protocol-Version header missing, assuming 2025-03-26 for backward compatibility"
+        ActionMCP.logger.debug "MCP-Protocol-Version header missing, assuming 2025-03-26 for backward compatibility"
         return true
       end
 
+      # Handle array values (take the last one as per TypeScript SDK)
+      if header_version.is_a?(Array)
+        header_version = header_version.last
+      end
+
       # Check if the header version is supported
       unless ActionMCP::SUPPORTED_VERSIONS.include?(header_version)
-        render_bad_request("Unsupported MCP-Protocol-Version: #{header_version}")
+        supported_versions = ActionMCP::SUPPORTED_VERSIONS.join(", ")
+        ActionMCP.logger.warn "Unsupported MCP-Protocol-Version: #{header_version}. Supported versions: #{supported_versions}"
+        render_protocol_version_error("Unsupported MCP-Protocol-Version: #{header_version}. Supported versions: #{supported_versions}")
         return false
       end
 
@@ -247,12 +271,13 @@ module ActionMCP
       if session && session.initialized?
         negotiated_version = session.protocol_version
         if header_version != negotiated_version
-          Rails.logger.warn "MCP-Protocol-Version mismatch: header=#{header_version}, negotiated=#{negotiated_version}"
-          render_bad_request("MCP-Protocol-Version header (#{header_version}) does not match negotiated version (#{negotiated_version})")
+          ActionMCP.logger.warn "MCP-Protocol-Version mismatch: header=#{header_version}, negotiated=#{negotiated_version}"
+          render_protocol_version_error("MCP-Protocol-Version header (#{header_version}) does not match negotiated version (#{negotiated_version})")
           return false
         end
       end
 
+      ActionMCP.logger.debug "MCP-Protocol-Version header validation passed: #{header_version}"
       true
     end
 
@@ -260,12 +285,12 @@ module ActionMCP
     # Note: This doesn't save the new session; that happens upon first use or explicitly.
     def find_or_initialize_session
       session_id = extract_session_id
+      session_store = ActionMCP::Server.session_store
+
       if session_id
-        session = Server.session_store.load_session(session_id)
-        # Session protocol version is set during initialization and should not be overridden
-        session
+        session_store.load_session(session_id)
       else
-        Server.session_store.create_session(nil, protocol_version: ActionMCP::DEFAULT_PROTOCOL_VERSION)
+        session_store.create_session(nil, protocol_version: ActionMCP::DEFAULT_PROTOCOL_VERSION)
       end
     end
 
@@ -305,6 +330,13 @@ module ActionMCP
       payload.method == "initialize"
     end
 
+    # Checks if the request is related to initialization (initialize or notifications/initialized)
+    def initialization_related_request?(payload)
+      return false unless payload.respond_to?(:method) && !jsonrpc_params_batch?
+
+      %w[initialize notifications/initialized].include?(payload.method)
+    end
+
     # Processes the results from the JsonRpcHandler.
     def process_handler_results(result, session, session_initially_missing, is_initialize_request)
       # Handle empty result (notifications)
@@ -364,7 +396,7 @@ module ActionMCP
       rescue StandardError
         nil
       end
-      Rails.logger.debug "Unified SSE (POST): Response stream closed."
+      Rails.logger.debug "Unified SSE (POST): Response stream closed." if ActionMCP.configuration.verbose_logging
     end
 
     # Helper to write a JSON payload as an SSE event with a unique ID.
@@ -396,7 +428,7 @@ module ActionMCP
       begin
         retention_period = session.sse_event_retention_period
         count = session.cleanup_old_sse_events(retention_period)
-        Rails.logger.debug "Cleaned up #{count} old SSE events for session: #{session.id}" if count.positive?
+        Rails.logger.debug "Cleaned up #{count} old SSE events for session: #{session.id}" if count.positive? && ActionMCP.configuration.verbose_logging
       rescue StandardError => e
         Rails.logger.error "Error cleaning up old SSE events: #{e.message}"
       end
@@ -415,6 +447,12 @@ module ActionMCP
       render json: { jsonrpc: "2.0", id: id, error: { code: -32_600, message: message } }
     end
 
+    # Renders a 400 Bad Request response for protocol version errors as per MCP spec
+    def render_protocol_version_error(message = "Protocol Version Error", id = nil)
+      id ||= extract_jsonrpc_id_from_request
+      render json: { jsonrpc: "2.0", id: id, error: { code: -32_000, message: message } }, status: :bad_request
+    end
+
     # Renders a 404 Not Found response with a JSON-RPC-like error structure.
     def render_not_found(message = "Not Found", id = nil)
       id ||= extract_jsonrpc_id_from_request
@@ -463,5 +501,34 @@ module ActionMCP
         nil
       end
     end
+
+    # Authenticates the request using the configured gateway
+    def authenticate_gateway!
+      # Skip authentication for initialization-related requests in POST method
+      if request.post? && defined?(jsonrpc_params) && jsonrpc_params
+        return if initialization_related_request?(jsonrpc_params)
+      end
+
+      gateway_class = ActionMCP.configuration.gateway_class
+      return unless gateway_class # Skip if no gateway configured
+
+      gateway = gateway_class.new
+      gateway.call(request)
+    rescue ActionMCP::UnauthorizedError => e
+      render_unauthorized(e.message)
+    end
+
+    # Renders an unauthorized response
+    def render_unauthorized(message = "Unauthorized", id = nil)
+      id ||= extract_jsonrpc_id_from_request
+
+      # Add WWW-Authenticate header for OAuth discovery as per spec
+      auth_methods = ActionMCP.configuration.authentication_methods || []
+      if auth_methods.include?("oauth")
+        response.headers["WWW-Authenticate"] = 'Bearer realm="MCP API"'
+      end
+
+      render json: { jsonrpc: "2.0", id: id, error: { code: -32_000, message: message } }, status: :unauthorized
+    end
   end
 end

data/app/controllers/action_mcp/oauth/metadata_controller.rb

@@ -25,12 +25,12 @@ module ActionMCP
         }
 
         # Add optional fields based on configuration
-        if oauth_config["enable_dynamic_registration"]
+        if oauth_config[:enable_dynamic_registration]
           metadata[:registration_endpoint] = registration_endpoint
         end
 
-        if oauth_config["jwks_uri"]
-          metadata[:jwks_uri] = oauth_config["jwks_uri"]
+        if oauth_config[:jwks_uri]
+          metadata[:jwks_uri] = oauth_config[:jwks_uri]
         end
 
         render json: metadata
@@ -60,11 +60,11 @@ module ActionMCP
       end
 
       def oauth_config
-        @oauth_config ||= ActionMCP.configuration.oauth_config || {}
+        @oauth_config ||= HashWithIndifferentAccess.new(ActionMCP.configuration.oauth_config || {})
       end
 
       def issuer_url
-        @issuer_url ||= oauth_config["issuer_url"] || request.base_url
+        @issuer_url ||= oauth_config.fetch(:issuer_url, request.base_url)
       end
 
       def authorization_endpoint
@@ -93,36 +93,36 @@ module ActionMCP
 
       def grant_types_supported
         grants = [ "authorization_code" ]
-        grants << "refresh_token" if oauth_config["enable_refresh_tokens"]
-        grants << "client_credentials" if oauth_config["enable_client_credentials"]
+        grants << "refresh_token" if oauth_config[:enable_refresh_tokens]
+        grants << "client_credentials" if oauth_config[:enable_client_credentials]
         grants
       end
 
       def token_endpoint_auth_methods_supported
         methods = [ "client_secret_basic", "client_secret_post" ]
-        methods << "none" if oauth_config["allow_public_clients"]
+        methods << "none" if oauth_config[:allow_public_clients]
         methods
       end
 
       def scopes_supported
-        oauth_config["scopes_supported"] || [ "mcp:tools", "mcp:resources", "mcp:prompts" ]
+        oauth_config.fetch(:scopes_supported, [ "mcp:tools", "mcp:resources", "mcp:prompts" ])
       end
 
       def code_challenge_methods_supported
         methods = []
-        if oauth_config["pkce_required"] || oauth_config["pkce_supported"]
+        if oauth_config[:pkce_required] || oauth_config[:pkce_supported]
           methods << "S256"
-          methods << "plain" if oauth_config["allow_plain_pkce"]
+          methods << "plain" if oauth_config[:allow_plain_pkce]
         end
         methods
       end
 
       def service_documentation
-        oauth_config["service_documentation"] || "#{request.base_url}/docs"
+        oauth_config.fetch(:service_documentation, "#{request.base_url}/docs")
       end
 
       def resource_documentation
-        oauth_config["resource_documentation"] || "#{request.base_url}/docs/api"
+        oauth_config.fetch(:resource_documentation, "#{request.base_url}/docs/api")
       end
     end
   end