> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-use.com/llms.txt
> Use this file to discover all available pages before exploring further.
# useCallTool()
> React hook for calling MCP tools from widgets with TanStack Query-like state management API Documentation
View the source code for this module on GitHub: [https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/src/react/useCallTool.ts](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/src/react/useCallTool.ts)
`useCallTool` is a React hook for calling MCP tools from inside a widget. It manages the call with a discriminated union state machine (idle, pending, success, error) similar to TanStack Query, and exposes two ways to invoke the tool: `callTool` (fire-and-forget with optional side effect callbacks) and `callToolAsync` (returns a `Promise`).
Types are inferred automatically from the tool name when running `mcp-use dev`, which generates `ToolRegistry` augmentations in `.mcp-use/tool-registry.d.ts`. For setups without the dev server, use [`generateHelpers()`](#generatehelpers) to bind the hook to an explicit tool map.
`useCallTool` runs only in a browser environment. Calling it outside the browser (for example, during server-side rendering) throws `Error("useCallTool can only be used in browser environment")`.
## useCallTool
Call an MCP tool and track its lifecycle with idle, pending, success, and error states.
```ts theme={null}
import { useCallTool } from "mcp-use/react";
```
Hook for calling MCP tools with TanStack Query-like state management.
The hook is declared with two overloads. The first is type-safe and resolves input and output types from the augmented `ToolRegistry` based on the tool `name`. The second is a fallback that lets you supply explicit generics when a tool is not in the registry. The runtime detects the protocol automatically: in MCP Apps clients it uses JSON-RPC over `postMessage`, and in the ChatGPT Apps SDK it uses `window.openai.callTool()`. Your code is identical in both cases.
When `name` is a key of `ToolRegistry`, input arguments and the response `structuredContent` are fully typed from your server's tool definition. The hook tracks the latest call with an internal counter, so if you fire a new call before a previous one resolves, only the most recent call updates state (responses from stale calls are ignored).
```ts theme={null}
import { useCallTool } from "mcp-use/react";
```
**Type Parameters (overload 1)**
> The tool name. Constrained to the keys of the augmented `ToolRegistry`, which gives autocomplete for available tool names.
**Type Parameters (overload 2)**
> The shape of the tool input arguments. Use `null` when the tool takes no arguments.
> The shape of the tool response.
**Parameters**
> The name of the tool to call. Auto-typed from `ToolRegistry` in the first overload, or a plain `string` in the fallback overload.
**Returns**
> The current call state spread with the `callTool` and `callToolAsync` methods. See [`UseCallToolReturn`](#usecalltoolreturn).
**Signature**
```ts wrap theme={null}
// Overload 1: type-safe with ToolRegistry
export function useCallTool(name: TName): UseCallToolReturn, ResolveOutput>;
// Overload 2: fallback with explicit generics
export function useCallTool = CallToolResponse>(name: string): UseCallToolReturn;
```
### Returns
The hook returns the current [`CallToolState`](#calltoolstate) spread together with two methods. Every field below is present on the returned object.
### status
The current lifecycle state of the tool call.
**Returns**
> `"idle"` before any call, `"pending"` while a call is in flight, `"success"` after the latest call resolves, and `"error"` after the latest call rejects.
### isIdle
Convenience boolean flag for the idle state.
**Returns**
> `true` when `status === "idle"` (no call has been made yet).
### isPending
Convenience boolean flag for the pending state.
**Returns**
> `true` when `status === "pending"` (a call is currently executing).
### isSuccess
Convenience boolean flag for the success state.
**Returns**
> `true` when `status === "success"`. When `true`, `data` is defined and `error` is `undefined`.
### isError
Convenience boolean flag for the error state.
**Returns**
> `true` when `status === "error"`. When `true`, `error` is defined and `data` is `undefined`.
### data
The tool result, available only after a successful call.
**Returns**
> The normalized response. `undefined` in every state except `success`. For registry-typed tools this is `CallToolResponse` with a typed `structuredContent`. See [`CallToolResponse`](#calltoolresponse).
### error
The error thrown by the tool call, available only after a failed call.
**Returns**
> The thrown error. `undefined` in every state except `error`. Typed as `unknown` because any value can be thrown.
### callTool
Fire-and-forget invocation with optional side effect callbacks.
`callTool` starts the tool call and returns `void` immediately. State (`isPending`, `data`, `error`, and so on) updates as the call progresses. You can pass a [`SideEffects`](#sideeffects) object to react to the result. When the tool input is optional (for example `null` input or all-optional fields), you may omit `args` entirely or pass only the side effects object as the first argument; the hook detects a side effects object by the presence of an `onSuccess`, `onError`, or `onSettled` key.
**Type**
```ts wrap theme={null}
callTool: CallToolFn
```
See [`CallToolFn`](#calltoolfn) for the full set of call signatures.
### callToolAsync
Promise-based invocation for sequential or `try`/`catch` flows.
`callToolAsync` starts the tool call and returns a `Promise` that resolves with the response or rejects with the thrown error. State flags update the same way as `callTool`. When the tool input is optional, you may call it with no arguments. Use this method to chain tool calls or to handle the result with `await` inside a `try`/`catch` block.
**Type**
```ts wrap theme={null}
callToolAsync: CallToolAsyncFn
```
See [`CallToolAsyncFn`](#calltoolasyncfn) for the full set of call signatures.
## generateHelpers
Generate fully-typed hook helpers from an explicit tool map.
This is an alternative to the automatic `ToolRegistry` approach. When using `mcp-use dev`, types are auto-generated in `.mcp-use/tool-registry.d.ts` and `useCallTool` is typed without this factory. Use `generateHelpers` for advanced cases: running without `mcp-use dev` (for example a custom build setup), scoping types to a subset of tools, or using different tool maps in different parts of your app. It returns an object containing a typed `useCallTool` and a typed `useToolInfo` hook, both bound to the supplied `TMap`.
```ts theme={null}
import { generateHelpers } from "mcp-use/react";
```
**Type Parameters**
> The tool map defining all tools and their input/output types. See [`ToolMap`](#toolmap).
**Returns**
> A `useCallTool` hook whose `name` argument is constrained to the keys of `TMap`, with input and output inferred from the map. See [`TypedUseCallTool`](#typedusecalltool).
> A `useToolInfo` hook that returns the current widget state typed against `TMap`. See [`TypedUseToolInfo`](#typedusetoolinfo).
**Signature**
```ts wrap theme={null}
export function generateHelpers(): { useCallTool: TypedUseCallTool; useToolInfo: () => UseWidgetResult>, UnknownObject, ToolOutput, UnknownObject, WidgetInputType>> };
```
## Types
### CallToolState
The discriminated union that models the four lifecycle states of a tool call.
Each variant fixes the boolean flags and the presence of `data` and `error`, so narrowing on `status` (or on any flag) gives type-safe access to `data` and `error`. The success variant is the only one where `data` is present, and the error variant is the only one where `error` is present.
```ts theme={null}
import type { CallToolState } from "mcp-use/react";
```
**Type Parameters**
> The type of `data` in the `success` variant.
**Signature**
```ts wrap theme={null}
export type CallToolState =
| { status: "idle"; isIdle: true; isPending: false; isSuccess: false; isError: false; data: undefined; error: undefined }
| { status: "pending"; isIdle: false; isPending: true; isSuccess: false; isError: false; data: undefined; error: undefined }
| { status: "success"; isIdle: false; isPending: false; isSuccess: true; isError: false; data: TData; error: undefined }
| { status: "error"; isIdle: false; isPending: false; isSuccess: false; isError: true; data: undefined; error: unknown };
```
### SideEffects
Optional callbacks passed to [`callTool`](#calltool), modeled after TanStack Query mutation callbacks.
All three callbacks are optional. `onSuccess` runs when the call resolves, `onError` runs when it rejects, and `onSettled` runs after either outcome. Each callback receives the original `args` that were passed to the call. In `onSettled`, exactly one of `data` or `error` is defined depending on the outcome.
```ts theme={null}
import type { SideEffects } from "mcp-use/react";
```
**Type Parameters**
> The type of the tool input arguments passed back to each callback.
> The type of the successful response.
**Signature**
```ts wrap theme={null}
export type SideEffects = {
onSuccess?: (data: TResponse, args: TArgs) => void;
onError?: (error: unknown, args: TArgs) => void;
onSettled?: (data: TResponse | undefined, error: unknown | undefined, args: TArgs) => void;
};
```
### CallToolFn
The call signature of [`callTool`](#calltool), the fire-and-forget method. Returns `void`.
The signature adapts to whether the tool input is optional. When the input type is optional (it is `null`, or all of its keys are optional), you can call with no arguments, with only a [`SideEffects`](#sideeffects) object, with only `args`, or with both. When the input is required, you must pass `args`, optionally followed by a `SideEffects` object.
```ts theme={null}
import type { CallToolFn } from "mcp-use/react";
```
**Type Parameters**
> The tool input type. Whether it is optional determines which overloads are available.
> The successful response type passed to the callbacks.
**Signature**
```ts wrap theme={null}
export type CallToolFn = IsArgsOptional extends true
? {
(): void;
(sideEffects: SideEffects): void;
(args: TArgs): void;
(args: TArgs, sideEffects: SideEffects): void;
}
: {
(args: TArgs): void;
(args: TArgs, sideEffects: SideEffects): void;
};
```
### CallToolAsyncFn
The call signature of [`callToolAsync`](#calltoolasync), the Promise-based method.
Like `CallToolFn`, it adapts to whether the input is optional. When the input is optional, you can call with no arguments or with `args`; both return `Promise`. When the input is required, you must pass `args`.
```ts theme={null}
import type { CallToolAsyncFn } from "mcp-use/react";
```
**Type Parameters**
> The tool input type. Whether it is optional determines which overloads are available.
> The type the returned `Promise` resolves with.
**Signature**
```ts wrap theme={null}
export type CallToolAsyncFn = IsArgsOptional extends true
? {
(): Promise;
(args: TArgs): Promise;
}
: (args: TArgs) => Promise;
```
### UseCallToolReturn
The full return type of [`useCallTool`](#usecalltool). Intersects the current [`CallToolState`](#calltoolstate) with the two call methods.
```ts theme={null}
import type { UseCallToolReturn } from "mcp-use/react";
```
**Type Parameters**
> The tool input type.
> The successful response type.
**Signature**
```ts wrap theme={null}
export type UseCallToolReturn = CallToolState & {
callTool: CallToolFn;
callToolAsync: CallToolAsyncFn;
};
```
### ToolMap
The structure of a tool map passed to [`generateHelpers`](#generatehelpers). Maps each tool name to its input and optional output types.
Each entry has a required `input` (an object type, or `null` when the tool takes no arguments) and an optional `output` object type. When `output` is omitted, the tool's response is the bare `CallToolResponse` without typed `structuredContent`.
```ts theme={null}
import type { ToolMap } from "mcp-use/react";
```
**Signature**
```ts wrap theme={null}
export type ToolMap = Record;
```
### ToolInput
Extracts the input type for a given tool name from a [`ToolMap`](#toolmap).
```ts theme={null}
import type { ToolInput } from "mcp-use/react";
```
**Type Parameters**
> The tool map to read from.
> The tool name whose input type to extract.
**Signature**
```ts wrap theme={null}
export type ToolInput = TMap[TName]["input"];
```
### ToolOutput
Extracts the output type for a given tool name from a [`ToolMap`](#toolmap), combined with [`CallToolResponse`](#calltoolresponse).
When the map entry declares an `output` object, the result is `CallToolResponse` intersected with `{ structuredContent: