MCP App CSP Domains: connectDomains vs resourceDomains vs frameDomains

TL;DR: MCP App resources run in sandboxed iframes with no external access by default. Use connectDomains for API calls (fetch, WebSocket), resourceDomains for static assets (images, fonts, scripts), and frameDomains for nested iframes (embeds). All three go in _meta.ui.csp on your resource config.

---

The Three CSP Domain Types

Every MCP App resource runs in a sandboxed iframe. The iframe gets a Content Security Policy (CSP) that blocks all external connections and resource loading by default. You open up access by declaring specific origins in _meta.ui.csp.

There are three domain arrays you’ll use, and they control different things:

connectDomains (runtime network requests)

Maps to the CSP connect-src directive. Controls:

• fetch() calls
• XMLHttpRequest
• WebSocket connections

Use this when your resource component calls an API at runtime. If your component calls fetch('https://api.example.com/data'), you need https://api.example.com in connectDomains.

resourceDomains (static asset loading)

Maps to the CSP img-src, script-src, style-src, font-src, and media-src directives. Controls:

• <img src="..."> tags and CSS background-image URLs
• <script src="..."> tags
• <link rel="stylesheet" href="..."> tags
• @font-face URLs
• <video> and <audio> sources

Use this when your resource loads assets from external CDNs. If your component renders <img src="https://cdn.example.com/photo.jpg" />, you need https://cdn.example.com in resourceDomains.

frameDomains (nested iframes)

Maps to the CSP frame-src directive. Controls:

• <iframe src="..."> tags inside your resource

Use this when your resource embeds third-party content like YouTube players, Google Maps, or any iframe-based widget. Without it, nested iframes are blocked entirely.

Quick Reference

I need to…	Use	CSP directive
Call an API with fetch()	connectDomains	connect-src
Open a WebSocket	connectDomains	connect-src
Load images from a CDN	resourceDomains	img-src
Load fonts from Google Fonts	resourceDomains	font-src
Load a script from a CDN	resourceDomains	script-src
Embed a YouTube video	frameDomains	frame-src
Embed Google Maps	frameDomains	frame-src

There is also baseUriDomains (maps to base-uri), but most apps never need it.

Common Patterns

API-only resource

Your resource fetches data from a backend. No external images or embeds.

export const resource: ResourceConfig = {
  description: 'Live usage dashboard',
  _meta: {
    ui: {
      csp: {
        connectDomains: ['https://api.example.com'],
      },
    },
  },
};

Resource with CDN images

Your resource renders images hosted on an external CDN. No runtime API calls.

export const resource: ResourceConfig = {
  description: 'Photo gallery',
  _meta: {
    ui: {
      csp: {
        resourceDomains: ['https://cdn.example.com'],
      },
    },
  },
};

Map resource (needs both)

Mapbox (and similar map services) serve both API responses and tile images from the same origins. You need both connectDomains and resourceDomains:

export const resource: ResourceConfig = {
  description: 'Map view',
  _meta: {
    ui: {
      csp: {
        connectDomains: ['https://api.mapbox.com', 'https://events.mapbox.com'],
        resourceDomains: ['https://api.mapbox.com', 'https://events.mapbox.com'],
      },
    },
  },
};

Embedded video

Your resource embeds a YouTube player inside a nested iframe:

export const resource: ResourceConfig = {
  description: 'Video player',
  _meta: {
    ui: {
      csp: {
        frameDomains: ['https://www.youtube.com'],
        resourceDomains: ['https://img.youtube.com'], // thumbnail images
      },
    },
  },
};

Everything at once

A music player resource that calls an API, loads album art from a CDN, and embeds an audio player widget:

export const resource: ResourceConfig = {
  description: 'Music player',
  _meta: {
    ui: {
      csp: {
        connectDomains: ['https://api.spotify.com'],
        resourceDomains: ['https://i.scdn.co', 'https://fonts.googleapis.com'],
        frameDomains: ['https://open.spotify.com'],
      },
    },
  },
};

Why fetch() Fails by Default

If you write this in a resource without declaring connectDomains:

useEffect(() => {
  fetch('https://api.example.com/data')
    .then(r => r.json())
    .then(setData);
}, []);

The browser blocks the request before it leaves the iframe and logs a CSP violation in the console. The code itself is fine. The CSP just doesn’t include that origin.

