fix: align tasks/* with MCP 2025-11-25 spec (#219)

Author: seuros

README.md

@@ -315,7 +315,7 @@ class BatchIndexTool < ApplicationMCPTool
 end
 ```
 
-Call it as a task from a client by adding `_meta.task` (creates a Task record and runs the tool via `ToolExecutionJob`):
+Call it as a task from a client by adding top-level `task` params (creates a Task record and runs the tool via `ToolExecutionJob`):
 
 ```json
 {
@@ -325,12 +325,27 @@ Call it as a task from a client by adding `_meta.task` (creates a Task record an
   "params": {
     "name": "batch_index",
     "arguments": { "items": ["a", "b", "c"] },
-    "_meta": { "task": { "ttl": 120000, "pollInterval": 2000 } }
+    "task": { "ttl": 120000 }
   }
 }
 ```
 
-Poll task status with `tasks/get` or fetch the result when finished with `tasks/result`. 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.
+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:
+
+```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
 

app/jobs/action_mcp/tool_execution_job.rb

@@ -53,6 +53,7 @@ def validate_session(task)
       session = task.session
       unless session
         task.update(status_message: "Session not found")
+        task.result_payload = { code: -32_603, message: "Session not found" }
         task.mark_failed!
         return nil
       end
@@ -64,6 +65,10 @@ def prepare_tool(session, tool_name, arguments, task)
       tool_class = session.registered_tools.find { |t| t.tool_name == tool_name }
       unless tool_class
         @task.update(status_message: "Tool '#{tool_name}' not found")
+        @task.result_payload = {
+          code: -32_601,
+          message: "Tool '#{tool_name}' not found"
+        }
         @task.mark_failed!
         return nil
       end
@@ -101,12 +106,13 @@ def execute_with_reloader(tool, session)
     def update_task_result(task, result)
       return if task.terminal? # Guard against double-complete
 
-      if result.is_error
-        task.result_payload = result.to_h
+      payload = result.to_h
+      if result.is_error || payload[:isError] || payload["isError"]
+        task.result_payload = payload
         task.status_message = result.respond_to?(:error_message) ? result.error_message : "Tool returned error"
         task.mark_failed!
       else
-        task.result_payload = result.to_h
+        task.result_payload = payload
         task.record_step!(:completed)
         task.complete!
       end
@@ -123,6 +129,10 @@ def self.handle_job_discard(job, error)
 
       task.update(
         status_message: "Job failed: #{error.message}",
+        result_payload: {
+          code: -32_603,
+          message: "Job failed: #{error.message}"
+        },
         continuation_state: {
           step: :failed,
           error: { class: error.class.name, message: error.message },

app/models/action_mcp/session.rb

@@ -114,7 +114,7 @@ def server_capabilities_payload
       payload = {
         protocolVersion: protocol_version || ActionMCP::DEFAULT_PROTOCOL_VERSION,
         serverInfo: server_info,
-        capabilities: server_capabilities
+        capabilities: capabilities_for_protocol(server_capabilities)
       }
       # Add instructions at top level if configured
       instructions = ActionMCP.configuration.instructions
@@ -130,6 +130,23 @@ def server_capabilities=(value)
       super(parsed_json_attribute(value))
     end
 
+    def capabilities_for_protocol(capabilities)
+      parsed = parsed_json_attribute(capabilities)
+      filtered =
+        if parsed.respond_to?(:deep_dup)
+          parsed.deep_dup
+        elsif parsed
+          parsed.dup
+        else
+          {}
+        end
+      return filtered if protocol_version == "2025-11-25"
+
+      filtered.delete("tasks")
+      filtered.delete(:tasks)
+      filtered
+    end
+
     def initialize!
       # update the session initialized to true
       return false if initialized?

app/models/action_mcp/session/task.rb

@@ -52,6 +52,8 @@ class Session
     #   input_required -> completed | failed | cancelled
     #
     class Task < ApplicationRecord
+      RELATED_TASK_META_KEY = "io.modelcontextprotocol/related-task"
+
       self.table_name = "action_mcp_session_tasks"
 
       attribute :id, :string, default: -> { SecureRandom.uuid_v7 }
@@ -139,6 +141,10 @@ def terminal?
         status.in?(%w[completed failed cancelled])
       end
 
+      def result_ready?
+        terminal? || input_required?
+      end
+
       # Check if task is in a non-terminal state
       def non_terminal?
         !terminal?
@@ -148,32 +154,73 @@ def non_terminal?
       # @return [Hash] Task data for JSON-RPC responses
       def to_task_data
         data = {
-          id: id,
+          taskId: id,
           status: status,
-          lastUpdatedAt: last_updated_at.iso8601(3)
+          createdAt: created_at.iso8601(3),
+          lastUpdatedAt: last_updated_at.iso8601(3),
+          ttl: ttl
         }
         data[:statusMessage] = status_message if status_message.present?
-
-        # Add progress if available (ActiveJob::Continuable support)
-        if progress_percent.present? || progress_message.present?
-          data[:progress] = {}.tap do |progress|
-            progress[:percent] = progress_percent if progress_percent.present?
-            progress[:message] = progress_message if progress_message.present?
-          end
-        end
+        data[:pollInterval] = poll_interval if poll_interval.present?
 
         data
       end
 
-      # Convert to full task result format
-      # @return [Hash] Complete task with result for tasks/result response
-      def to_task_result
+      def to_create_task_result
         {
           task: to_task_data,
-          result: result_payload
+          _meta: related_task_meta
         }
       end
 
+      # Convert to the original request's result payload for tasks/result.
+      # The result carries related-task metadata because its structure does not
+      # otherwise include the task identifier.
+      # @return [Hash] Result payload for tasks/result response
+      def to_task_result
+        payload = result_payload.is_a?(Hash) ? result_payload.deep_dup : {}
+        meta = payload.delete("_meta") || payload.delete(:_meta) || {}
+        meta = meta.to_h if meta.respond_to?(:to_h)
+        meta = {} unless meta.is_a?(Hash)
+
+        payload[:_meta] = meta.deep_merge(related_task_meta)
+        payload
+      end
+
+      def to_task_error
+        return unless result_payload.is_a?(Hash)
+
+        code = result_payload["code"] || result_payload[:code]
+        message = result_payload["message"] || result_payload[:message]
+        return unless code && message
+        return if result_payload.key?("content") || result_payload.key?(:content)
+        return if result_payload.key?("isError") || result_payload.key?(:isError)
+
+        error = { code: code, message: message }
+        data = result_payload["data"] || result_payload[:data]
+        error[:data] = data unless data.nil?
+        error
+      end
+
+      def related_task_meta
+        {
+          RELATED_TASK_META_KEY => {
+            "taskId" => id
+          }
+        }
+      end
+
+      def request_meta_with_related_task(meta = nil)
+        existing_meta =
+          if meta.respond_to?(:to_h)
+            meta.to_h.deep_dup
+          else
+            {}
+          end
+
+        existing_meta.deep_merge(related_task_meta)
+      end
+
       # Broadcast status change notification to the session
       # @param transition [StateMachines::Transition] The state transition that occurred
       def broadcast_status_change(transition = nil)

lib/action_mcp/configuration.rb

@@ -45,6 +45,9 @@ class Configuration
                   :tasks_enabled,
                   :tasks_list_enabled,
                   :tasks_cancel_enabled,
+                  :tasks_result_strategy,
+                  :tasks_result_timeout,
+                  :tasks_result_poll_interval,
                   # --- Schema Validation Options ---
                   :validate_structured_content,
                   # --- Allowed identity keys for gateway ---
@@ -72,6 +75,9 @@ def initialize
       @tasks_enabled = false
       @tasks_list_enabled = true
       @tasks_cancel_enabled = true
+      @tasks_result_strategy = :blocking_http
+      @tasks_result_timeout = 30.seconds
+      @tasks_result_poll_interval = 0.25
 
       # Pagination - nil means off. Set a number to enable with that page size.
       # Most MCP clients (including Claude Code) don't follow nextCursor yet.
@@ -152,6 +158,23 @@ def pagination_page_size=(value)
       end
     end
 
+    def tasks_result_strategy=(value)
+      strategy = value.to_sym
+      unless %i[blocking_http polling_only].include?(strategy)
+        raise ArgumentError, "tasks_result_strategy must be :blocking_http or :polling_only, got: #{value.inspect}"
+      end
+
+      @tasks_result_strategy = strategy
+    end
+
+    def tasks_result_timeout=(value)
+      @tasks_result_timeout = normalize_positive_duration(value, "tasks_result_timeout")
+    end
+
+    def tasks_result_poll_interval=(value)
+      @tasks_result_poll_interval = normalize_positive_duration(value, "tasks_result_poll_interval")
+    end
+
     def gateway_class
       # Resolve gateway class lazily to account for Zeitwerk autoloading
       # This allows ApplicationGateway to be loaded from app/mcp even if the
@@ -408,6 +431,12 @@ def extract_top_level_settings(app_config)
         self.pagination_page_size = config["pagination_page_size"]
       end
 
+      self.tasks_result_strategy = config["tasks_result_strategy"] if config.key?("tasks_result_strategy")
+      self.tasks_result_timeout = config["tasks_result_timeout"] if config.key?("tasks_result_timeout")
+      if config.key?("tasks_result_poll_interval")
+        self.tasks_result_poll_interval = config["tasks_result_poll_interval"]
+      end
+
       # Extract allowed origins for DNS rebinding protection
       if config["allowed_origins"]
         @allowed_origins = Array(config["allowed_origins"])
@@ -434,6 +463,13 @@ def parse_instructions(instructions)
       Array(instructions).map(&:to_s)
     end
 
+    def normalize_positive_duration(value, setting_name)
+      duration = value.respond_to?(:to_f) ? value.to_f : value.to_s.to_f
+      raise ArgumentError, "#{setting_name} must be positive, got: #{value.inspect}" unless duration.positive?
+
+      duration
+    end
+
     def ensure_mcp_components_loaded
       # Only load if we haven't loaded yet - but in development, always reload
       return if @mcp_components_loaded && !Rails.env.development?

lib/action_mcp/json_rpc_handler_base.rb

@@ -40,7 +40,6 @@ module Methods
       TASKS_RESULT = "tasks/result"
       TASKS_LIST = "tasks/list"
       TASKS_CANCEL = "tasks/cancel"
-      TASKS_RESUME = "tasks/resume"
 
       # Task notifications
       NOTIFICATIONS_TASKS_STATUS = "notifications/tasks/status"

lib/action_mcp/server/base_session.rb

@@ -118,7 +118,7 @@ def server_capabilities_payload
         payload = {
           protocolVersion: ActionMCP::LATEST_VERSION,
           serverInfo: server_info,
-          capabilities: server_capabilities
+          capabilities: capabilities_for_protocol(server_capabilities)
         }
         # Add instructions at top level if configured
         instructions = ActionMCP.configuration.instructions
@@ -280,6 +280,22 @@ def revoke_consent(key)
 
       private
 
+      def capabilities_for_protocol(capabilities)
+        filtered =
+          if capabilities.respond_to?(:deep_dup)
+            capabilities.deep_dup
+          elsif capabilities
+            capabilities.dup
+          else
+            {}
+          end
+        return filtered if protocol_version == "2025-11-25"
+
+        filtered.delete("tasks")
+        filtered.delete(:tasks)
+        filtered
+      end
+
       def normalize_name(class_or_name, type)
         case class_or_name
         when String

lib/action_mcp/server/handlers/task_handler.rb

@@ -12,6 +12,11 @@ def process_tasks(rpc_method, id, params)
           params ||= {}
 
           with_error_handling(id) do
+            unless transport.session.protocol_version == "2025-11-25"
+              raise JSON_RPC::JsonRpcError.new(:method_not_found,
+                                               message: "Tasks are only available in MCP 2025-11-25")
+            end
+
             handler = task_method_handlers[rpc_method]
             if handler
               send(handler, id, params)
@@ -29,8 +34,7 @@ def task_method_handlers
             JsonRpcHandlerBase::Methods::TASKS_GET => :handle_tasks_get,
             JsonRpcHandlerBase::Methods::TASKS_RESULT => :handle_tasks_result,
             JsonRpcHandlerBase::Methods::TASKS_LIST => :handle_tasks_list,
-            JsonRpcHandlerBase::Methods::TASKS_CANCEL => :handle_tasks_cancel,
-            JsonRpcHandlerBase::Methods::TASKS_RESUME => :handle_tasks_resume
+            JsonRpcHandlerBase::Methods::TASKS_CANCEL => :handle_tasks_cancel
           }
         end
 
@@ -63,15 +67,6 @@ def handle_tasks_cancel(id, params)
           transport.send_tasks_cancel(id, task_id)
         end
 
-        def handle_tasks_resume(id, params)
-          task_id = validate_required_param(params, "taskId", "Task ID is required")
-          input = params["input"]
-          task = find_task_or_error(id, task_id)
-          return unless task
-
-          transport.send_tasks_resume(id, task_id, input)
-        end
-
         def find_task_or_error(id, task_id)
           task = transport.session.tasks.find_by(id: task_id)
           unless task

lib/action_mcp/server/handlers/tool_handler.rb

@@ -37,7 +37,8 @@ def handle_tools_call(id, params)
           name = validate_required_param(params, "name", "Tool name is required")
           arguments = extract_arguments(params)
           _meta = params["_meta"] || params[:_meta] || {}
-          transport.send_tools_call(id, name, arguments, _meta)
+          task_params = params.key?("task") ? params["task"] : params[:task]
+          transport.send_tools_call(id, name, arguments, _meta, task_params)
         end
 
         def extract_arguments(params)