1# Model Context Annotations
2 
3Keep the AI model aware of what the user is currently seeing in your widget — without requiring explicit tool calls or storing data in developer-managed state.
4 
5Both APIs feed into a shared global registry that serializes to an indented tree string, pushed to the host via `ui/update-model-context` (MCP Apps) or `setWidgetState` (ChatGPT Apps SDK). Updates are batched via `queueMicrotask`.
6 
7---
8 
9## When to Use
10 
11| Situation | Use |
12|-----------|-----|
13| Annotate what the user is *seeing* right now | `<ModelContext>` or `modelContext.set()` |
14| Annotate in JSX, tied to component lifecycle | `<ModelContext content="...">` |
15| Annotate from an event handler or outside React | `modelContext.set(key, value)` |
16| Persist structured state the model reads on future turns | `setState` from `useWidget` |
17 
18Do **not** use `<ModelContext>` as a replacement for `setState`. They serve different purposes:
19- `setState` = developer-managed state (cart, selections, filters). Explicit, you control the shape.
20- `ModelContext` = declarative description of what the user *sees*. Set it and forget it.
21 
22---
23 
24## `<ModelContext>` Component
25 
26Declarative, lifecycle-tied, nesting-aware. Removes itself from the tree on unmount — no cleanup needed.
27 
28```tsx
29import { ModelContext, useWidget, McpUseProvider } from "mcp-use/react";
30 
31export default function DashboardWidget() {
32  const { props, isPending } = useWidget<{ activeTab: string }>();
33  const [hovered, setHovered] = useState<string | null>(null);
34 
35  if (isPending) return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
36 
37  return (
38    <McpUseProvider autoSize>
39      {/* Root annotation — present for the full widget lifetime */}
40      <ModelContext content="User is viewing the analytics dashboard">
41 
42        {/* Re-registers automatically when props.activeTab changes */}
43        <ModelContext content={`Active tab: ${props.activeTab}`} />
44 
45        {/* Conditional — only present while something is hovered */}
46        {hovered && (
47          <ModelContext content={`Hovering over chart: ${hovered}`} />
48        )}
49 
50        {/* Nesting — children become child nodes in the model's tree */}
51        <ModelContext content="Metrics panel">
52          <ModelContext content="Revenue chart visible" />
53          <ModelContext content="User count visible" />
54        </ModelContext>
55 
56        <div>{/* widget UI */}</div>
57      </ModelContext>
58    </McpUseProvider>
59  );
60}
61```
62 
63The model receives an indented tree:
64```
65- User is viewing the analytics dashboard
66  - Active tab: overview
67  - Hovering over chart: Revenue Q4
68  - Metrics panel
69    - Revenue chart visible
70    - User count visible
71```
72 
73### Nesting Rules
74 
75- `<ModelContext>` at the same JSX level → siblings (flat list at that depth)
76- `<ModelContext>` inside another's `children` → child node in the tree
77- Self-closing `<ModelContext content="..." />` → leaf node, no children needed
78 
79---
80 
81## `modelContext` Module-Level API
82 
83Imperative, works anywhere — event handlers, plain functions, `useEffect`, outside React entirely. Entries are always root-level (no parent).
84 
85```tsx
86import { modelContext } from "mcp-use/react";
87 
88// From an event handler
89function onProductSelect(product: Product) {
90  modelContext.set("selection", `User selected: ${product.name} ($${product.price})`);
91}
92 
93function onDrawerClose() {
94  modelContext.remove("selection");
95}
96 
97// From useEffect (lifecycle-aware)
98useEffect(() => {
99  modelContext.set("page", `Viewing page ${currentPage} of ${totalPages}`);
100  return () => modelContext.remove("page");
101}, [currentPage, totalPages]);
102```
103 
104| Method | Description |
105|--------|-------------|
106| `modelContext.set(key, content)` | Register or update a named entry. Same key = overwrite. |
107| `modelContext.remove(key)` | Remove an entry by key. |
108| `modelContext.clear()` | Remove all entries (component-based and imperative). |
109 
110**Important:** Unlike `<ModelContext>`, `modelContext.set()` entries are NOT automatically cleaned up on component unmount. Always call `.remove(key)` in cleanup logic, or use `<ModelContext>` when you need automatic lifecycle management.
111 
112---
113 
114## How the Tree is Sent to the Model
115 
116The serialized string is sent under a reserved `__model_context` key:
117- **MCP Apps**: `ui/update-model-context` with `structuredContent.__model_context`
118- **ChatGPT Apps SDK**: `setWidgetState` with `__model_context` merged into the state object
119 
120`__model_context` is **filtered from the developer-facing `state`** returned by `useWidget` — it never appears in your code.
121 
122Calling `setState` from `useWidget` preserves the current `__model_context` value, so user state updates never wipe annotations.
123 
124---
125 
126## Common Patterns
127 
128### Tab-switching widget
129 
130```tsx
131const [tab, setTab] = useState("overview");
132 
133<ModelContext content={`User is on the ${tab} tab`}>
134  <TabContent tab={tab} />
135</ModelContext>
136```
137 
138### Selected item (imperative)
139 
140```tsx
141function onSelect(item: Item) {
142  modelContext.set("selected", `Selected: ${item.name}`);
143}
144function onDeselect() {
145  modelContext.remove("selected");
146}
147```
148 
149### Multi-level dashboard
150 
151```tsx
152<ModelContext content="Dashboard — overview mode">
153  <ModelContext content={`Showing ${period} data`} />
154  <ModelContext content={`${visibleCharts.length} charts visible`} />
155</ModelContext>
156```
157 
158---
159 
160## Reference
161 
162- Full API reference: https://docs.mcp-use.com/typescript/server/widget-components/modelcontext
163- Example server: `examples/server/ui/model-context/`
164