actionmcp 0.111.1 → 0.200.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 278cf7ec84daea1af24b29413c1a0d4a0c56793f8aebff32c2ca10953bde715b
-  data.tar.gz: 1bf9dbb492f66f611523a6c802a84565470ff5323459a76d420ab7d5393a826b
+  metadata.gz: 5959fcdcfdeed27a18bc9723f51bbfb3699d0983172875e4c8dc9cc6873eadf4
+  data.tar.gz: 04ce30167f6377c54dc92e574dc50d027bb9a6f76355d3c96bde33de99ada463
 SHA512:
-  metadata.gz: 243bb2bf2d3c844e25b7a83fd74f7aa1c004742124caa1da723d30c25a24ec8211e6eb98f96ea0e53eaa429d66a334a770ffcf6e2186b1096c451ef1e268195a
-  data.tar.gz: 6b4cfd0bd035f6af788ae8e61215fa6a64e88177369a62a5a507c67c3812494dd06832c26753519c77c826e9985747469443ecc9a073d713a4e7424cc64f6866
+  metadata.gz: 7cd9b2994aca071515bd4141186ba95e352f0af355b817b38e45df672ce85d4b404e67df88d98523bb7b8bd5da60ed05aecf163fe5371a24f199c04eb5a3915a
+  data.tar.gz: 89de790b55becb12ab8c991a0fffe569c70ebef2ec01a0d29135313708be7cae2a5aa27a6fd9de295c9a5d078e6d4ffe57b91c5395a4133e1c29408a46c35402

data/README.md

@@ -24,13 +24,20 @@ This means an AI (like an LLM) can request information or actions from your appl
 
 ## Protocol Support
 
-ActionMCP supports **MCP 2025-06-18** (current) with backward compatibility for **MCP 2025-03-26**. The protocol implementation is fully compliant with the MCP specification, including:
+ActionMCP targets the released **MCP 2025-11-25** protocol. Older protocol versions and unreleased draft versions are not accepted. Core handling includes:
 
 - **JSON-RPC 2.0** transport layer
 - **Capability negotiation** during initialization
 - **Error handling** with proper error codes (-32601 for method not found, -32002 for consent required)
