MCP App Resource _meta — CSP, Permissions, Domain & Border

MCP Apps SDK

Overview

Resource _meta.ui controls security, rendering, and sandbox behavior for MCP App Views. All fields are optional. This metadata is set on resources registered via registerAppResource.

_meta: {
  ui: {
    csp: { connectDomains: ["https://api.example.com"] },
    permissions: { camera: {} },
    domain: "a904794854a047f6.claudemcpcontent.com",
    prefersBorder: false,
  },
}

Where to Set `_meta`

Set _meta.ui on individual contents[] items returned by the registerAppResource read callback when the host needs to enforce CSP, permissions, stable domains, or border preferences for the rendered View.

import { registerAppResource, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";

registerAppResource(server, "Music Player", "ui://music/player.html", {
  description: "Interactive music player",
}, async () => ({
  contents: [
    {
      uri: "ui://music/player.html",
      mimeType: RESOURCE_MIME_TYPE,
      text: musicPlayerHtml,
      _meta: {
        ui: {
          csp: { connectDomains: ["https://api.spotify.com"] },
          permissions: { microphone: {} },
          prefersBorder: false,
        },
      },
    },
  ],
}));

Advanced: listing-level vs content-item

When using registerAppResource, you can set _meta in two places:

Listing-level — in the config object. Hosts see this in the resources/list response at connection time.
Content-item level — on individual contents[] items returned by the read callback. Content-item values take precedence.

Use content-item metadata for values that affect the rendered iframe. Listing-level metadata is useful as a static hint during discovery, but a host that renders a View reads the resource content and should apply the content-item metadata.

Fields

`csp` — Content Security Policy

McpUiResourceCsp

Declares which external origins your View needs. The host uses these to build CSP headers for the sandboxed iframe.

MCP App HTML runs in a sandboxed iframe with no same-origin server. You must declare all origins — including where your bundled JS/CSS is served from (localhost in dev, your CDN in production).

Field	CSP Directive	Purpose
`connectDomains`	`connect-src`	fetch, XHR, and WebSocket origins
`resourceDomains`	`img-src`, `script-src`, `style-src`, `font-src`, `media-src`	Static resource origins (images, scripts, stylesheets, fonts, media)
`frameDomains`	`frame-src`	Nested iframe origins (e.g., YouTube embeds)
`baseUriDomains`	`base-uri`	Allowed base URIs for the document

All fields accept arrays of origin strings. Wildcard subdomains are supported (e.g., https://*.example.com). Empty or omitted fields default to no external access — this is the secure default.

_meta: {
  ui: {
    csp: {
      connectDomains: ["https://api.example.com", "wss://realtime.example.com"],
      resourceDomains: ["https://cdn.example.com", "https://*.cloudflare.com"],
      frameDomains: ["https://www.youtube.com", "https://player.vimeo.com"],
      baseUriDomains: ["https://cdn.example.com"],
    },
  },
}

`connectDomains`

Origins for network requests — fetch(), XMLHttpRequest, and WebSocket connections. Maps to the CSP connect-src directive. If omitted, no network connections are allowed from the View (secure default).

`resourceDomains`

Origins for static resources — images, scripts, stylesheets, fonts, and media files. Maps to CSP img-src, script-src, style-src, font-src, and media-src directives. If omitted, no external resources can be loaded (secure default).

`frameDomains`

Origins for nested iframes within your View. Maps to the CSP frame-src directive. Use this for embedding third-party content like YouTube or Vimeo players. If omitted, nested iframes are blocked (frame-src 'none').

`baseUriDomains`

Allowed base URIs for the document. Maps to the CSP base-uri directive. If omitted, only the same origin is allowed (base-uri 'self').

`permissions` — Sandbox Permissions

McpUiResourcePermissions

Requests browser capabilities for the View’s iframe. Each permission is declared as an empty object {} — its presence requests the capability.

Field	Permission Policy	Purpose
`camera`	`camera`	Camera access (e.g., for photo capture, video calls)
`microphone`	`microphone`	Microphone access (e.g., for voice input, audio recording)
`geolocation`	`geolocation`	Location access (e.g., for maps, local search)
`clipboardWrite`	`clipboard-write`	Clipboard write access (e.g., for “copy to clipboard” buttons)

Hosts MAY honor these permissions by setting appropriate iframe allow attributes, but are not required to. Your View should use JavaScript feature detection as a fallback and degrade gracefully when permissions are not granted.

_meta: {
  ui: {
    permissions: {
      camera: {},
      microphone: {},
      geolocation: {},
      clipboardWrite: {},
    },
  },
}

`domain` — Stable Sandbox Origin

string

Requests a stable, dedicated origin for the View’s sandbox iframe. The value is not your server’s domain — it’s a subdomain within the host’s sandbox domain space.

By default, hosts assign each View an ephemeral sandbox origin (typically per-conversation). Setting domain tells the host to use a stable, deterministic origin instead — useful when external services need to recognize your app by origin. Use cases:

OAuth callbacks — redirect URIs require a stable origin on the allowlist
CORS policies — API servers that check Origin headers need a known value to allowlist
API key restrictions — external services that restrict by origin

This field is host-specific. The value is a subdomain within the host’s own sandbox domain — not your server’s domain. Each host has its own format:

Host	Domain format	Example
Claude	`{sha256-hash}.claudemcpcontent.com`	`a904794854a047f6.claudemcpcontent.com`
ChatGPT	`{url-derived}.oaiusercontent.com`	`www-example-com.oaiusercontent.com`

A cross-platform server must compute different values per host. For APIs using Access-Control-Allow-Origin: * or API key auth, you don’t need domain at all.

import crypto from "node:crypto";

// Claude: hash-based subdomain derived from your MCP server URL
function computeDomainForClaude(mcpServerUrl: string): string {
  const hash = crypto
    .createHash("sha256")
    .update(mcpServerUrl)
    .digest("hex")
    .slice(0, 32);
  return `${hash}.claudemcpcontent.com`;
}

// Usage (single host)
_meta: {
  ui: {
    domain: computeDomainForClaude("https://example.com/mcp"),
  },
}

Cross-platform servers

A server that supports multiple hosts needs different domain values per host. The sunpeak framework accepts a map of clientInfo.name to domain string, with an optional default fallback for unmatched hosts:

import { computeClaudeDomain, computeChatGPTDomain } from "sunpeak/mcp";

const SERVER_URL = "https://example.com/mcp";

// sunpeak resolves the correct value based on the connecting host's clientInfo.name
_meta: {
  ui: {
    domain: {
      claude: computeClaudeDomain(SERVER_URL),
      "openai-mcp": computeChatGPTDomain(SERVER_URL),
      default: "fallback.example.com",
    },
  },
}

Without sunpeak, detect the host in your resources/read handler and return the appropriate string. The MCP initialize handshake includes clientInfo.name, which identifies the connecting host. If omitted, the host uses its default sandbox origin.

`prefersBorder` — Visual Boundary

boolean

Controls whether the host renders a visible border and background around the View.

Value	Behavior
`true`	Request visible border and background from the host
`false`	Request no visible border or background (seamless appearance)
omitted	Host decides — defaults vary by platform

_meta: { ui: { prefersBorder: false } }

Explicitly set prefersBorder rather than relying on the host default, since defaults vary between ChatGPT and Claude.

Complete Example

import { registerAppResource, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";

registerAppResource(
  server,
  "Music Player",
  "ui://music/player.html",
  {
    description: "Interactive music player",
    _meta: {
      ui: { prefersBorder: false },
    },
  },
  async () => ({
    contents: [
      {
        uri: "ui://music/player.html",
        mimeType: RESOURCE_MIME_TYPE,
        text: musicPlayerHtml,
        _meta: {
          ui: {
            csp: {
              connectDomains: ["https://api.spotify.com"],
              resourceDomains: ["https://i.scdn.co"],
            },
            permissions: { microphone: {} },
            prefersBorder: false,
          },
        },
      },
    ],
  }),
);

TypeScript Types

import type {
  McpUiResourceMeta,
  McpUiResourceCsp,
  McpUiResourcePermissions,
} from "@modelcontextprotocol/ext-apps";

interface McpUiResourceMeta {
  csp?: McpUiResourceCsp;
  permissions?: McpUiResourcePermissions;
  domain?: string;
  prefersBorder?: boolean;
}

interface McpUiResourceCsp {
  connectDomains?: string[];
  resourceDomains?: string[];
  frameDomains?: string[];
  baseUriDomains?: string[];
}

interface McpUiResourcePermissions {
  camera?: {};
  microphone?: {};
  geolocation?: {};
  clipboardWrite?: {};
}

In the sunpeak framework, resource metadata is co-located with resource components. See the Tool File Reference.

Overview

App

MCP

React

Server

Styling

Types

MCP App Resource _meta — CSP, Permissions, Domain & Border

Overview

Where to Set `_meta`

Fields

`csp` — Content Security Policy

`connectDomains`

`resourceDomains`

`frameDomains`

`baseUriDomains`

`permissions` — Sandbox Permissions

`domain` — Stable Sandbox Origin

Cross-platform servers

`prefersBorder` — Visual Boundary

Complete Example

TypeScript Types

​Overview

​Where to Set _meta

​Fields

​csp — Content Security Policy

​connectDomains

​resourceDomains

​frameDomains

​baseUriDomains

​permissions — Sandbox Permissions

​domain — Stable Sandbox Origin

​Cross-platform servers

​prefersBorder — Visual Boundary

​Complete Example

​TypeScript Types

Overview

Where to Set `_meta`

Fields

`csp` — Content Security Policy

`connectDomains`

`resourceDomains`

`frameDomains`

`baseUriDomains`

`permissions` — Sandbox Permissions

`domain` — Stable Sandbox Origin

Cross-platform servers

`prefersBorder` — Visual Boundary

Complete Example

TypeScript Types