feat: add ui/update-model-context by idosal · Pull Request #125 · modelcontextprotocol/ext-apps

idosal · 2025-12-10T17:49:53Z

This new message allows the UI to update the Host's model context without triggering a follow-up action.

`ui/update-model-context` - Update the Host's model context
// Request
{
jsonrpc: "2.0",
id: 3,
method: "ui/update-model-context",
params: {
role: "user",
content: ContentBlock[]
}
}
Guest UI MAY send this request to inform the agent about app state changes that should be added to the model's context for future reasoning. This event serves a different use case from `notifications/message` (logging) and `ui/message` (which also trigger followups).
Host behavior:
- SHOULD provide the context to the model in future turns
- SHOULD overwrite the previous model context with the new update
- MAY display context updates to the user

notifications/message remains another message type with MCP's original intent.

Addresses #61.

Note: the params's type (content: ContentBlock[]) may be problematic for the MVP. It's subject to the same decision as #119 (comment)

pkg-pr-new · 2025-12-10T17:50:45Z

Open in StackBlitz

@modelcontextprotocol/ext-apps

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/ext-apps@125

@modelcontextprotocol/server-basic-react

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-basic-react@125

@modelcontextprotocol/server-basic-vanillajs

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-basic-vanillajs@125

@modelcontextprotocol/server-budget-allocator

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-budget-allocator@125

@modelcontextprotocol/server-cohort-heatmap

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-cohort-heatmap@125

@modelcontextprotocol/server-customer-segmentation

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-customer-segmentation@125

@modelcontextprotocol/server-scenario-modeler

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-scenario-modeler@125

@modelcontextprotocol/server-system-monitor

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-system-monitor@125

@modelcontextprotocol/server-threejs

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-threejs@125

@modelcontextprotocol/server-wiki-explorer

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-wiki-explorer@125

commit: d8156f9

Copilot

Pull request overview

This PR introduces the ui/update-context request to allow Guest UI applications to inform the host agent about app state changes that should be stored in the conversation context for future reasoning, without triggering follow-up actions. This addresses the need to distinguish between logging messages (notifications/message), interactive messages that expect follow-ups (ui/message), and context updates that inform the agent's reasoning.

Key changes:

Added ui/update-context request type with role and ContentBlock[] parameters
Extended host capabilities to include optional context capability for negotiation
Implemented sendContext() method in App class and oncontext handler in AppBridge class

Reviewed changes

Copilot reviewed 6 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/types.ts	Re-exports new McpUiUpdateContextRequest/Result types and schemas
src/spec.types.ts	Defines TypeScript interfaces for update-context request/result and adds context capability to McpUiHostCapabilities
src/generated/schema.ts	Adds Zod schemas for validating update-context requests and results
src/generated/schema.test.ts	Adds type inference tests to verify schema/type compatibility
src/generated/schema.json	Contains JSON schema definitions for update-context with full ContentBlock support
src/app.ts	Implements sendContext() method for Guest UI to send context updates to host
src/app-bridge.ts	Implements oncontext handler for Host to receive context updates from Guest UI
src/app-bridge.test.ts	Adds integration tests covering basic sendContext functionality with single and multiple content blocks
specification/draft/apps.mdx	Documents ui/update-context in the protocol specification with examples and host behavior guidelines

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 6 out of 9 changed files in this pull request and generated 6 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 6 out of 9 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

ochafik

Something to discuss: I wonder if we want to go full multimedia on this one.
Also, in OAI Apps SDK the updates are essentially structuredContent, and text might also often be the most useful kind of update, so both would place us in the territory of Pick<CallToolResult, 'content' | 'structuredContent' | 'isError'> more than a message content block array

ochafik · 2025-12-11T17:46:19Z

We probably also need to mention that the host MAY defer sending the context to the model, and it MAY dedupe identical ui/update-context calls.
Potentially we could add a boolean that says it replaces / purges any previously pending

How about SHOULD provide the context to the model in future turns?
We always replace now

ochafik · 2025-12-11T17:51:41Z

And should this be ui/update-semantic-state?

I think semantic-state isn't as self-documenting as model-context

antonpk1

Thanks for the proposal! I think we should design the state that only the last 'context-update' is used, and all past context updates are disregarded.

Here's a specific example: imagine a text-editor app. The user can write and edit text and wants to be able to ask the agent to help/reflect/act on the current text state.

Problem with the current proposal: if we send a 'context-update' with full text on every character change, it will quickly pollute the entire context window and won't work well.

