ModelContext

ModelContext describes what the user currently sees. mcp-use merges that description with useViewState before sending it to the host.

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

function WeatherCard({
  city,
  temperature,
}: {
  city: string;
  temperature: number;
}) {
  return (
    <>
      <ModelContext
        content={`Showing weather for ${city}: ${temperature} degrees`}
      />
      <div>
        {city}: {temperature}°
      </div>
    </>
  );
}

For city="Paris" and temperature={22}, the serialized context is:

- Showing weather for Paris: 22 degrees

Nested ModelContext components form an indented context tree when the UI needs more detail.

Component signature

function ModelContext({
  content,
  children,
}: {
  content: string;
  children?: ReactNode;
}): ReactElement | null;

string

required

Text describing the visible UI. Whitespace-only content creates no node; nested nodes attach to the nearest non-empty ancestor.

ReactNode

default:"undefined"

Optional UI and nested ModelContext components. A self-closing component registers a leaf and renders null.

The component registers its node after mount, updates it when content changes, and removes it on unmount. Siblings retain their React registration order.

Describe dynamic UI

Use state-derived content so the context follows what is on screen:

const [tab, setTab] = useState("overview");

return (
  <ModelContext content="Analytics dashboard">
    <ModelContext content={`Active tab: ${tab}`} />
    <TabPanel tab={tab} onTabChange={setTab} />
  </ModelContext>
);

Multiple root components are allowed. They serialize as root-level sibling bullets.

Imperative API

Use modelContext for events and non-React code. Imperative entries join the same tree as root nodes.

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

modelContext.set("selected-item", "Selected product: Wireless Headphones");
modelContext.remove("selected-item");
modelContext.clear();

`modelContext.set(key, content)`

Creates or replaces a root entry under a stable key. It returns void.

`modelContext.remove(key)`

Removes the named imperative entry. Missing keys are ignored.

`modelContext.clear()`

Clears every component and imperative context node from the runtime store. Imperative entries are not tied to React lifecycle. Remove them explicitly when they become stale.

Merged host payload

The runtime stores the serialized tree under the reserved _uiContext key. This key is model-visible but hidden from the state returned by useViewState. For example, view state and context may produce:

{
  "count": 1,
  "_uiContext": "- Dashboard\n  - Revenue chart is visible"
}

On MCP Apps hosts, the complete object is sent as structuredContent, and its JSON representation is sent as a text content block. On ChatGPT, it is written to window.openai.widgetState.modelContent with setWidgetState. When the tree is empty, _uiContext remains present as an empty string. Context and state changes are batched, deduplicated, and coalesced while a host write is in flight.

Choose state or context

Need	API
A cart, selection, draft, filter, or other structured model-visible value	`useViewState`
A natural-language description of what is visible	`ModelContext` or `modelContext`
Ephemeral UI state the model does not need	React `useState`

Overview

Server

React

Client

Agent

Component signature

Describe dynamic UI

Imperative API

`modelContext.set(key, content)`

`modelContext.remove(key)`

`modelContext.clear()`

Merged host payload

Choose state or context

​Component signature

​Describe dynamic UI

​Imperative API

​modelContext.set(key, content)

​modelContext.remove(key)

​modelContext.clear()

​Merged host payload

​Choose state or context

​Related

Component signature

Describe dynamic UI

Imperative API

`modelContext.set(key, content)`

`modelContext.remove(key)`

`modelContext.clear()`

Merged host payload

Choose state or context

Related