CallTool is the bridge between your UI and your server logic. When a user clicks a button or submits a form, CallTool invokes a server tool with the arguments you specify — the same tools you define with @mcp.tool().
The renderer proxies the call through the Prefab SDK, so the tool executes server-side with full access to your backend.
Passing Arguments
Use.rx or Rx("key") to pass client state to the tool. Form controls with a name automatically sync to state — Input(name="city") updates city on every keystroke, no SetState needed.
Type a city name, click the button, and the current input value flows into the location argument.
Combined with Client Actions
Pass a list to execute multiple actions from a single interaction. A common pattern: update UI state before making the server call, so the user sees immediate feedback.Combined Actions
SetState executes first (instant), then CallTool fires the server request.
Handling Results
The tool’s return value is available as$result (Python: RESULT) inside on_success callbacks. Use SetState to write it into client-side state:
Writing results to state
$result is the success counterpart of $error: one is available in on_success, the other in on_error. You can combine them with any action — ShowToast, AppendState, or chain multiple actions in a list:
Callbacks with result
Callable References (FastMCP)
When using Prefab with FastMCP, you can pass a function reference instead of a tool name string. The framework resolves it to the correct tool name at serialization time, including any namespace prefixes or global keys:unwrapResult.
String names are also resolved when a resolver is active. CallTool("save_contact") will pass the string "save_contact" through the resolver, which can map it to a global key like "save_contact-a1b2c3d4". This means you can use string names in a FastMCPApp context and still get correct name resolution — useful when you don’t have a direct reference to the tool function (e.g., tools defined in mounted sub-apps).
Automatic Result Unwrapping
MCP requiresstructuredContent to be a JSON object, so FastMCP wraps non-object tool returns (lists, strings, numbers) in a {"result": X} envelope. Without correction, $result in your on_success callback would contain this envelope instead of the actual data.
When you use a callable reference, the resolver detects this wrapping and sets unwrapResult: true on the serialized action. The renderer sees the flag and automatically extracts the inner value, so $result contains exactly what your tool returned.
String names go through the same resolver, so they also benefit from unwrapResult when the resolver can identify the tool. However, if the resolver doesn’t recognize a string name (e.g., a dynamically constructed name), it may not be able to determine whether unwrapping is needed.
API Reference
CallTool Parameters
str | Callable
required
Name of the server tool to call, or a callable reference to the tool function. Can be passed as a positional argument.
dict[str, Any]
default:"{}"
Arguments to pass to the tool. Values support
{{ key }} interpolation to reference client-side state at call time.Action | list[Action] | None
default:"None"
Action(s) to run when the tool call succeeds. The returned value is available as
$result.Action | list[Action] | None
default:"None"
Action(s) to run when the tool call fails. The error message is available as
$error.Protocol Reference
CallTool