At the same time, if an app wants to share context with a chronological history of events like in current proposal, nothing prevents them from accumulating an array and passing that as a 'context-update'.

idosal · 2025-12-18T22:37:18Z

Thanks for the proposal! I think we should design the state that only the last 'context-update' is used, and all past context updates are disregarded.
Here's a specific example: imagine a text-editor app. The user can write and edit text and wants to be able to ask the agent to help/reflect/act on the current text state.
Problem with the current proposal: if we send a 'context-update' with full text on every character change, it will quickly pollute the entire context window and won't work well.
At the same time, if an app wants to share context with a chronological history of events like in current proposal, nothing prevents them from accumulating an array and passing that as a 'context-update'.

After further discussions, for the MVP, we propose clarifying that ui/update-model-context will overwrite the previous state. In the future, following community feedback and requirements, we can extend it to enable maintaining history and other enhancements.

idosal · 2025-12-18T22:55:19Z

Something to discuss: I wonder if we want to go full multimedia on this one. Also, in OAI Apps SDK the updates are essentially structuredContent, and text might also often be the most useful kind of update, so both would place us in the territory of Pick<CallToolResult, 'content' | 'structuredContent' | 'isError'> more than a message content block array

I think this is the last open item. I can see value in pushing non-textual information (like images) into context. Thoughts?

antonpk1 · 2026-01-06T18:27:28Z

Thanks for this, the overall design is great! The ui/update-model-context name and behavior (overwrite semantics, no follow-up trigger) looks solid.

Two suggestions:

Method naming: Could we rename sendUpdateModelContext to just updateModelContext? This would be consistent with other API methods where we avoid using two verbs at the beginning (e.g., we have openLink()).
Params type: The role: "user" field doesn't add much value here - it's always "user" and the concept of "role" doesn't quite fit this use case (we're updating context, not sending a message). As @ochafik suggested, we could use something like Pick<CallToolResult, 'content' | 'structuredContent' | 'isError'> instead for consistency with tool call results.

lmk what you think!

idosal · 2026-01-07T00:48:06Z

Thanks for this, the overall design is great! The ui/update-model-context name and behavior (overwrite semantics, no follow-up trigger) looks solid.
Two suggestions:
Method naming: Could we rename sendUpdateModelContext to just updateModelContext? This would be consistent with other API methods where we avoid using two verbs at the beginning (e.g., we have openLink()).
Params type: The role: "user" field doesn't add much value here - it's always "user" and the concept of "role" doesn't quite fit this use case (we're updating context, not sending a message). As @ochafik suggested, we could use something like Pick<CallToolResult, 'content' | 'structuredContent' | 'isError'> instead for consistency with tool call results.
lmk what you think!

Thanks @antonpk1 ! Makes sense. I'll update the PR tomorrow so we can merge.

antonpk1 · 2026-01-08T13:57:49Z

Thanks @antonpk1 ! Makes sense. I'll update the PR tomorrow so we can merge.

thank you, Ido! looking forward to it

ochafik

Thanks @idosal, sorry for the delay!

ochafik · 2026-01-09T01:40:39Z

