class RubyLLM::MCP::Task

A tool call that an MCP server runs in the background, as the Tasks extension describes. Declare MCP.extension :tasks, and a server may answer a long call with a task instead of a result.

A chat never waits for a task. It pauses the tool call, and Chat#pending_tasks returns the tasks it waits on. refresh checks on a task once; Chat#complete checks on every one again and resumes the chat once they are done:

task = chat.pending_tasks.first
task.refresh
task.status         # => :working
task.status_message # => "Rendering page 3 of 12"
task.poll_interval  # => 5.0

MCP#call waits for the task of a tool you call directly.

Attributes

id [R]

The task’s id on its server.

tool_call [R]

The ToolCall paused on the task, when it came from a chat.

Public Instance Methods

cancel ()

Source

# File lib/ruby_llm/mcp/task.rb, line 121
def cancel
  connected.cancel_task(id) unless done?
  self
end

Asks the server to cancel the task, and returns self. The server may still finish it, so check with refresh.

cancelled? ()

Source

# File lib/ruby_llm/mcp/task.rb, line 87
def cancelled?
  status == :cancelled
end

Returns true when the task was cancelled before it finished.

completed? ()

Source

# File lib/ruby_llm/mcp/task.rb, line 77
def completed?
  status == :completed
end

Returns true when the task finished with a result.

done? ()

Source

# File lib/ruby_llm/mcp/task.rb, line 72
def done?
  DONE.include?(status)
end

Returns true once the task completed, failed, or was cancelled.

expires_at ()

Source

# File lib/ruby_llm/mcp/task.rb, line 67
def expires_at
  Time.iso8601(data['createdAt']) + (data['ttlMs'] / 1000.0) if data['ttlMs'] && data['createdAt']
end

When the server may forget the task, as a Time, or nil when it keeps the task for good.

failed? ()

Source

# File lib/ruby_llm/mcp/task.rb, line 82
def failed?
  status == :failed
end

Returns true when the task failed with an error.

poll_interval ()

Source

# File lib/ruby_llm/mcp/task.rb, line 61
def poll_interval
  data['pollIntervalMs'] / 1000.0 if data['pollIntervalMs']
end

How many seconds the server asks you to wait before checking on the task again, or nil.

refresh ()

Source

# File lib/ruby_llm/mcp/task.rb, line 102
def refresh
  @data = connected.poll_task(id) unless done?
  self
end

Checks on the task once and returns self, which now tells whether the task is done? and how soon to check again. Does nothing once the task is done?.

result ()

Source

# File lib/ruby_llm/mcp/task.rb, line 93
def result
  raise error if failed? || cancelled?

  Result.new(data['result']) if completed?
end

Returns the MCP::Result once the task completed?, and nil until then. Raises MCP::Error when the task failed or was cancelled.

status ()

Source

# File lib/ruby_llm/mcp/task.rb, line 49
def status
  data['status'].to_sym
end

The task’s state: :working, :input_required, :completed, :failed, or :cancelled.

status_message ()

Source

# File lib/ruby_llm/mcp/task.rb, line 55
def status_message
  data['statusMessage']
end

What the server says about the task’s state, such as how far it got, or nil.

wait (timeout: nil, interval: nil)

Source

# File lib/ruby_llm/mcp/task.rb, line 115
def wait(timeout: nil, interval: nil)
  connected.await_task(self, timeout:, interval:)
end

Checks on the task until it is done?, sleeping poll_interval seconds in between, and returns self. Answers the server’s requests for input with MCP.before_input_request callbacks. timeout defaults to the server’s MCP.timeout, and the task is cancelled when it runs out or the chat is cancelled.

Raises MCP::Error when the task fails or the time runs out, and MCP::InputRequiredError when no callback answers a request.