-- **Session management** with resumable sessions
-- **Change notifications** for dynamic capability updates
+- **Stateful session management** with explicit termination
+- **Tasks, tools, prompts, resources, completion, logging, sampling, roots, and elicitation** message handling
+
+The built-in Streamable HTTP endpoint returns one `application/json` message for
+requests and intentionally returns HTTP 405 for GET because it does not provide
+SSE streams. That behavior is allowed by the transport specification. Outbound
+server requests and notifications are retained in session message storage, but
+an application needs an SSE or custom transport to push those messages to a
+client outside the response to an active request.
 
 For a detailed (and entertaining) breakdown of protocol versions, features, and our design decisions, see [The Hitchhiker's Guide to MCP](The_Hitchhikers_Guide_to_MCP.md).
 
@@ -331,20 +338,12 @@ Call it as a task from a client by adding top-level `task` params (creates a Tas
 ```
 
 Poll task status with `tasks/get` or fetch the result with `tasks/result`.
-By default, `tasks/result` uses spec-aligned blocking HTTP: if the task is still working, the request waits until the task reaches `completed`, `failed`, `cancelled`, or `input_required`, then returns one JSON response. Configure the wait bounds for your Rails app:
+As required by MCP 2025-11-25, `tasks/result` waits while a task is in any non-terminal state, including `input_required`, and returns once it reaches `completed`, `failed`, or `cancelled`. The internal database polling interval must be positive and can be tuned for your Rails app:
 
 ```ruby
-config.action_mcp.tasks_result_strategy = :blocking_http
-config.action_mcp.tasks_result_timeout = 30.seconds
 config.action_mcp.tasks_result_poll_interval = 0.25.seconds
 ```
 
-Rails apps that cannot hold request workers open can opt into `:polling_only`, where clients must poll `tasks/get` until terminal or `input_required` before calling `tasks/result`. This is a deliberate MCP spec deviation:
-
-```ruby
-config.action_mcp.tasks_result_strategy = :polling_only
-```
-
 Use `tasks/cancel` to stop non-terminal tasks. `tasks/list` returns tasks in recent-first order and always paginates (default 50 per page, or `pagination_page_size` if configured). The response includes an opaque `nextCursor` when more results are available; treat cursors as opaque tokens.
 
 ### ActionMCP::ResourceTemplate
@@ -455,7 +454,7 @@ ActionMCP provides comprehensive documentation across multiple specialized guide
 
 ### Protocol & Technical Details
 - **[🚀 The Hitchhiker's Guide to MCP](The_Hitchhikers_Guide_to_MCP.md)** - Protocol versions and migration
-  - Comprehensive comparison of MCP protocol versions (2024-11-05, 2025-03-26, 2025-06-18)
+  - Historical protocol comparison and the current 2025-11-25 behavior
   - Design decisions and architectural rationale
   - Migration paths and compatibility considerations
   - Feature evolution and technical specifications (*Don't Panic!*)
@@ -628,7 +627,7 @@ session_store = ActionMCP::Server.session_store
 # Create a session
 session = session_store.create_session(session_id, {
   status: "initialized",
-  protocol_version: "2025-03-26",
+  protocol_version: "2025-11-25",
   # ... other session attributes
 })
 
@@ -750,7 +749,7 @@ ActionMCP provides a Gateway system for handling authentication. The Gateway all
 
 ActionMCP uses a Gateway pattern with pluggable identifiers for authentication. You can implement custom authentication strategies using session-based auth, API keys, bearer tokens, or integrate with existing authentication systems like Warden, Devise, or external OAuth providers.
 
-> **Note:** Auth errors return HTTP 200 with a JSON-RPC error payload (not HTTP 401). This is correct per the MCP specification — all MCP communication uses JSON-RPC over HTTP, and protocol-level errors are expressed within the JSON-RPC envelope. The `initialize` request bypasses authentication per MCP spec.
+> **Note:** When a Gateway is configured, it authenticates every MCP HTTP request, including `initialize`, GET, and DELETE. Authentication failures return HTTP 401 with a `WWW-Authenticate: Bearer` challenge and a JSON-RPC error body.
 
 ### Creating an ApplicationGateway
 
@@ -881,7 +880,7 @@ If your Rails application uses middleware that interferes with MCP server operat
 
 bundle exec rails s -c mcp_vanilla.ru -p 62770
 # Or with Falcon:
-bundle exec falcon serve --bind http://0.0.0.0:62770 --config mcp_vanilla.ru
+bundle exec falcon serve --bind http://127.0.0.1:62770 --config mcp_vanilla.ru
 ```
 
 Common middleware that can cause issues:
@@ -1115,6 +1114,7 @@ bundle exec rails action_mcp:list
 bundle exec rails action_mcp:list_tools
 bundle exec rails action_mcp:list_prompts
 bundle exec rails action_mcp:list_resources
+bundle exec rails action_mcp:list_widgets
 bundle exec rails action_mcp:list_profiles
 
 # Show configuration and statistics
@@ -1125,6 +1125,14 @@ bundle exec rails action_mcp:stats
 bundle exec rails action_mcp:show_profile[profile_name]
 ```
 
+### Linting
+
+RuboCop runs as a git pre-commit hook on staged Ruby files. Enable it once per clone:
+
+```bash
+git config core.hooksPath .githooks
+```
+
 ## Error Handling and Troubleshooting
 
 ActionMCP provides comprehensive error handling following the JSON-RPC 2.0 specification:
@@ -1264,7 +1272,7 @@ bin/rails action_mcp:list_profiles
 # Show detailed information about a specific profile
 bin/rails action_mcp:show_profile[admin]
 
-# List all tools, prompts, resources, and profiles
+# List all tools, prompts, resources, UI widgets, and profiles
 bin/rails action_mcp:list
 ```
 
@@ -1297,7 +1305,7 @@ For comprehensive client documentation, including examples, session management,
 - **Implement proper authorization** in your tools and prompts
 - **Validate all inputs** using property definitions and Rails validations
 - **Use consent management** for sensitive operations
-- **Protect against DNS rebinding**: ActionMCP validates the `Origin` header on every request. If `Origin` is present and its host doesn't match the server's own host, the server returns HTTP 403 with a JSON-RPC error body (no `id`), as required by the MCP spec. Non-browser clients (Claude Desktop, CLI tools) don't send `Origin` and are unaffected. To allow additional trusted origins, configure `allowed_origins`:
+- **Protect against DNS rebinding**: ActionMCP validates the `Origin` header on every request without trusting the request's `Host` header. Loopback origins (`localhost`, `127.0.0.1`, and `::1`) are allowed by default. Other browser origins receive HTTP 403 unless their host is explicitly listed in `allowed_origins`. Non-browser clients that omit `Origin` are unaffected:
 
   ```ruby
   # config/initializers/action_mcp.rb

data/Rakefile

@@ -6,3 +6,6 @@ APP_RAKEFILE = File.expand_path('test/dummy/Rakefile', __dir__)
 load 'rails/tasks/engine.rake'
 
 require 'bundler/gem_tasks'
+
+task test: "app:test"
+task default: :test

data/app/controllers/action_mcp/application_controller.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
 module ActionMCP
-  # Implements the MCP endpoints according to the 2025-03-26 specification.
-  # Supports GET for server-initiated SSE streams, POST for client messages
-  # (responding with JSON or SSE), and optionally DELETE for session termination.
+  # Implements the MCP endpoints according to the 2025-11-25 specification.
+  # POST returns one JSON message, DELETE terminates sessions, and GET returns
+  # 405 because the built-in transport does not provide SSE streams.
   class ApplicationController < ActionController::API
     MCP_SESSION_ID_HEADER = "Mcp-Session-Id"
+    POST_ACCEPT_MEDIA_TYPES = %w[application/json text/event-stream].freeze
 
     include Engine.routes.url_helpers
     include JSONRPC_Rails::ControllerHelpers
@@ -15,11 +16,11 @@ module ActionMCP
     # (see engine.rb) so invalid requests are rejected before routing.
 
     # 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.
-    # @return [ActionMCP::Session] The session object (might be unsaved if new)
+    # @return [ActionMCP::Session, nil] The session identified by the request header.
     def mcp_session
-      @mcp_session ||= find_or_initialize_session
+      return @mcp_session if defined?(@mcp_session)
+
+      @mcp_session = load_session(extract_session_id)
     end
 
     # Provides a unique key for caching or pub/sub based on the session ID.
@@ -35,13 +36,25 @@ module ActionMCP
     # ROUTE: /, name: mcp_get, via: GET
     # <rails-lens:routes:end>
     def show
+      return unless authenticate_gateway!
+
+      if (session_id = extract_session_id)
+        session = load_session(session_id)
+        return render_not_found("Session not found.") unless session
+        return render_not_found("Session has been terminated.") if session.status == "closed"
+
+        @mcp_session = session
+        return unless configure_gateway_session!(session)
+        return unless validate_protocol_version_header(session)
+      end
+
       # MCP Streamable HTTP spec allows servers to return 405 if they don't support SSE.
       # ActionMCP uses Tasks for async operations instead of SSE streaming.
       response.headers["Allow"] = "POST, DELETE"
       head :method_not_allowed
     end
 
-    # Handles POST requests containing client JSON-RPC messages according to 2025-03-26 spec.
+    # Handles POST requests containing one client JSON-RPC message.
     # <rails-lens:routes:begin>
     # ROUTE: /, name: mcp_post, via: POST
     # <rails-lens:routes:end>
@@ -51,54 +64,60 @@ module ActionMCP
         return render_not_acceptable(post_accept_headers_error_message, id)
       end
 
-      # Reject JSON-RPC batch requests as per MCP 2025-06-18 spec
-      return render_bad_request("JSON-RPC batch requests are not supported", nil) if jsonrpc_params_batch?
-
-      is_initialize_request = check_if_initialize_request(jsonrpc_params)
-      session_initially_missing = extract_session_id.nil?
-      session = mcp_session
-
-      # Validate MCP-Protocol-Version header for non-initialize requests
-      return unless validate_protocol_version_header
-
-      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)
-        elsif session.nil? || session.new_record?
-          id = jsonrpc_params.respond_to?(:id) ? jsonrpc_params.id : nil
-          return render_not_found("Session not found.", id)
-        elsif session.status == "closed"
-          id = jsonrpc_params.respond_to?(:id) ? jsonrpc_params.id : nil
-          return render_not_found("Session has been terminated.", id)
+      payload = jsonrpc_params
+      is_initialize_request = initialize_request?(payload)
+      session_id = extract_session_id
+
+      return unless authenticate_gateway!
+
+      if (validation_error = ProtocolValidator.client_message_validation_error(payload))
+        if payload.is_a?(JSON_RPC::Notification)
+          return render_notification_error(validation_error)
         end
-      end
 
-      if session.nil?
-        id = jsonrpc_params.respond_to?(:id) ? jsonrpc_params.id : nil
-        return render_not_found("Session not found.", id)
+        return render_jsonrpc_error(validation_error.code, validation_error.message, request_id(payload))
       end
 
-      if session.new_record?
-        session.save!
-        response.headers[MCP_SESSION_ID_HEADER] = session.id
-      end
+      session = if is_initialize_request
+                  if session_id
+                    existing_session = load_session(session_id)
+                    return render_not_found("Session not found.", request_id(payload)) unless existing_session
+                    if existing_session.status == "closed"
+                      return render_not_found("Session has been terminated.", request_id(payload))
+                    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}
+                    return render_bad_request("Initialize requests must not include an Mcp-Session-Id header.", request_id(payload))
+                  end
+
+                  create_session
       else
-        authenticate_gateway!
-        return if performed?
+                  return render_bad_request("Mcp-Session-Id header is required for this request.", request_id(payload)) unless session_id
+
+                  existing_session = load_session(session_id)
+                  return render_not_found("Session not found.", request_id(payload)) unless existing_session
+                  if existing_session.status == "closed"
+                    return render_not_found("Session has been terminated.", request_id(payload))
+                  end
+
+                  existing_session
       end
 
+      @mcp_session = session
+      unless configure_gateway_session!(session)
+        Server.session_store.delete_session(session.id) if is_initialize_request
+        return
+      end
+      return unless is_initialize_request || validate_protocol_version_header(session)
+      return unless lifecycle_allows?(payload, session, is_initialize_request)
+
       # 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)
 
       result = json_rpc_handler.call(jsonrpc_params)
-      process_handler_results(result, session, session_initially_missing, is_initialize_request)
+      process_handler_results(result, session, is_initialize_request)
     rescue StandardError => e
+      Server.session_store.delete_session(session.id) if is_initialize_request && session
       Rails.error.report(e, handled: true, severity: :error)
       id = begin
         jsonrpc_params.respond_to?(:id) ? jsonrpc_params.id : nil
@@ -108,24 +127,26 @@ module ActionMCP
       render_internal_server_error("An unexpected error occurred.", id) unless performed?
     end
 
-    # Handles DELETE requests for session termination (2025-03-26 spec).
+    # Handles DELETE requests for session termination.
     # <rails-lens:routes:begin>
     # ROUTE: /, name: mcp_delete, via: DELETE
     # <rails-lens:routes:end>
     def destroy
+      return unless authenticate_gateway!
+
       session_id_from_header = extract_session_id
       return render_bad_request("Mcp-Session-Id header is required for DELETE requests.") unless session_id_from_header
 
-      session = Server.session_store.load_session(session_id_from_header)
+      session = load_session(session_id_from_header)
       if session.nil?
         return render_not_found("Session not found.")
       elsif session.status == "closed"
-        return head :no_content
+        return render_not_found("Session has been terminated.")
       end
 
-      # Authenticate the request via gateway
-      authenticate_gateway!
-      return if performed?
+      @mcp_session = session
+      return unless configure_gateway_session!(session)
+      return unless validate_protocol_version_header(session)
 
       begin
         session.close!
@@ -139,23 +160,12 @@ module ActionMCP
 
     private
 
-    # Validates the MCP-Protocol-Version header for non-initialization requests
+    # Validates the MCP-Protocol-Version header for requests after initialization.
     # Returns true if valid, renders error and returns false if invalid
-    def validate_protocol_version_header
-      # Skip validation for initialization-related requests
-      return true if initialization_related_request?(jsonrpc_params)
-
-      # Check for both case variations of the header (spec uses MCP-Protocol-Version)
+    def validate_protocol_version_header(session)
       header_version = request.headers["MCP-Protocol-Version"] || request.headers["mcp-protocol-version"]
-      session = mcp_session
-
-      # If header is missing, assume 2025-06-18 for backward compatibility as per spec
-      if header_version.nil?
-        ActionMCP.logger.debug "MCP-Protocol-Version header missing, assuming 2025-06-18 for backward compatibility"
-        return true
-      end
+      return true if header_version.nil? && session.protocol_version == ActionMCP::LATEST_VERSION
 
-      # Handle array values (take the last one as per TypeScript SDK)
       header_version = header_version.last if header_version.is_a?(Array)
 
       # Check if the header version is supported
@@ -166,30 +176,27 @@ module ActionMCP
         return false
       end
 
-      # If we have an initialized session, check if the header matches the negotiated version
-      if session&.initialized?
-        negotiated_version = session.protocol_version
-        if header_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
+      negotiated_version = session.protocol_version
+      if header_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
 
       true
     end
 
-    # Finds an existing session based on header or param, or initializes a new one.
-    # 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
+    def load_session(session_id)
+      return unless session_id
 
-      if session_id
-        session_store.load_session(session_id)
-      else
-        session_store.create_session(nil, protocol_version: ActionMCP::DEFAULT_PROTOCOL_VERSION)
-      end
+      ActionMCP::Server.session_store.load_session(session_id)
+    end
+
+    def create_session
+      ActionMCP::Server.session_store.create_session(
+        nil,
+        protocol_version: ActionMCP::DEFAULT_PROTOCOL_VERSION
+      )
     end
 
     # @return [String, nil] The extracted session ID or nil if not found.
@@ -199,30 +206,50 @@ module ActionMCP
 
     # Checks if the Accept headers for POST are valid.
     def post_accept_headers_valid?
-      request.accepts.any? { |type| type.to_s == "application/json" }
+      accepted_media_types = Rack::Utils.q_values(request.get_header("HTTP_ACCEPT")).filter_map do |media_range, quality|
+        Rack::MediaType.type(media_range)&.downcase if quality.positive?
+      end
+
+      POST_ACCEPT_MEDIA_TYPES.all? { |media_type| accepted_media_types.include?(media_type) }
     end
 
     # Returns the appropriate error message for POST Accept header validation.
     def post_accept_headers_error_message
-      "Client must accept 'application/json'"
+      "Not Acceptable: Client must accept both application/json and text/event-stream"
     end
 
-    # Checks if the parsed body represents an 'initialize' request.
-    def check_if_initialize_request(payload)
-      return false unless payload.is_a?(JSON_RPC::Request) && !jsonrpc_params_batch?
+    def initialize_request?(payload)
+      payload.is_a?(JSON_RPC::Request) && payload.method == JsonRpcHandlerBase::Methods::INITIALIZE
+    end
 
-      payload.method == "initialize"
+    def initialized_notification?(payload)
+      payload.is_a?(JSON_RPC::Notification) &&
+        payload.method == JsonRpcHandlerBase::Methods::NOTIFICATIONS_INITIALIZED
     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?
+    def ping_request?(payload)
+      payload.is_a?(JSON_RPC::Request) && payload.method == JsonRpcHandlerBase::Methods::PING
+    end
+
+    def lifecycle_allows?(payload, session, initialize_request)
+      return true if initialize_request
+
+      if initialized_notification?(payload)
+        return true if session.status == "initializing" && !session.initialized?
 
-      %w[initialize notifications/initialized].include?(payload.method)
+        render_bad_request("Session is not awaiting an initialized notification.", request_id(payload))
+        return false
+      end
+
+      return true if session.initialized?
+      return true if session.status == "initializing" && ping_request?(payload)
+
+      render_bad_request("Session initialization is incomplete.", request_id(payload))
+      false
     end
 
     # Processes the results from the JsonRpcHandler.
-    def process_handler_results(result, session, session_initially_missing, is_initialize_request)
+    def process_handler_results(result, session, is_initialize_request)
       # Handle empty result (notifications)
       return head :accepted if result.nil?
 
@@ -235,7 +262,10 @@ module ActionMCP
                   result
       end
 
-      add_session_header = is_initialize_request && session_initially_missing && session.persisted?
+      successful_initialize = is_initialize_request && result.is_a?(JSON_RPC::Response) && result.error.nil?
+      Server.session_store.delete_session(session.id) if is_initialize_request && !successful_initialize
+
+      add_session_header = successful_initialize && session.persisted?
       render_json_response(payload, session, add_session_header)
     end
 
@@ -258,7 +288,7 @@ module ActionMCP
     # Renders a 400 Bad Request response with a JSON-RPC-like error structure.
     def render_bad_request(message = "Bad Request", id = nil)
       id ||= extract_jsonrpc_id_from_request
-      render json: { jsonrpc: "2.0", id: id, error: { code: -32_600, message: message } }
+      render json: { jsonrpc: "2.0", id: id, error: { code: -32_600, message: message } }, status: :bad_request
     end
 
     # Renders a 400 Bad Request response for protocol version errors as per MCP spec
@@ -270,30 +300,40 @@ module ActionMCP
     # 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
-      render json: { jsonrpc: "2.0", id: id, error: { code: -32_001, message: message } }
+      render json: { jsonrpc: "2.0", id: id, error: { code: -32_001, message: message } }, status: :not_found
     end
 
     # Renders a 405 Method Not Allowed response.
     def render_method_not_allowed(message = "Method Not Allowed", id = nil)
       id ||= extract_jsonrpc_id_from_request
-      render json: { jsonrpc: "2.0", id: id, error: { code: -32_601, message: message } }
+      render json: { jsonrpc: "2.0", id: id, error: { code: -32_601, message: message } }, status: :method_not_allowed
     end
 
     # Renders a 406 Not Acceptable response.
     def render_not_acceptable(message = "Not Acceptable", id = nil)
       id ||= extract_jsonrpc_id_from_request
-      render json: { jsonrpc: "2.0", id: id, error: { code: -32_002, message: message } }
+      render json: { jsonrpc: "2.0", id: id, error: { code: -32_000, message: message } }, status: :not_acceptable
     end
 
     # Renders a 501 Not Implemented response.
     def render_not_implemented(message = "Not Implemented", id = nil)
       id ||= extract_jsonrpc_id_from_request
-      render json: { jsonrpc: "2.0", id: id, error: { code: -32_003, message: message } }
+      render json: { jsonrpc: "2.0", id: id, error: { code: -32_003, message: message } }, status: :not_implemented
     end
 
     # Renders a 500 Internal Server Error response.
     def render_internal_server_error(message = "Internal Server Error", id = nil)
-      render json: { jsonrpc: "2.0", id: id, error: { code: -32_000, message: message } }
+      render json: { jsonrpc: "2.0", id: id, error: { code: -32_603, message: message } }, status: :internal_server_error
+    end
+
+    def render_jsonrpc_error(symbol, message, id = nil)
+      error = JSON_RPC::JsonRpcError.new(symbol, message: message)
+      render json: JSON_RPC::Response.new(id: id, error: error), status: :ok
+    end
+
+    def render_notification_error(validation_error)
+      error = JSON_RPC::JsonRpcError.new(validation_error.code, message: validation_error.message)
+      render json: JSON_RPC::Response.new(id: nil, error: error), status: :bad_request
     end
 
     # Extract JSON-RPC ID from request
@@ -316,34 +356,51 @@ module ActionMCP
       end
     end
 
+    def request_id(payload)
+      payload.respond_to?(:id) ? payload.id : nil
+    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 && initialization_related_request?(jsonrpc_params)
-        return
-      end
-
       gateway_class = ActionMCP.configuration.gateway_class
-      return unless gateway_class # Skip if no gateway configured
+      return true unless gateway_class
 
       begin
-        gateway = gateway_class.new(request)
-        gateway.call
-        gateway.configure_session(mcp_session)
+        @authenticated_gateway = gateway_class.new(request)
+        @authenticated_gateway.call
+        true
       rescue ActionMCP::UnauthorizedError => e
         render_unauthorized(e.message)
+        false
       rescue StandardError => e
         Rails.error.report(e, handled: true, severity: :error)
         render_unauthorized("Authentication system error")
+        false
       end
     end
 
+    def configure_gateway_session!(session)
+      return true unless @authenticated_gateway
+
+      @authenticated_gateway.configure_session(session)
+      true
+    rescue ActionMCP::UnauthorizedError => e
+      render_unauthorized(e.message)
+      false
+    rescue StandardError => e
+      Rails.error.report(e, handled: true, severity: :error)
+      render_unauthorized("Authentication system error")
+      false
+    end
+
     # Renders an unauthorized response
     def render_unauthorized(message = "Unauthorized", id = nil)
       id ||= extract_jsonrpc_id_from_request
 
-      # Return JSON-RPC error with 200 status as per MCP specification
-      render json: { jsonrpc: "2.0", id: id, error: { code: -32_000, message: message } }
+      challenge = "Bearer"
+      challenge += ' error="invalid_token"' if request.headers["Authorization"].present?
+      response.headers["WWW-Authenticate"] = challenge
+      render json: { jsonrpc: "2.0", id: id, error: { code: -32_000, message: message } }, status: :unauthorized
     end
   end
 end

data/app/controllers/action_mcp/mcp_app_renderer.rb

@@ -18,5 +18,6 @@ module ActionMCP
   #
   # Not routed. Not intended to be subclassed or used directly by host apps.
   class MCPAppRenderer < ActionController::Base
+    helper ActionMCP::AppsHelper
   end
 end

data/app/helpers/action_mcp/apps_helper.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ActionMCP
+  # View helpers for MCP Apps UI templates rendered via `render_ui`.
+  module AppsHelper
+    # Inlines the vendored @modelcontextprotocol/ext-apps browser bundle and a
+    # small bootstrap into a single <script type="module"> element.
+    #
+    # UI view HTML is delivered to hosts as resource text (not over HTTP), so
+    # the bridge must ship inline — external scripts would require CSP-declared
+    # origins and a reachable asset host.
+    #
+    # The bootstrap exposes `globalThis.ActionMCP`:
+    #   App           - the raw ext-apps App class
+    #   bridgeVersion - vendored package version
+    #   connect(opts) - registers opts.handlers on a new App instance BEFORE
+    #                   calling connect(), per the ext-apps handshake contract,
+    #                   then resolves with the connected app.
+    #
+    # Views run their own module script after this tag; module scripts execute
+    # in document order, so `ActionMCP` is always defined by then.
+    #
+    # @example In a view
+    #   <%= mcp_app_bridge_tag %>
+    #   <script type="module">
+    #     const app = await ActionMCP.connect({
+    #       handlers: { ontoolresult: (result) => { ... } }
+    #     });
+    #   </script>
+    def mcp_app_bridge_tag(app_name: "action-mcp-view", app_version: "1.0.0")
+      default_app_info = { name: app_name, version: app_version }.to_json
+      bootstrap = <<~JS
+        globalThis.ActionMCP = Object.freeze({
+          App,
+          bridgeVersion: #{Apps::BRIDGE_VERSION.to_json},
+          async connect({ appInfo, capabilities, handlers } = {}) {
+            const app = new App(appInfo ?? #{default_app_info}, capabilities ?? {});
+            if (handlers) Object.assign(app, handlers);
+            await app.connect();
+            return app;
+          }
+        });
+      JS
+
+      content_tag(:script, "#{Apps.bridge_source}\n#{bootstrap}".html_safe, type: "module")
+    end
+  end
+end