Protocol discrepancies between MCP Apps and Apps SDK

[fredericbarthelet]

My current understanding of the ongoing effort of MCP Apps extension is to serve as the common standard shared by all clients:

This SEP [SEP-1865] addresses the current limitations through an optional, backwards-compatible extension that unifies the approaches pioneered by MCP-UI and the Apps SDK into a single, open standard.

From SEP-1865 initial message

However, as of today, there are still discrepancies between the current version of OpenAI Apps SDK and MCP Apps Extension. Some are just interface differences that can be unified under a common interface with some adaptors like the ones from MCP-UI or from Skybridge or even the draft #172). Some others simply can't be achieve with the existing tooling.

I tried listing those hereafter in order to have a better picture of the current situation with associated ongoing efforts on missing pieces. Feel free to let me know if something is missing.

Which of those will remain not implemented in ext-apps? Which should be discussed further to make their way in the final implementation before GA?

Pre-declared meta

On tool (tools/list operation)

Apps SDK	Ext Apps	Comment
_meta["securitySchemes"]		Deferred
_meta["openai/outputTemplate"]	_meta["ui"].resourceUri	Aligned ✅
_meta["openai/widgetAccessible"]		Deferred
_meta["openai/visibility"]	_meta["ui"].visibility	Aligned ✅
_meta["openai/toolInvocation/invoking"]		Deferred
_meta["openai/toolInvocation/invoked"]		Deferred
_meta["openai/fileParams"]		Deferred

On resource (resource/read operation)

Apps SDK	Ext Apps	Comment
_meta["openai/widgetDescription"]		Deferred
_meta["openai/widgetPrefersBorder"]	_meta["ui"].prefersBorder	Aligned ✅
_meta["openai/widgetCSP"]	_meta["ui"].csp	connect & resource domains included in both standards. frame and redirect only available in apps sdk. Will be added in #158
_meta["openai/widgetDomain"]	_meta["ui"].domain	Aligned ✅

Dynamic comms

Properties available in widget (Host -> UI)

Apps SDK	Ext Apps	Comment
window.openai.toolInput	ui/notifications/tool-input	Aligned ✅
window.openai.toolOutput	ui/notifications/tool-result	Aligned ✅
window.openai.toolResponseMetadata	ui/notifications/tool-result	Aligned ✅
_meta["openai/widgetSessionId"]		Deferred (sessions will likely be added in some form in the future)
	ui/notifications/tool-cancelled
	ui/resource-teardown
window.openai.widgetState		Discussed in #62
window.openai.theme	theme	Aligned ✅
window.openai.displayMode	displayMode	missing "modal" value in apps sdk
	availableDisplayModes
window.openai.maxHeight	viewport.maxHeight	Aligned ✅
window.openai.safeArea	safeAreaInsets	Aligned ✅
window.openai.view
window.openai.userAgent	deviceCapabilities & platform	Aligned ✅
	userAgent
window.openai.locale	locale	Aligned ✅
	timeZone
	styles
	toolInfo

Properties added by host on tool call (Host -> Server)

Apps SDK	Ext Apps	Comment
_meta["openai/userAgent"]
_meta["openai/locale"]
_meta["openai/userLocation"]
_meta["openai/subject"]

Methods (UI -> Host)

Apps SDK	Ext Apps	Comment
window.openai.setWidgetState(state)		Discussed in #61 and #62 as everything set in widget state is injected in model's context. To be clear, #62 will support writing to a shared mutable state with the model. All other related capabilities have been deferred
window.openai.callTool(name, args)	tools/call	Aligned ✅
	resources/read
window.openai.sendFollowUpMessage({ prompt })	ui/message	Aligned ✅
window.openai.requestDisplayMode({ mode })	ui/request-display-mode	Aligned ✅
window.openai.requestModal({ title, params, anchor })		Deferred
window.openai.notifyIntrinsicHeight()	ui/notifications/size-changed	missing "width" in apps sdk
window.openai.openExternal({ href })	ui/open-link	Aligned ✅
window.openai.requestClose()		#203
window.openai.uploadFile(file)		Deferred
window.openai.getFileDownloadUrl({ fileId })		Deferred

Others

• _meta["mcp/www_authenticate"] sent by MCP server in the tools/call response as a challenge to trigger OAuth
• Hosted-backed navigation - discussion in SEP: Host Backed Navigation #147

Edited on Jan 7th with @idosal comments

[idosal]

Thanks for mapping this out @fredericbarthelet, it's greatly appreciated! I've filled out the table with comments. Please feel free to point out any substantial gaps or suggestions.

My current understanding of the ongoing effort of MCP Apps extension is to serve as the common standard shared by all clients:

