Skip to main content

ToolHandler

fastmcp_server

Trait ToolHandler 

Source 
pub trait ToolHandler: Send + Sync {
    // Required methods
    fn definition(&self) -> Tool;
    fn call(
        &self,
        ctx: &McpContext,
        arguments: Value,
    ) -> McpResult<Vec<Content>>;

    // Provided methods
    fn icon(&self) -> Option<&Icon> { ... }
    fn version(&self) -> Option<&str> { ... }
    fn tags(&self) -> &[String] { ... }
    fn annotations(&self) -> Option<&ToolAnnotations> { ... }
    fn output_schema(&self) -> Option<Value> { ... }
    fn timeout(&self) -> Option<Duration> { ... }
    fn call_async<'a>(
        &'a self,
        ctx: &'a McpContext,
        arguments: Value,
    ) -> BoxFuture<'a, McpOutcome<Vec<Content>>> { ... }
}
Expand description

Handler for a tool.

This trait is typically implemented via the #[tool] macro.

§Sync vs Async

By default, implement call() for synchronous execution. For async tools, override call_async() instead. The router always calls call_async(), which defaults to running call() in an async block.

§Return Type

Async handlers return McpOutcome<Vec<Content>>, a 4-valued type supporting:

  • Ok(content) - Successful result
  • Err(McpError) - Recoverable error
  • Cancelled - Request was cancelled
  • Panicked - Unrecoverable failure

Required Methods§

Source

fn definition(&self) -> Tool

Returns the tool definition.

Source

fn call(&self, ctx: &McpContext, arguments: Value) -> McpResult<Vec<Content>>

Calls the tool synchronously with the given arguments.

This is the default implementation point. Override this for simple synchronous tools. Returns McpResult which is converted to McpOutcome by the async wrapper.

Provided Methods§

Source

fn icon(&self) -> Option<&Icon>

Returns the tool’s icon, if any.

Default implementation returns None. Override to provide an icon. Note: Icons can also be set directly in definition().

Source

fn version(&self) -> Option<&str>

Returns the tool’s version, if any.

Default implementation returns None. Override to provide a version. Note: Version can also be set directly in definition().

Source

fn tags(&self) -> &[String]

Returns the tool’s tags for filtering and organization.

Default implementation returns an empty slice. Override to provide tags. Note: Tags can also be set directly in definition().

Source

fn annotations(&self) -> Option<&ToolAnnotations>

Returns the tool’s annotations providing behavioral hints.

Default implementation returns None. Override to provide annotations like destructive, idempotent, read_only, or open_world_hint. Note: Annotations can also be set directly in definition().

Source

fn output_schema(&self) -> Option<Value>

Returns the tool’s output schema (JSON Schema).

Default implementation returns None. Override to provide a schema that describes the structure of the tool’s output. Note: Output schema can also be set directly in definition().

Source

fn timeout(&self) -> Option<Duration>

Returns the tool’s custom timeout duration.

Default implementation returns None, meaning the server’s default timeout applies. Override to specify a per-handler timeout.

When set, creates a child budget with the specified timeout that overrides the server’s default timeout for this handler.

Source

fn call_async<'a>( &'a self, ctx: &'a McpContext, arguments: Value, ) -> BoxFuture<'a, McpOutcome<Vec<Content>>>

Calls the tool asynchronously with the given arguments.

Override this for tools that need true async execution (e.g., I/O-bound operations, database queries, HTTP requests).

Returns McpOutcome to properly represent all four states: success, error, cancellation, and panic.

The default implementation delegates to the sync call() method and converts the McpResult to McpOutcome.

Implementors§