Copilot Widget Protocol

Language-agnostic protocol requirements for MCP servers that render widgets in Microsoft 365 Copilot Chat. This document describes what your server must implement, regardless of programming language. For a complete TypeScript reference implementation, see mcp-server-pattern.md.

Table of Contents

• Transport: Streamable HTTP
• CORS Configuration
• Server Capabilities
• MCP Resources for Widgets
• MCP Tool Response Format
• Widget Shell and Asset Serving
• Widget-Resource-Tool Triplet
• Environment Configuration
• Adaptation Checklist: Existing MCP Server
• Language SDK References

Transport: Streamable HTTP

Your server must expose a single /mcp endpoint that handles three HTTP methods:

Method	Purpose	Key Headers
POST /mcp	Send JSON-RPC messages (initialize, tool calls, resource reads)	Content-Type: application/json, mcp-session-id (after init)
GET /mcp	Open SSE stream for server-to-client notifications	mcp-session-id (required)
DELETE /mcp	Terminate a session	mcp-session-id (required)

Session lifecycle:

1. Client sends POST /mcp with an initialize request (no mcp-session-id header)
2. Server generates a session ID and returns it in the mcp-session-id response header
3. All subsequent requests include the mcp-session-id header

Initialize request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": { "name": "copilot", "version": "1.0.0" }
  }
}

Initialize response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": { "resources": {}, "tools": {} },
    "serverInfo": { "name": "my-server", "version": "1.0.0" }
  }
}

CORS Configuration

The /mcp endpoint must handle CORS for cross-origin requests from Copilot. Use origin-checking rather than a blanket wildcard — validate the request's Origin header against an allowlist and reflect the origin back if it matches.

Required allowed origins (at minimum):

• m365.cloud.microsoft — the base Copilot Chat domain
• *.m365.cloud.microsoft — any subdomain (e.g., copilot.m365.cloud.microsoft)

Preflight (OPTIONS /mcp):