From 99d208055ba9e7fac4992f0df243ed79bd5b1ad9 Mon Sep 17 00:00:00 2001
From: Rizel Scarlett <rizel@squareup.com>
Date: Wed, 18 Feb 2026 16:55:11 -0500
Subject: [PATCH 1/4] docs: add Permission Policy documentation for MCP Apps

- Add 'Requesting Browser Permissions' section documenting camera, microphone,
  geolocation, and clipboardWrite permissions
- Update CSP configuration to remove deprecated frameDomains and baseUriDomains
- Update server.js example to remove deprecated CSP fields

Ref: PR #6947
---
 .../docs/tutorials/building-mcp-apps.md       | 86 ++++++++++++++-----
 1 file changed, 66 insertions(+), 20 deletions(-)

diff --git a/documentation/docs/tutorials/building-mcp-apps.md b/documentation/docs/tutorials/building-mcp-apps.md
index 7bcbd7ca6600..b27388814855 100644
--- a/documentation/docs/tutorials/building-mcp-apps.md
+++ b/documentation/docs/tutorials/building-mcp-apps.md
@@ -169,8 +169,6 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
               csp: {
                 connectDomains: [],
                 resourceDomains: [],
-                frameDomains: [],
-                baseUriDomains: [],
               },
               prefersBorder: true,
             },
@@ -538,7 +536,7 @@ MCP Apps run in a sandboxed iframe with strict Content Security Policy restricti
 
 ### Content Security Policy Configuration
 
-By default, apps can only load resources from their own origin. If your app needs to interact with external domains—such as loading resources from a CDN, making API calls, or embedding maps—you can configure which domains are allowed through the `csp` object in the resource's `_meta.ui` section.
+By default, apps can only load resources from their own origin. If your app needs to interact with external domains—such as loading resources from a CDN or making API calls—you can configure which domains are allowed through the `csp` object in the resource's `_meta.ui` section.
 
 ```javascript
 _meta: {
@@ -546,8 +544,6 @@ _meta: {
     csp: {
       connectDomains: [],      // Domains for fetch/XHR requests
       resourceDomains: [],     // Domains for scripts, styles, images, fonts, media
-      frameDomains: [],        // Origins allowed for nested iframes
-      baseUriDomains: [],      // Additional allowed base URIs
     },
   },
 }
@@ -557,37 +553,87 @@ _meta: {
 |--------|---------------|---------|---------|
 | `connectDomains` | `connect-src` | Domains your app can make network requests to | Same-origin only |
 | `resourceDomains` | `script-src`, `style-src`, `img-src`, `font-src`, `media-src` | Domains for loading external resources | Same-origin only |
-| `frameDomains` | `frame-src` | Origins allowed for nested `<iframe>` elements | `'none'` (no iframes) |
-| `baseUriDomains` | `base-uri` | Additional domains allowed for `<base>` element | `'self'` only |
 
 <details>
-<summary>Examples</summary>
-
-**Embedding a map:**
+<summary>Example: Loading resources from a CDN</summary>
 
 ```javascript
 csp: {
-  frameDomains: ['https://www.openstreetmap.org'],
-  resourceDomains: ['https://tile.openstreetmap.org'],
+  resourceDomains: ['https://cdn.jsdelivr.net', 'https://unpkg.com'],
+  connectDomains: ['https://api.example.com'],
 }
 ```
 
-**Loading resources from a CDN:**
+</details>
+
+:::warning Security Consideration
+Only add domains you trust. Each domain you add expands what external content can be loaded or embedded in your app. Keep the list minimal and specific to reduce security risks.
+:::
+
+### Requesting Browser Permissions
+
+MCP Apps can request specific browser permissions using Permission Policy. This is useful for apps that need access to device capabilities like camera, microphone, or location services.
+
+To declare permissions for your MCP App, include the `permissions` object in the resource's `_meta.ui` section:
 
 ```javascript
