mcp-use - The fullstack MCP framework to develop MCP Apps for ChatGPT / Claude and MCP Servers for AI Agents.

Interactive widgets can call tools, save UI state, send follow-up messages, and request a larger display mode. Use these APIs for user actions that should happen inside the widget instead of requiring another prompt. This guide assumes your widget already renders with useWidget(). See Build widgets first if you still need the server and widget setup. Use useCallTool() when a button or form should call another MCP tool. The hook gives you loading, success, and error state.

import { useCallTool } from "mcp-use/react";

function DetailsButton({ productId }: { productId: string }) {
  const { callTool, data, isPending, isError } = useCallTool("get-product");

  return (
    <section>
      <button onClick={() => callTool({ productId })} disabled={isPending}>
        {isPending ? "Loading..." : "View details"}
      </button>

      {isError && <p>Could not load product details.</p>}
      {data && <pre>{JSON.stringify(data.structuredContent, null, 2)}</pre>}
    </section>
  );
}

Prefer useCallTool() for user-facing actions. Use useWidget().callTool only for small one-off calls where you do not need hook-managed state. Use setState for UI state that should survive re-renders and be available to future model turns.

import { useWidget } from "mcp-use/react";

type FavoritesState = {
  favorites: string[];
};

function FavoriteButton({ id }: { id: string }) {
  const { state, setState } = useWidget<{}, FavoritesState>();
  const favorites = state?.favorites ?? [];
  const isFavorite = favorites.includes(id);

  async function toggleFavorite() {
    await setState({
      favorites: isFavorite
        ? favorites.filter((favoriteId) => favoriteId !== id)
        : [...favorites, id],
    });
  }

  return (
    <button onClick={toggleFavorite}>
      {isFavorite ? "Remove favorite" : "Save favorite"}
    </button>
  );
}

Use widget state for view state and user choices. Do not use widget state as your database.

Send a follow-up message

Use sendFollowUpMessage when a widget action should ask the model to continue the conversation.

import { useWidget } from "mcp-use/react";

function ExplainButton({ productName }: { productName: string }) {
  const { sendFollowUpMessage } = useWidget();

  return (
    <button
      onClick={() =>
        sendFollowUpMessage(`Compare ${productName} with similar products.`)
      }
    >
      Compare
    </button>
  );
}

Follow-up messages create a new model turn. Use them for actions that need model reasoning, not for local UI updates.

Request display modes

Use requestDisplayMode when a widget needs more room.

import { useWidget } from "mcp-use/react";

function DisplayModeControls() {
  const { displayMode, requestDisplayMode } = useWidget();
  const expanded = displayMode === "fullscreen" || displayMode === "pip";

  return (
    <button onClick={() => requestDisplayMode(expanded ? "inline" : "fullscreen")}>
      {expanded ? "Exit" : "Expand"}
    </button>
  );
}

The host may grant a different mode than requested. Read displayMode for the actual current mode.

Combine actions carefully

A single click should usually do one main thing. For example:

call a tool to fetch more data
update widget state after a user choice
send a follow-up message for model reasoning
request fullscreen for a larger view

If one action must do multiple things, update local widget state first so the UI responds immediately, then call the tool or send the follow-up message.

Next steps

Use Model context to decide what the model should know about these interactions.
Use useCallTool() for full call state and typing details.
Use useWidget() for all host actions and display-mode behavior.

Get Started

MCP Server

MCP Apps

MCP Client

MCP Agent

Tooling

Interactivity

Call tools from a widget

Save widget state

Send a follow-up message

Request display modes

Combine actions carefully

Next steps

​Call tools from a widget

​Save widget state

​Send a follow-up message

​Request display modes

​Combine actions carefully

​Next steps

Call tools from a widget

Save widget state

Send a follow-up message

Request display modes

Combine actions carefully

Next steps