The same applies to images. This won’t render without resourceDomains:

<img src="https://cdn.example.com/photo.jpg" />

And this won’t load without frameDomains:

<iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ" />

The fix is always the same: add the origin to the right domain array.

Wildcard Subdomains

You can use wildcard subdomains to allow all subdomains of a domain:

connectDomains: ['https://*.example.com']

This allows https://api.example.com, https://cdn.example.com, https://v2.api.example.com, etc.

A bare * (all origins) is rejected. CSP keywords like 'unsafe-inline', 'unsafe-eval', and 'none' are also rejected. Declare explicit origins or wildcard-subdomain patterns only.

CSP in Development

sunpeak automatically adds localhost origins to your CSP when you run sunpeak dev:

• http://localhost:<port> into resourceDomains (for bundled JS and CSS from Vite)
• http://localhost:<port> and ws://localhost:<hmr-port> into connectDomains (for Vite HMR)

You don’t need to add these manually. Your declared domains are merged with the injected localhost entries.

CSP vs CORS

CSP and CORS solve different problems:

CSP is on the browser side. It controls whether the browser allows your iframe to make the request at all. You configure it with connectDomains in your resource metadata.

CORS is on the API server side. It controls whether the server accepts requests from your app’s origin. The API server configures this with Access-Control-Allow-Origin headers.

You need both for a fetch() call to work. CSP lets the request leave the iframe. CORS lets the server accept it.

Public APIs that respond with Access-Control-Allow-Origin: * work without any CORS configuration on your end. Just add the origin to connectDomains and the request works.

For APIs that allowlist specific origins, you need your MCP App to have a stable origin. By default, MCP App iframes have ephemeral origins (srcdoc or blob: URLs). Set _meta.ui.domain to assign a stable one.

The catch: the domain format is host-specific. Each host assigns sandbox origins differently, so a cross-platform server must compute the right value per host:

Host	Domain format	Example
Claude	SHA-256 hash of MCP server URL	a904794854a047f6.claudemcpcontent.com
ChatGPT	URL-derived subdomain	www-example-com.oaiusercontent.com

For most apps, this isn’t something you need to worry about. Public APIs with Access-Control-Allow-Origin: * (or APIs secured with API keys rather than origin allowlists) work with just connectDomains and no domain at all. You only need domain when your API server checks the Origin header and rejects unknown origins.

See the CSP & CORS docs and Resource Metadata reference for the full computation and per-host formats.

Passing Auth Tokens to fetch()

The sandboxed iframe has no access to localStorage, sessionStorage, or cookies. Pass tokens through tool output instead:

// src/tools/get-dashboard.ts
export default async function (args: Args, _extra: ToolHandlerExtra) {
  const token = process.env.INTERNAL_API_TOKEN;
  return {
    structuredContent: {
      userId: args.userId,
      apiToken: token,
    },
  };
}

// src/resources/dashboard/dashboard.tsx
export function DashboardResource() {
  const { output } = useToolData<unknown, { userId: string; apiToken: string }>(undefined, undefined);
  const [data, setData] = useState(null);

  useEffect(() => {
    if (!output) return;
    fetch(`https://api.example.com/usage/${output.userId}`, {
      headers: { Authorization: `Bearer ${output.apiToken}` },
    })
      .then(r => r.json())
      .then(setData);
  }, [output?.userId]);

  // render...
}

The token travels from the server to the resource only when the tool runs, inside the structured content envelope.

Testing fetch() Calls

In Playwright e2e tests, use page.route() to intercept external API calls so tests stay deterministic:

import { test, expect } from '@playwright/test';
import { createInspectorUrl } from 'sunpeak/inspector';

test('dashboard fetches and displays usage data', async ({ page }) => {
  await page.route('https://api.example.com/usage/user_123', route =>
    route.fulfill({
      status: 200,
      body: JSON.stringify({ requests: 412, credits: 3.20 }),
    })
  );

  await page.goto(createInspectorUrl({ simulation: 'get-dashboard', host: 'chatgpt' }));
  const iframe = page.frameLocator('iframe');
  await expect(iframe.locator('text=412')).toBeVisible();
});

No real API calls, no AI credits. Run pnpm test:e2e to execute against the local inspector.