Host Capability Matrix

Host capability matrix

Every host implements a subset. An API that exists in ChatGPT may be undefined in M365 Copilot and absent in a custom host. Unsupported APIs are undefined, not throwing — so a missing guard produces a silent dead button, not an error you will notice in testing.

The tables below are the published Microsoft 365 Copilot support matrix, which is the most complete public statement of any host's coverage. Treat ChatGPT as full support for the window.openai column (it defines it) and Claude as full support for the MCP Apps column. Verify at runtime regardless.

Component bridge

The four ❌ rows that hurt most in practice:

• onteardown unsupported → you get no flush signal. Persist on every meaningful change rather than at unmount.
• onhostcontextchanged unsupported → theme changes mid-session will not reach you. Read theme once at init and accept the staleness, or use CSS prefers-color-scheme as a backstop.
• ontoolinputpartial unsupported → no streaming skeleton. Design the loading state around ontoolinput only.
• sendLog unsupported → fall back to console plus a visible debug pane behind a query flag.

Tool descriptor _meta

Tool descriptor annotations

Only readOnlyHint is honored. Do not rely on destructiveHint to produce a confirmation prompt — build the confirmation into your own UI.

Component resource _meta

CSP object properties

Nested iframes are not available in Copilot at all. If your design embeds a third-party frame (a map, a video player), it will not render there — inline the capability or degrade to a link.

Host-provided tool result _meta

Client-provided _meta

Feature detection patterns

Minimal guard:

if (window.openai?.callTool) {
  const result = await window.openai.callTool({ name: "myTool", params: {} });
} else {
  // fallback UI
}

Conditional affordance — never render a control the host cannot honor:

function FullScreenButton() {
  if (!window.openai?.requestDisplayMode) return null;
  return (
    <button => window.openai.requestDisplayMode({ mode: "fullscreen" })}>
      Enter Fullscreen
    </button>
  );
}

Startup capability probe — the pattern to prefer for anything non-trivial:

interface PlatformCapabilities {
  canCallTools: boolean;
  canChangeDisplayMode: boolean;
  canSendMessages: boolean;
  canPersistState: boolean;
}

function detectCapabilities(): PlatformCapabilities {
  const o = typeof window !== "undefined" ? window.openai : undefined;
  return {
    canCallTools: !!o?.callTool,
    canChangeDisplayMode: !!o?.requestDisplayMode,
    canSendMessages: !!o?.sendMessage,
    canPersistState: !!o?.setWidgetState,
  };
}

const caps = detectCapabilities();
if (!caps.canCallTools) renderReducedFunctionality();

On the MCP Apps side, ask the host directly:

const caps = await app.getHostCapabilities();
const modes = app.getHostContext()?.availableDisplayModes ?? ["inline"];

availableDisplayModes is itself unsupported in Copilot, so the ?? ["inline"] default is doing real work.

Rules

1. Never branch on host name or user agent. Test for the capability.
2. Never render an affordance whose API is missing — hide it.
3. Every host API call needs a defined fallback path, not a try/catch that swallows.
4. Re-verify this matrix against the vendor docs before shipping; host coverage moves.

Related

• openai-apps-sdk — what each window.openai API does.
• mcp-apps-protocol — the standard equivalents.
• m365-copilot-packaging — Copilot's other requirements (CORS, redirect URIs).