This SEP [SEP-1865] addresses the current limitations through an optional, backwards-compatible extension that unifies the approaches pioneered by MCP-UI and the Apps SDK into a single, open standard.

From SEP-1865 initial message

However, as of today, there are still discrepancies between the current version of OpenAI Apps SDK and MCP Apps Extension. Some are just interface differences that can be unified under a common interface with some adaptors like the ones from MCP-UI or from Skybridge or even the draft #172). Some others simply can't be achieve with the existing tooling.

I tried listing those hereafter in order to have a better picture of the current situation with associated ongoing efforts on missing pieces. Feel free to let me know if something is missing.

Which of those will remain not implemented in ext-apps? Which should be discussed further to make their way in the final implementation before GA?

Pre-declared meta

On tool (tools/list operation)

Apps SDK Ext Apps Comment
_meta["securitySchemes"] Deferred
_meta["openai/outputTemplate"] _meta["ui"].resourceUri Aligned ✅
_meta["openai/widgetAccessible"] Deferred
_meta["openai/visibility"] _meta["ui"].visibility Aligned ✅
_meta["openai/toolInvocation/invoking"] Deferred
_meta["openai/toolInvocation/invoked"] Deferred
_meta["openai/fileParams"] Deferred

On resource (resource/read operation)

Apps SDK Ext Apps Comment
_meta["openai/widgetDescription"] Deferred
_meta["openai/widgetPrefersBorder"] _meta["ui"].prefersBorder Aligned ✅
_meta["openai/widgetCSP"] _meta["ui"].csp connect & resource domains included in both standards. frame and redirect only available in apps sdk. Will be added in #158
_meta["openai/widgetDomain"] _meta["ui"].domain Aligned ✅

Dynamic comms

Properties available in widget (Host -> UI)

Apps SDK Ext Apps Comment
window.openai.toolInput ui/notifications/tool-input Aligned ✅
window.openai.toolOutput ui/notifications/tool-result Aligned ✅
window.openai.toolResponseMetadata ui/notifications/tool-result Aligned ✅
_meta["openai/widgetSessionId"] Deferred (sessions will likely be added in some form in the future)
ui/notifications/tool-cancelled
ui/resource-teardown
window.openai.widgetState Discussed in #62
window.openai.theme theme Aligned ✅
window.openai.displayMode displayMode missing "modal" value in apps sdk
availableDisplayModes
window.openai.maxHeight viewport.maxHeight Aligned ✅
ui/notifications/size-changed
window.openai.safeArea safeAreaInsets Aligned ✅
window.openai.view
window.openai.userAgent deviceCapabilities & platform Aligned ✅
userAgent
window.openai.locale locale Aligned ✅
timeZone
styles
toolInfo

Properties added by host on tool call (Host -> Server) - These seem more on the core protocol layer than App-specific

Apps SDK Ext Apps Comment
_meta["openai/userAgent"]
_meta["openai/locale"]
_meta["openai/userLocation"]
_meta["openai/subject"]

Methods (UI -> Host)

Apps SDK Ext Apps Comment
window.openai.setWidgetState(state) Discussed in #61 and #62 as everything set in widget state is injected in model's context To be clear, #62 will support writing to a shared mutable state with the model. All other related capabilities have been deferred
window.openai.callTool(name, args) tools/call Aligned ✅
resources/read
window.openai.sendFollowUpMessage({ prompt }) ui/message Aligned ✅
window.openai.requestDisplayMode({ mode }) ui/request-display-mode Aligned ✅
window.openai.requestModal({ title, params, anchor }) Deferred
window.openai.notifyIntrinsicHeight() Not sure what this method does. MCP Apps has ui/notifications/size-changed.
window.openai.openExternal({ href }) ui/open-link Aligned ✅
window.openai.requestClose() #203
window.openai.uploadFile(file) Deferred
window.openai.getFileDownloadUrl({ fileId }) Deferred

Others

• _meta["mcp/www_authenticate"] sent by MCP server in the tools/call response as a challenge to trigger OAuth
• Hosted-backed navigation - discussion in SEP: Host Backed Navigation #147

[liady]

Great work on mapping these @fredericbarthelet 🙏

[fredericbarthelet]

Thanks for your comments @idosal @liady - I updated the initial message accordingly.

Just to make sure: deferred means it'll be postponed after GA? Are you open to have the conversations on implementing those features after that? Or should they remain outside of the extension (like file handling for exemple) ?

Also, some features are lacking on Apps SDK side. Do you know if those will be backported at some point as well (like styles or resource/read) ?

[liady]

@fredericbarthelet as for the "missing" features on Apps SDK - while this is of course OpenAI's product decision I imagine that we'll still see such differences between the specs.
MCP Apps is meant to be a universal spec that can be rendered on any host, but of course hosts can still define their own specs that may or may not overlap with it.