-csp: {
-  resourceDomains: ['https://cdn.jsdelivr.net', 'https://unpkg.com'],
-  connectDomains: ['https://api.example.com'],
+_meta: {
+  ui: {
+    permissions: {
+      camera: true,           // Request camera access
+      microphone: true,       // Request microphone access
+      geolocation: true,      // Request geolocation access
+      clipboardWrite: true,   // Request clipboard write access
+    },
+  },
 }
 ```
 
-</details>
+| Permission | Permission Policy Feature | Use Case |
+|------------|---------------------------|----------|
+| `camera` | `camera` | Video capture, QR code scanning |
+| `microphone` | `microphone` | Audio recording, voice input |
+| `geolocation` | `geolocation` | Location-aware apps, maps |
+| `clipboardWrite` | `clipboard-write` | Copy to clipboard functionality |
 
-See the [MCP Apps Specification](https://github.com/modelcontextprotocol/ext-apps) for details on security and the full protocol.
+All permissions default to `false`. Only request the permissions your app actually needs.
 
-:::warning Security Consideration
-Only add domains you trust. Each domain you add expands what external content can be loaded or embedded in your app. Keep the list minimal and specific to reduce security risks.
+<details>
+<summary>Example: Video recording app</summary>
+
+```javascript
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const { uri } = request.params;
+
+  if (uri === "ui://my-video-app/recorder") {
+    return {
+      contents: [
+        {
+          uri: "ui://my-video-app/recorder",
+          mimeType: "text/html;profile=mcp-app",
+          text: VIDEO_RECORDER_HTML,
+          _meta: {
+            ui: {
+              permissions: {
+                camera: true,
+                microphone: true,
+              },
+            },
+          },
+        },
+      ],
+    };
+  }
+});
+```
+
+</details>
+
+:::info User Consent Required
+Even when an MCP App requests permissions, the browser will still prompt the user for consent before granting access. Users can deny permission requests at any time.
 :::
 
+See the [MCP Apps Specification](https://github.com/modelcontextprotocol/ext-apps) for details on security and the full protocol.
+
 
 

From 03678eb74ef466caeba9cd5d15a8b4f2b9511c6c Mon Sep 17 00:00:00 2001
From: Rizel Scarlett <rizel@squareup.com>
Date: Wed, 18 Feb 2026 16:59:06 -0500
Subject: [PATCH 2/4] docs: remove emdashes from tutorial

---
 documentation/docs/tutorials/building-mcp-apps.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/documentation/docs/tutorials/building-mcp-apps.md b/documentation/docs/tutorials/building-mcp-apps.md
index b27388814855..89c07bda92b5 100644
--- a/documentation/docs/tutorials/building-mcp-apps.md
+++ b/documentation/docs/tutorials/building-mcp-apps.md
@@ -530,13 +530,13 @@ Try:
 └──────────────────────────────────────┘
 ```
 
-Your server returns a `ui://` resource URI, goose fetches the HTML and renders it in an iframe. The app communicates back via `postMessage`—requesting theme info, sending messages to chat, or resizing itself.
+Your server returns a `ui://` resource URI, goose fetches the HTML and renders it in an iframe. The app communicates back via `postMessage` to request theme info, send messages to chat, or resize itself.
 
 MCP Apps run in a sandboxed iframe with strict Content Security Policy restrictions.
 
 ### Content Security Policy Configuration
 
-By default, apps can only load resources from their own origin. If your app needs to interact with external domains—such as loading resources from a CDN or making API calls—you can configure which domains are allowed through the `csp` object in the resource's `_meta.ui` section.
+By default, apps can only load resources from their own origin. If your app needs to interact with external domains (such as loading resources from a CDN or making API calls), you can configure which domains are allowed through the `csp` object in the resource's `_meta.ui` section.
 
 ```javascript
 _meta: {

From 0a3ab2e26c0471ea41c54bf577cd85a8932c3538 Mon Sep 17 00:00:00 2001
From: Rizel Scarlett <rizel@squareup.com>
Date: Wed, 18 Feb 2026 17:13:28 -0500
Subject: [PATCH 3/4] docs: add Permission Policy documentation for MCP Apps

Add 'Requesting Browser Permissions' section documenting camera, microphone,
geolocation, and clipboardWrite permissions that MCP Apps can request.

Ref: PR #6947
---
 .../docs/tutorials/building-mcp-apps.md       | 23 ++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/documentation/docs/tutorials/building-mcp-apps.md b/documentation/docs/tutorials/building-mcp-apps.md
index 89c07bda92b5..5305cd5a264a 100644
--- a/documentation/docs/tutorials/building-mcp-apps.md
+++ b/documentation/docs/tutorials/building-mcp-apps.md
@@ -169,6 +169,8 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
               csp: {
                 connectDomains: [],
                 resourceDomains: [],
+                frameDomains: [],
+                baseUriDomains: [],
               },
               prefersBorder: true,
             },
@@ -530,13 +532,13 @@ Try:
 └──────────────────────────────────────┘
 ```
 