+ *
+ * @returns Promise that resolves when the context update is acknowledged
+ */
+ sendUpdateModelContext(


updateModelContext
the current pattern is to avoid double verbs (w/ exception of sendMessage as message is ambiguous)

ochafik · 2026-01-09T01:42:56Z

+ * @description Result from setting the agent's model context.
+ * @see {@link McpUiUpdateModelContextRequest}
+ */
+export interface McpUiUpdateModelContextResult {


we probably can just rely on the request erroring (i.e. use EmptyResult for this one)

ochafik · 2026-01-09T01:44:18Z

+ method: "ui/update-model-context";
+ params: {
+ /** @description Message role, currently only "user" is supported. */
+ role: "user";


can we remove the role? (In OAI land, their role would be tool anyway; the real role here is kinda app)

ochafik · 2026-01-09T01:44:54Z

+ /** @description Message role, currently only "user" is supported. */
+ role: "user";
+ /** @description Context content blocks (text, image, etc.). */
+ content: ContentBlock[];


can we add structuredContent?

ochafik · 2026-01-09T01:48:36Z

 /** @description Host accepts log messages. */
 logging?: {};
+ /** @description Host accepts context updates to be included in the model's context for future turns. */
+ updateModelContext?: {};


Suggested change
updateModelContext?: {};
updateModelContext?: {
text?: {};
image?: {};
audio?: {};
resource?: {};
resourceLink?: {};
structuredContent?: {};
};

- Rename sendUpdateModelContext → updateModelContext (avoid double verbs) - Remove role field from params (always user, adds no value) - Add structuredContent support for machine-readable context data - Use EmptyResult instead of {isError?: boolean} for result type - Errors now signaled via JSON-RPC error responses - Update capability to specify supported content types: text, image, audio, resource, resourceLink, structuredContent - Add spec guidance for deferred delivery semantics: - Host MAY defer until next user message - Host MAY dedupe identical updates - Only last update before user message is sent to model

- Create reusable McpUiSupportedContentBlockModalities interface - Use it for both updateModelContext and message capabilities - Add message capability to advertise ui/message content type support

Gives hosts flexibility to accumulate context history if desired, rather than mandating replacement semantics.

ochafik · 2026-01-12T13:37:59Z

@idosal I pushed some commits implementing the review feedback. Here's a suggested updated PR description:

This new message allows the UI to update the Host's model context without triggering a follow-up action.

// Request{jsonrpc: "2.0",id: 3,method: "ui/update-model-context",params: {content?: ContentBlock[],structuredContent?: Record<string,unknown>}}

Guest UI MAY send this request to inform the agent about app state changes that should be added to the model's context for future reasoning. Each request overwrites the previous context. This differs from notifications/message (logging) and ui/message (which triggers follow-ups).

Host behavior:

SHOULD provide the context to the model in future turns
MAY overwrite the previous model context with the new update
MAY defer sending until the next user message (including ui/message)
MAY dedupe identical calls; only last update before user message is sent
MAY display context updates to the user

notifications/message remains another message type with MCP's original intent.

Addresses #61.

Summary of changes from review feedback:

Removed role field (always "user", added no value)
Added structuredContent for machine-readable context data
Made both fields optional
Renamed method: sendUpdateModelContext → updateModelContext
Empty result {}; errors via JSON-RPC error responses
Extracted McpUiSupportedContentBlockModalities for capability negotiation
Added message capability to McpUiHostCapabilities for symmetry

antonpk1

very cool!

# Conflicts: # src/generated/schema.json # src/generated/schema.test.ts # src/generated/schema.ts # src/spec.types.ts

…sult)

idosal added 2 commits December 10, 2025 19:41

feat: add ui/update-context
6727390

lint
69b7570

CopilotAI review requested due to automatic review settings December 10, 2025 17:49

Copilotstarted reviewing on behalf of idosal December 10, 2025 17:50 View session

sequence diagram
0085768

CopilotAI reviewed Dec 10, 2025
View reviewed changes

Comment threadsrc/app-bridge.ts Outdated
Comment threadsrc/app-bridge.test.ts Outdated
Comment threadsrc/app-bridge.ts Outdated

cr
b848642

idosal requested a review from Copilot December 10, 2025 18:07

Copilotstarted reviewing on behalf of idosal December 10, 2025 18:07 View session

idosal mentioned this pull request Dec 10, 2025
SEP: Context update mechanism #61
Closed

CopilotAI reviewed Dec 10, 2025
View reviewed changes

Comment threadsrc/spec.types.ts Outdated
Comment threadsrc/app.ts Outdated
Comment threadsrc/app.ts Outdated
Comment threadsrc/app-bridge.ts Outdated
Comment threadsrc/app.ts Outdated
Comment threadspecification/draft/apps.mdx Outdated

CR
5369d33

idosal requested a review from Copilot December 10, 2025 20:17

Copilotstarted reviewing on behalf of idosal December 10, 2025 20:17 View session

CopilotAI reviewed Dec 10, 2025
View reviewed changes

Comment threadsrc/app-bridge.ts Outdated

idosal added 2 commits December 10, 2025 22:21

comment
0447af5

rename capability
7392629

liady previously approved these changes Dec 11, 2025
View reviewed changes

ochafik reviewed Dec 11, 2025
View reviewed changes

antonpk1 requested changes Dec 11, 2025
View reviewed changes

ochafik mentioned this pull request Dec 16, 2025
feat: experimental OpenAI Apps SDK compatibility #172
Draft

idosal added 2 commits December 19, 2025 00:30

Update to update-model-context
9e920c9

clean up comment
27f950a

idosal dismissed liady’s stale review via 27f950aDecember 18, 2025 22:32

Merge remote-tracking branch 'origin/main' into feat/update-context
a809478

idosal requested a review from antonpk1 December 18, 2025 22:49

idosal requested a review from ochafik December 18, 2025 22:50

idosal changed the title ~~feat: add ui/update-context~~feat: add ui/update-model-contextDec 18, 2025

liady mentioned this pull request Dec 20, 2025
spec: remove Intents reference from rationale #187
Merged
1 task

idosal mentioned this pull request Dec 23, 2025
[MCP Apps] Set widget state #194
Closed
9 tasks

fredericbarthelet mentioned this pull request Jan 8, 2026
Enable support for widgetState alternative on MCP app renderer alpic-ai/skybridge#267
Closed

ochafik requested changes Jan 9, 2026
View reviewed changes

ochafik reviewed Jan 9, 2026
View reviewed changes

connor4312 mentioned this pull request Jan 9, 2026
spec: Add tool registration for Apps, to be called by Host (WebMCP-style!) #72
Merged

fredericbarthelet mentioned this pull request Jan 9, 2026
Polyfill - useWidgetState alpic-ai/skybridge#167
Closed

This was referenced Jan 11, 2026
examples: Add CesiumJS Map App example #235
Merged
examples: add transcript-server example with live speech transcription #240
Merged

ochafik added 3 commits January 12, 2026 13:11

refactor: extract McpUiSupportedContentBlockModalities type
0e2ad4b
- Create reusable McpUiSupportedContentBlockModalities interface - Use it for both updateModelContext and message capabilities - Add message capability to advertise ui/message content type support

spec: change overwrite behavior from SHOULD to MAY
2b0869d
Gives hosts flexibility to accumulate context history if desired, rather than mandating replacement semantics.

antonpk1 previously approved these changes Jan 12, 2026
View reviewed changes

Merge branch 'main' into feat/update-context
d8156f9
# Conflicts: # src/generated/schema.json # src/generated/schema.test.ts # src/generated/schema.ts # src/spec.types.ts

ochafik dismissed antonpk1’s stale review via d8156f9January 12, 2026 15:15

refactor: remove redundant McpUiUpdateModelContextResult (use EmptyRe…
0d65356
…sult)

ochafik approved these changes Jan 12, 2026
View reviewed changes

ochafik merged commit b273279 into mainJan 12, 2026
18 checks passed

ochafik mentioned this pull request Jan 12, 2026
chore: release 0.4.0 #249
Merged

aharvard mentioned this pull request Jan 13, 2026
feat: Implement ui/update-model-context for MCP Apps aaif-goose/goose#6472
Closed

ochafik mentioned this pull request Jan 21, 2026
Notification when model context was read by model #319
Open

- updateModelContext?: {};
+ updateModelContext?: {
+ text?: {};
+ image?: {};
+ audio?: {};
+ resource?: {};
+ resourceLink?: {};
+ structuredContent?: {};
+};

Uh oh!

Conversation

idosal commented Dec 10, 2025• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-newBot commented Dec 10, 2025• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

ochafik left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ochafikDec 11, 2025

Choose a reason for hiding this comment

Uh oh!

idosalDec 18, 2025

Choose a reason for hiding this comment

Uh oh!

ochafikDec 11, 2025

Choose a reason for hiding this comment

Uh oh!

idosalDec 18, 2025• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

antonpk1 left a comment

Choose a reason for hiding this comment

Uh oh!

idosal commented Dec 18, 2025• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

idosal commented Dec 18, 2025

Uh oh!

antonpk1 commented Jan 6, 2026

Uh oh!

idosal commented Jan 7, 2026

Uh oh!

antonpk1 commented Jan 8, 2026

Uh oh!

ochafik left a comment

Choose a reason for hiding this comment

Uh oh!

ochafikJan 9, 2026

Choose a reason for hiding this comment

Uh oh!

ochafikJan 9, 2026

Choose a reason for hiding this comment

Uh oh!

ochafikJan 9, 2026

Choose a reason for hiding this comment

Uh oh!

ochafikJan 9, 2026

Choose a reason for hiding this comment

Uh oh!

ochafikJan 9, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

idosal commented Dec 10, 2025•
edited
Loading

pkg-pr-newBot commented Dec 10, 2025•
edited
Loading

ochafik left a comment •
edited
Loading

idosalDec 18, 2025•
edited
Loading

idosal commented Dec 18, 2025•
edited
Loading

ochafikJan 9, 2026•
edited
Loading