@callback call(GenMCP.MCP.CallToolRequest.t(), GenMCP.Mux.Channel.t(), arg()) ::
  call_result()

Executes the tool call and returns a result, error, or async continuation.

Receives validated request parameters if validate_request/2 is defined. When using use GenMCP.Suite.Tool, JSON schema validation is automatically implemented, ensuring req.params.arguments conforms to the schema.

Result payload

Synchronous results are returned as {:result, %MCP.CallToolResult{}, channel}. The second element must be a %MCP.CallToolResult{}, typically built with GenMCP.MCP.call_tool_result/1.

Async calls

When returning {:async, {tag, ref}, channel}, the continue/3 callback will be invoked with {tag, {:ok, value}} if the server process receives a {ref, value} message with the same ref.

This works automatically with tasks. It is possible to directly return the task struct as in {:async, {tag, task}, channel}.

Note that Task.async/1 may crash the server process, you may want to use Task.Supervisor.async_nolink/2 in which case a :DOWN message from the task will be delivered as with the same tag as {tag, {:error, reason}}.

This should also work with manually monitored processes, given the monitored process obtains the ref to send the {ref, result} value back to the calling process.

Channel and Assigns

The channel provides access to assigns copied from the Plug.Conn struct (from the HTTP request that delivered the tool call request) and can be modified via GenMCP.Mux.Channel.assign/3 to keep state before entering the continue/3 callback.

Assigning modifies the channel, so the last updated channel must always be returned from your callback.

Examples

Synchronous execution:

def call(req, channel, _arg) do
  %{"query" => query} = req.params.arguments
  entity = perform_search(query)

  # With structured output (entity is a map), mind the list wrapper
  {:result, MCP.call_tool_result([entity]), channel}

  # Without structured output
  {:result, MCP.call_tool_result(text: Jason.encode!(entity)), channel}
end

Asynchronous with Task:

def call(req, channel, _arg) do
  task = Task.async(fn -> expensive_operation(req) end)
  {:async, {:search_task, task}, channel}
end

Error handling:

def call(_req, channel, _arg) do
  {:error, "Resource not available", channel}
end

@callback continue(
  {tag(), {:ok, term()} | {:error, term()}},
  GenMCP.Mux.Channel.t(),
  arg()
) ::
  call_result()

Continues processing after async work completes.

Invoked when call/3 returns {:async, {tag, ref_or_task}, channel} and the task finishes.

The first tuple element contains the tag and the wrapped task result (either {:ok, result} for success or {:error, reason} for failures with non-linked tasks). Returns same result types as call/3. Can chain another async operation by returning {:async, {new_tag, new_ref}, channel}.

The tag is generally an atom to be matched on if you implement multiple conitinuation callbacks but it can be any term.

Examples

Basic continuation:

def continue({:search_task, {:ok, results}}, channel, _arg) do
  {:result, MCP.call_tool_result(text: Jason.encode!(results)), channel}
end

Error handling:

def continue({:search_task, {:error, reason}}, channel, _arg) do
  {:error, "Search failed: #{reason}", channel}
end

Chaining async operations:

def continue({:step1, {:ok, intermediate}}, channel, _arg) do
  task = Task.async(fn -> step2(intermediate) end)
  {:async, {:step2, task}, channel}
end

@callback info(:name, arg()) :: String.t()

@callback info(:description, arg()) :: nil | String.t()

@callback info(:title, arg()) :: nil | String.t()

@callback info(:annotations, arg()) :: nil | tool_annotations()

@callback info(:_meta, arg()) :: nil | map()

Returns tool metadata for the specified key.

Invoked by describe/1 to gather tool metadata.

With use GenMCP.Suite.Tool with metadata options, this callback is auto-generated.

Examples

def info(:name, _arg), do: "search_files"
def info(:description, _arg), do: "Searches for files matching a pattern"
def info(:_meta, _arg), do: %{"ui/resourceUri" => "ui://pages/some-page"}
def info(:annotations, _arg), do: %{readOnlyHint: true}
def info(_, _), do: nil

@callback input_schema(arg()) :: schema()

Returns the JSON schema defining accepted tool arguments.

Sent to clients in tools/list responses to describe expected parameters.

Auto-generated with use GenMCP.Suite.Tool with an :input_schema option.

Examples

def input_schema(_arg) do
  %{
    type: :object,
    properties: %{
      query: %{type: :string},
      limit: %{type: :integer, default: 10}
    },
    required: [:query]
  }
end

@callback output_schema(arg()) :: nil | schema()

Returns the JSON schema defining tool result structure, or nil if unspecified.

Defines the structured outputs returned by the tool if any. Entirely optional and not enforced at runtime.

Auto-generated with use GenMCP.Suite.Tool with an :output_schema option.

Examples

def output_schema(_arg) do
  %{
    type: :object,
    properties: %{
      files: %{type: :array, items: %{type: :string}}
    }
  }
end

@callback validate_request(GenMCP.MCP.CallToolRequest.t(), arg()) ::
  {:ok, GenMCP.MCP.CallToolRequest.t()} | {:error, String.t()}

Validates and optionally transforms the incoming call request.

Invoked before call/3.

Auto-generated with JSON schema validation when using use GenMCP.Suite.Tool with an :input_schema option.

Examples

def validate_request(req, _arg) do
  case req.params.arguments do
    %{"limit" => n} when n > 0 and n <= 100 -> {:ok, req}
    _ -> {:error, "limit must be between 1 and 100"}
  end
end