-Your server returns a `ui://` resource URI, goose fetches the HTML and renders it in an iframe. The app communicates back via `postMessage` to request theme info, send messages to chat, or resize itself.
+Your server returns a `ui://` resource URI, goose fetches the HTML and renders it in an iframe. The app communicates back via `postMessage`—requesting theme info, sending messages to chat, or resizing itself.
 
 MCP Apps run in a sandboxed iframe with strict Content Security Policy restrictions.
 
 ### Content Security Policy Configuration
 
-By default, apps can only load resources from their own origin. If your app needs to interact with external domains (such as loading resources from a CDN or making API calls), you can configure which domains are allowed through the `csp` object in the resource's `_meta.ui` section.
+By default, apps can only load resources from their own origin. If your app needs to interact with external domains—such as loading resources from a CDN, making API calls, or embedding maps—you can configure which domains are allowed through the `csp` object in the resource's `_meta.ui` section.
 
 ```javascript
 _meta: {
@@ -544,6 +546,8 @@ _meta: {
     csp: {
       connectDomains: [],      // Domains for fetch/XHR requests
       resourceDomains: [],     // Domains for scripts, styles, images, fonts, media
+      frameDomains: [],        // Origins allowed for nested iframes
+      baseUriDomains: [],      // Additional allowed base URIs
     },
   },
 }
@@ -553,9 +557,22 @@ _meta: {
 |--------|---------------|---------|---------|
 | `connectDomains` | `connect-src` | Domains your app can make network requests to | Same-origin only |
 | `resourceDomains` | `script-src`, `style-src`, `img-src`, `font-src`, `media-src` | Domains for loading external resources | Same-origin only |
+| `frameDomains` | `frame-src` | Origins allowed for nested `<iframe>` elements | `'none'` (no iframes) |
+| `baseUriDomains` | `base-uri` | Additional domains allowed for `<base>` element | `'self'` only |
 
 <details>
-<summary>Example: Loading resources from a CDN</summary>
+<summary>Examples</summary>
+
+**Embedding a map:**
+
+```javascript
+csp: {
+  frameDomains: ['https://www.openstreetmap.org'],
+  resourceDomains: ['https://tile.openstreetmap.org'],
+}
+```
+
+**Loading resources from a CDN:**
 
 ```javascript
 csp: {

From 545de4a8fe31a4dd8bcedce93a7edd45eac02924 Mon Sep 17 00:00:00 2001
From: Rizel Scarlett <rizel@squareup.com>
Date: Wed, 18 Feb 2026 17:29:54 -0500
Subject: [PATCH 4/4] docs: clarify that permissions are requests, not
 guarantees

---
 documentation/docs/tutorials/building-mcp-apps.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/docs/tutorials/building-mcp-apps.md b/documentation/docs/tutorials/building-mcp-apps.md
index 5305cd5a264a..230cd5c4c56f 100644
--- a/documentation/docs/tutorials/building-mcp-apps.md
+++ b/documentation/docs/tutorials/building-mcp-apps.md
@@ -589,7 +589,7 @@ Only add domains you trust. Each domain you add expands what external content ca
 
 ### Requesting Browser Permissions
 
-MCP Apps can request specific browser permissions using Permission Policy. This is useful for apps that need access to device capabilities like camera, microphone, or location services.
+MCP Apps can request specific browser permissions using Permission Policy. This is useful for apps that need access to device capabilities like camera, microphone, or location services. These are requests only - the host may not grant them, and apps should use feature detection to handle cases where permissions are unavailable.
 
 To declare permissions for your MCP App, include the `permissions` object in the resource's `_meta.ui` section: