feat: enhance sandbox capability negotiation by idosal · Pull Request #158 · modelcontextprotocol/ext-apps

idosal · 2025-12-15T22:45:35Z

Proposal to tackle #58 -

Add frameDomains and baseUriDomains overrides to Resource Metadata's ui/csp attribute
Add a permissions attribute(ui/permissions) to the Resource Metadata. Currently, it supports camera, microphone, and geolocation. There are many other permissions, but I think we should only add fields as they're needed. @alexi-openai could you please share what OpenAI allows?
Add csp to Host<>App capability negotiation (since it's non-trivial for the app to detect at runtime)

If it's acceptable, I'll add an E2E test before merging.

Thoughts?

pkg-pr-new · 2025-12-15T22:46:28Z

@modelcontextprotocol/ext-apps

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

@modelcontextprotocol/server-basic-react

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

@modelcontextprotocol/server-basic-vanillajs

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

@modelcontextprotocol/server-budget-allocator

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

@modelcontextprotocol/server-cohort-heatmap

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

@modelcontextprotocol/server-customer-segmentation

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

@modelcontextprotocol/server-scenario-modeler

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

@modelcontextprotocol/server-system-monitor

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

@modelcontextprotocol/server-threejs

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

@modelcontextprotocol/server-wiki-explorer

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

commit: 88c9ed4

Copilot

Pull request overview

This PR enhances the MCP Apps sandbox capability negotiation by adding support for additional CSP directives and permissions policies. The changes enable apps to request nested iframe support, custom base URI configuration, and browser permissions (camera, microphone, geolocation) through resource metadata.

Key changes:

Added frameDomains and baseUriDomains fields to CSP configuration for controlling nested iframes and base URI directives
Introduced permissions metadata for requesting camera, microphone, and geolocation access via Permission Policy
Extended host capability negotiation to include CSP support indicators (frameDomains and baseUriDomains)

Reviewed changes

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

Show a summary per file

File	Description
src/types.ts	Added exports for new `McpUiResourcePermissions` type and schema
src/spec.types.ts	Defined new interfaces for permissions and extended CSP configuration with frame/baseUri domains
src/generated/schema.ts	Added Zod schemas for permissions and extended CSP schemas with new domain fields
src/generated/schema.test.ts	Updated type inference tests to include new permissions schema
src/generated/schema.json	Generated JSON schemas for new permissions and CSP extensions
specification/draft/apps.mdx	Documented new CSP fields and permissions with examples and security guidance
examples/simple-host/sandbox.html	Added new sandbox proxy HTML implementation (missing CSP/permissions handling)
examples/basic-host/src/sandbox.ts	Implemented CSP meta tag building and iframe allow attribute for permissions
examples/basic-host/src/implementation.ts	Extended resource data extraction to include new CSP and permissions metadata

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

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

ochafik

Thanks Ido!

ochafik · 2025-12-16T13:38:26Z

+ baseUriDomains?: string[];
+ };
+ permissions?: {
+ camera?: boolean;


let's make these objects (as in capabilities) for future extensions?
e.g. what if one day there's fine-grained vers. coarse geolocation, or front vs. back camera permission, etc.

Like CSP, Permissions are coupled to the browser spec (Permissions Policy). I don't think we should diverge at this point. WDYT?

There are 40+ Permission Policies you can stuff in an iFrame. Consider keeping permissions very simple and flexible, just have it be a string[].
Benefits:
Client can set all permission policies with a single string. Flexible for future extensions.
Enforcing this on the client side is simple. We just stuff the string into an iFrame's allow. This is safe because invalid strings are silently ignored.
Still easily parseable on the server side. Server developer only has to do permissions.contains("camera");.

Alternatively create some interface and have permission be an array of that interface if type safety and enforcement is of high importance.
interface Permissions { camera: "camera", .... }
permissions?: Permissions[]

ochafik

We should tell app what permissions were granted (and potentially which domains were allowed)

…ties

matteo8p · 2025-12-22T22:43:11Z

Is there an iFrame in the ext-apps project, or that out of the scope of this extension project? I'm wondering where the permissions are getting enforced into the iFrame.

matteo8p · 2025-12-22T22:48:39Z

I can see this being useful if the MCP server needs to know what the browser capabilities / permissions are. However, I'm pretty sure you can also fetch the browser capability within the widget too using document.featurePolicy.allowedFeatures().

https://developer.mozilla.org/en-US/docs/Web/API/FeaturePolicy/allowedFeatures

I perhaps React widgets should be using this instead as a source of truth.

matteo8p · 2025-12-22T23:01:32Z

@idosal I think OpenAI currently allows local-network-access *; microphone *; midi *

I have no clue why midi is on there. That's for music instruments haha

idosal · 2026-01-07T00:30:28Z

I can see this being useful if the MCP server needs to know what the browser capabilities / permissions are. However, I'm pretty sure you can also fetch the browser capability within the widget too using document.featurePolicy.allowedFeatures().
https://developer.mozilla.org/en-US/docs/Web/API/FeaturePolicy/allowedFeatures
I perhaps React widgets should be using this instead as a source of truth.

Thanks @matteo8p ! Permissions were originally excluded from negotiation because they could be detected directly. It was considered that the negotiation assumes less about the app runtime and the developer's awareness of the browser APIs. We should explore this further with the community to come to a decision.

ochafik · 2026-01-07T16:14:34Z

+ if (event.data && event.data.method === 'ui/notifications/sandbox-resource-ready') {
+ const { html, sandbox, permissions } = event.data.params || {};
+ // Note: csp is not extracted here - CSP is set via HTTP response headers in serve.ts
+ if (typeof sandbox === 'string') {


we probably need to set the sandbox attribute in the host itself (and let them be inherited transparently here), cf. comments from @domfarolino during today's meeting.
(or else, the child, being same origin, will be able to change its own sandbox attributes by poking at its parent dom ; or would be able to create other iframes w/o these limitations)

(same way that CSP settings are defined in the headers serving this page, and not injected by this page)

Yeah, I think whatever features are enabled inside of sandbox.html will be inherited by the same-origin iframe inner. So I think what really needs to happen is the explicit capability delegation to the iframe whose source is sandbox.html, and we should get delegation to the same-origin app contents for free. This is important because any changes made to sandbox and permissions policies here, after inner has been inserted into the DOM, will not apply to content (the html string, in this case) that has been synchronously written into the frame after the attributes change. For those attributes to take effect, the inner iframe will have to re-navigate to apply the attribute changes.

domfarolino · 2026-01-07T17:07:09Z

+ if (event.data && event.data.method === 'ui/notifications/sandbox-resource-ready') {
+ const { html, sandbox, permissions } = event.data.params || {};
+ // Note: csp is not extracted here - CSP is set via HTTP response headers in serve.ts
+ if (typeof sandbox === 'string') {


Yeah, I think whatever features are enabled inside of sandbox.html will be inherited by the same-origin iframe inner. So I think what really needs to happen is the explicit capability delegation to the iframe whose source is sandbox.html, and we should get delegation to the same-origin app contents for free. This is important because any changes made to sandbox and permissions policies here, after inner has been inserted into the DOM, will not apply to content (the html string, in this case) that has been synchronously written into the frame after the attributes change. For those attributes to take effect, the inner iframe will have to re-navigate to apply the attribute changes.

domfarolino · 2026-01-07T17:10:00Z

+ try {
+ if (inner.contentDocument) {
+ inner.contentDocument.open();
+ inner.contentDocument.write(html);


Note that as mentioned above, I don't think any changes made to inner's allow or sandbox attributes will take effect after inner has been inserted to the DOM. You'll need to re-navigate the iframe for those attributes to stick.
Probably what you want to do is hold of on appending inner to the DOM until after you parse and set the intended attribute values. Or, given the comment further above, maybe we don't need to send the attribute values all the way down here, since inner should inherit most things from sandbox.html, since it's a same-origin iframe.

Implements early support for proposed CSP extensions to the MCP Apps spec: - frameDomains: Controls frame-src directive for nested iframes - baseUriDomains: Controls base-uri directive This anticipates changes proposed in: modelcontextprotocol/ext-apps#158 Note: The upstream spec PR is not yet merged, but we're implementing early to validate the approach.

aharvard · 2026-01-08T15:25:16Z

Getting ahead of this and goose and implementing frameDomains and baseUriDoamins: aaif-goose/goose#6399

PTAL if interested.

…Domains, permissions Security improvements: - CSP is now set via HTTP headers in serve.ts instead of meta tags (meta tag CSP can be tampered with by same-origin content) - CSP passed as query param to sandbox.html for header-based enforcement New CSP/permissions features (borrowed from PR #158): - frameDomains: control frame-src directive for nested iframes - baseUriDomains: control base-uri directive - permissions: camera, microphone, geolocation via iframe allow attribute WebGL fix: - Use document.write() instead of srcdoc for inner iframe content (srcdoc creates opaque origin that breaks WebGL canvas updates) - Add worker-src directive with blob: support (critical for WebGL apps like CesiumJS/Three.js that use workers for tile decoding, terrain processing, image processing) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Keep this PR focused on CSP security fixes only. Permissions (camera, microphone, geolocation) will be handled in #158. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

ochafik · 2026-01-11T13:45:11Z

Note: I've created #234 to implement a reference csp handling in the sandbox's server, I've sneaked the frameDomains and baseUriDomains there. Maybe this PR can focus on the sandbox permissions? @idosal wdyt?

…er-src, document.write) (#234) * fix: Move CSP to HTTP headers + add worker-src, frameDomains, baseUriDomains, permissions Security improvements: - CSP is now set via HTTP headers in serve.ts instead of meta tags (meta tag CSP can be tampered with by same-origin content) - CSP passed as query param to sandbox.html for header-based enforcement New CSP/permissions features (borrowed from PR #158): - frameDomains: control frame-src directive for nested iframes - baseUriDomains: control base-uri directive - permissions: camera, microphone, geolocation via iframe allow attribute WebGL fix: - Use document.write() instead of srcdoc for inner iframe content (srcdoc creates opaque origin that breaks WebGL canvas updates) - Add worker-src directive with blob: support (critical for WebGL apps like CesiumJS/Three.js that use workers for tile decoding, terrain processing, image processing) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * refactor: Remove permissions support (defer to PR #158) Keep this PR focused on CSP security fixes only. Permissions (camera, microphone, geolocation) will be handled in #158. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * cleanup McpUiResourceCsp type usage / duplicate defs * fix: guard against CSP injection in domain parameters Validate CSP domain entries to reject characters that could: - Break out of CSP directives (semicolons, newlines) - Inject CSP keywords like 'unsafe-eval' (quotes) - Inject multiple sources in one entry (spaces) This prevents injection attacks where malicious domains could override the security policy. --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

ochafik · 2026-01-12T11:21:00Z

I've created an speech example that relies on microphone and clipboard-write: #240

@idosal mind if i help refresh this PR / push to this branch?

Merges the latest main branch changes including: - HTTP header-based CSP enforcement (more secure than meta tags) - frameDomains and baseUriDomains support Added from this branch: - McpUiResourcePermissions type for camera/microphone/geolocation - Permission Policy support via iframe allow attribute - Host capabilities sandbox section for permissions negotiation

Adds clipboardWrite to McpUiResourcePermissions for clipboard access. Maps to Permission Policy 'clipboard-write' feature.

ochafik · 2026-01-12T13:48:04Z

Merged main + pushed a few changes; Suggested updates for this PR (@idosal does this sg?):

Title: feat: add sandbox permissions support (camera, microphone, geolocation, clipboard-write)

Body:

Closes #58

Summary

This PR adds Permission Policy support for MCP Apps sandboxes, allowing apps to request browser capabilities like
camera, microphone, geolocation, and clipboard access.

Note: The CSP enhancements (frameDomains, baseUriDomains) and HTTP header-based CSP enforcement were
implemented separately in #234 and have been merged into this branch.

What's New

Permissions Support

Apps can now declare which browser permissions they need via resource metadata:

_meta: {ui: {permissions: {camera: {},microphone: {},geolocation: {},clipboardWrite: {},}}}Thesemaptothe https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Permissions_Policy allow attribute on the innersandboxiframe.HostCapabilityNegotiationHostsreportgrantedsandboxcapabilitiesbacktoappsviahostCapabilities.sandbox: hostCapabilities: {sandbox: {permissions: {camera: {},microphone: {}, ... },csp: {connectDomains: [...],resourceDomains: [...], ... }}}Thisallowsappstodetectatinitializationtimewhichpermissionsweregranted,ratherthanrelyingsolelyonruntimefeaturedetection.SupportedPermissions┌────────────────┬───────────────────┬───────────────────────────────────┐│Permission│PermissionPolicy│UseCase│├────────────────┼───────────────────┼───────────────────────────────────┤│camera│camera│Videocapture│├────────────────┼───────────────────┼───────────────────────────────────┤│microphone│microphone│Audiocapture,speechrecognition│├────────────────┼───────────────────┼───────────────────────────────────┤│geolocation│geolocation│Locationservices│├────────────────┼───────────────────┼───────────────────────────────────┤│clipboardWrite│clipboard-write│Copytoclipboard│└────────────────┴───────────────────┴───────────────────────────────────┘Additionalpermissionscanbeaddedasneeded(e.g.,midi,fullscreen).Implementation-Types: McpUiResourcePermissionsinspec.types.ts-Schemas: Auto-generatedZodschemas-Sandbox: buildAllowAttribute()insandbox.tsappliespermissionstoinneriframe-Host: Passespermissionsviaui/notifications/sandbox-resource-ready-Spec: Updatedapps.mdxwithpermissionsdocumentationTesting-✅54unittestspass-✅51e2etestspass(Docker)DesignDiscussionAsnotedby @matteo8p,appscanalsodetectpermissionsatruntimeviadocument.featurePolicy.allowedFeatures().The negotiation approachwaschosenbecause: 1.Itdoesn't assume app developers know about browser APIs 2.Itallowscapabilitydetectionatinitializationtime3.ItfollowstheexistingpatternforCSPnegotiation

antonpk1

this is great!

Additional sandbox negotiation options Refs modelcontextprotocol/ext-apps#158

feat: enhance sandbox capability negotiation
699549e

idosal requested review from alexi-openai, antonpk1, Copilot, liady and ochafik December 15, 2025 22:45

Copilotstarted reviewing on behalf of idosal December 15, 2025 22:45 View session

CopilotAI reviewed Dec 15, 2025
View reviewed changes

Comment threadspecification/draft/apps.mdx Outdated
Comment threadexamples/basic-host/src/sandbox.ts Outdated
Comment threadexamples/simple-host/sandbox.html Outdated
Comment threadexamples/basic-host/src/sandbox.ts

Update specification/draft/apps.mdx
7aef0d8
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

ochafik requested changes Dec 16, 2025
View reviewed changes

ochafik reviewed Dec 17, 2025
View reviewed changes

idosal added 2 commits December 18, 2025 21:53

Merge remote-tracking branch 'origin/main' into feat/sandbox-capabili…
0e4e524
…ties

add all csp and permissions to host capabilities + update SEP
e038020

idosal requested a review from ochafik December 18, 2025 20:31

idosal mentioned this pull request Jan 7, 2026
Protocol discrepancies between MCP Apps and Apps SDK #201
Open

ochafik reviewed Jan 7, 2026
View reviewed changes

domfarolino reviewed Jan 7, 2026
View reviewed changes

aharvard mentioned this pull request Jan 8, 2026
Add frameDomains and baseUriDomains CSP support for MCP Apps aaif-goose/goose#6399
Merged

ochafik mentioned this pull request Jan 11, 2026
fix: proper CSP handling in basic-host sandboxing (HTTP headers, worker-src, document.write) #234
Merged

ochafik mentioned this pull request Jan 12, 2026
examples: add transcript-server example with live speech transcription #240
Merged

ochafik added 5 commits January 12, 2026 12:20

feat: add clipboard-write permission support
ad92da0
Adds clipboardWrite to McpUiResourcePermissions for clipboard access. Maps to Permission Policy 'clipboard-write' feature.

rm files added by mistake
166aeb3

refactor: change McpUiResourcePermissions properties to empty objects
d2f53a6

chore: remove scratch files and redundant cross-env dependency
88c9ed4

antonpk1 approved these changes Jan 12, 2026
View reviewed changes

ochafik approved these changes Jan 12, 2026
View reviewed changes

ochafik merged commit 9acc52c into mainJan 12, 2026
19 checks passed

connor4312 added a commit to microsoft/vscode that referenced this pull request Jan 12, 2026
mcp: adopt ext-apps#158
fbf5f9d
Additional sandbox negotiation options Refs modelcontextprotocol/ext-apps#158

connor4312 mentioned this pull request Jan 12, 2026
mcp: adopt ext-apps#158 microsoft/vscode#287134
Merged

connor4312 added a commit to microsoft/vscode that referenced this pull request Jan 12, 2026
mcp: adopt ext-apps#158 (#287134)
77e7e7c
Additional sandbox negotiation options Refs modelcontextprotocol/ext-apps#158

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

eli-w-king pushed a commit to microsoft/vscode that referenced this pull request Jan 14, 2026
mcp: adopt ext-apps#158 (#287134)
f95bfa9
Additional sandbox negotiation options Refs modelcontextprotocol/ext-apps#158

ochafik mentioned this pull request Jan 21, 2026
Finalize permissions #320
Open

domfarolino mentioned this pull request Jan 28, 2026
feat: add sandbox flags negotiation #355
Open
9 tasks

pedrumj2 pushed a commit to pedrumj2/Agentic that referenced this pull request Jun 30, 2026
mcp: adopt ext-apps#158 (#287134)
1084aa0
Additional sandbox negotiation options Refs modelcontextprotocol/ext-apps#158

Uh oh!

Conversation

idosal commented Dec 15, 2025

Uh oh!

pkg-pr-newBot commented Dec 15, 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!

Uh oh!

ochafik left a comment

Choose a reason for hiding this comment

Uh oh!

ochafikDec 16, 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!

matteo8pDec 22, 2025

Choose a reason for hiding this comment

Uh oh!

matteo8pDec 22, 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!

Uh oh!

ochafik left a comment

Choose a reason for hiding this comment

Uh oh!

matteo8p commented Dec 22, 2025

Uh oh!

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

Uh oh!

Uh oh!

matteo8p commented Dec 22, 2025

Uh oh!

idosal commented Jan 7, 2026

Uh oh!

ochafikJan 7, 2026• 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!

ochafikJan 7, 2026

Choose a reason for hiding this comment

Uh oh!

domfarolinoJan 7, 2026

Choose a reason for hiding this comment

Uh oh!

domfarolinoJan 7, 2026

Choose a reason for hiding this comment

Uh oh!

domfarolinoJan 7, 2026

Choose a reason for hiding this comment

Uh oh!

aharvard commented Jan 8, 2026

Uh oh!

ochafik commented Jan 11, 2026

Uh oh!

ochafik commented Jan 12, 2026

Uh oh!

ochafik commented Jan 12, 2026

Summary

What's New

Permissions Support

Uh oh!

antonpk1 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

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

idosalDec 18, 2025•
edited
Loading

matteo8pDec 22, 2025•
edited
Loading

matteo8p commented Dec 22, 2025•
edited
Loading

ochafikJan 7, 2026•
edited
Loading