Shipping to Microsoft 365 Copilot

Copilot renders MCP apps as interactive widgets inside declarative agents. You attach an MCP server-based plugin whose tools return UI. Copilot supports both MCP Apps and the OpenAI Apps SDK, with the coverage documented in host-capability-matrix.

Prerequisites

• A remote MCP server (local stdio is not an option here).
• Visual Studio Code.
• Microsoft 365 Agents Toolkit 6.12.0 or later.
• MCP Inspector for verifying server responses before wiring Copilot up.
• The general Copilot extensibility requirements (tenant, licensing).

Allowed URLs — the step everyone misses

Both your MCP server and your identity provider must allowlist these.

Widget host URL (CORS)

Copilot renders widget UI under a server-specific host:

{hashed-mcp-domain}.widget-renderer.usercontent.microsoft.com

where {hashed-mcp-domain} is the SHA-256 hash of your MCP server's domain. Generate it with the Widget Host URL Generator at https://aka.ms/mcpwidgeturlgenerator, then add the result to your server's CORS allowlist.

Skip this and the symptom is a widget that works perfectly in the basic-host and renders blank in Copilot with no useful error.

OAuth 2.1 redirect URIs

https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect     ← Copilot
https://vscode.dev/redirect                                     ← VS Code / Agents Toolkit tool fetch

Microsoft Entra SSO redirect URIs

https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect

VS Code does not currently support SSO for fetching tools — use OAuth 2.1 or anonymous during development, then switch.

Authentication

Anonymous must be removed before deployment. It is a development affordance, not a shipping configuration.

Building and sideloading

Creating a declarative agent from an MCP server, configuring auth, and sideloading are identical whether or not the server returns UI. Follow the standard "build a plugin for a declarative agent from an MCP server" flow, with three MCP-apps-specific notes:

1. The server must return UI resources per the MCP Apps or Apps SDK requirements.
2. Dynamic tool discovery is the default — the agent resolves your tools, including UI tools, at runtime. You do not need to enumerate them.
3. If you pin a fixed tool set instead, include at least one tool that returns a UI widget, or nothing will ever render.

Test

1. Go to https://m365.cloud.microsoft/chat.
2. Select your agent in the sidebar (All agents if it is not pinned).
3. Ask something that invokes your server.
4. Allow the connection when prompted.
5. Confirm the widget renders.

Design around Copilot's gaps

From the support matrix, the constraints that change design rather than just code:

setWidgetState is supported, so remount survival works. getHostCapabilities() is supported, so probe it at startup rather than assuming this table is current.

Verify API availability — Microsoft's own guidance

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

function FullScreenButton() {
  if (!window.openai.requestDisplayMode) return null;   // don't render what won't work
  return (
    <button onClick={() => window.openai.requestDisplayMode({ mode: "fullscreen" })}>
      Enter Fullscreen
    </button>
  );
}

Startup probe:

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

function detectCapabilities(): PlatformCapabilities {
  return {
    canCallTools: !!window.openai.callTool,
    canChangeDisplayMode: !!window.openai.requestDisplayMode,
    canSendMessages: !!window.openai.sendMessage,
  };
}

Reference samples

Microsoft publishes microsoft/mcp-interactiveUI-samples — pattern-focused samples in mcp-apps/ (Node.js and Python) and oai-apps-sdk/ (Node.js), covering expense submission with Graph + Entra SSO, field service dispatch with maps, bulk approvals, HR consultant dashboards in Fluent UI v9, insurance claims, training recommendations with embedded video, and Python LOB integrations for Salesforce, ServiceNow, and HubSpot. Fluent UI v9, FastMCP, and Azure Container Apps deployment are the recurring stack.

Pre-ship checklist

• Server reachable over HTTPS at a stable URL
• Widget host URL generated and added to CORS
• OAuth 2.1 redirect URIs registered (Copilot + VS Code)
• Entra SSO consent redirect registered, if using SSO
• Anonymous auth removed
• At least one tool returns a UI widget (if tools are pinned)
• No dependency on any ❌ row above
• Widget renders and functions at m365.cloud.microsoft/chat
• Text-only fallback verified — the workflow completes without the widget

Related

• host-capability-matrix — the full support tables.
• mcp-apps-protocol — the standard being implemented.
• ui-testing-harness — the local loop before you reach Copilot.