将 MCP 应用添加到智能智能 Microsoft 365 Copilot 副驾驶® 副驾驶® 中的声明性代理

MCP 应用是在智能智能 Microsoft 365 Copilot 副驾驶® 副驾驶®内运行的交互式 UI 小组件，由模型上下文协议 (MCP) 服务器提供支持。它们允许声明性代理超越文本响应，直接在 Copilot 聊天中提供丰富的可操作体验。可以通过向代理添加基于 MCP 服务器的操作并扩展代理使用的 MCP 工具以包含 UI，将 MCP 应用添加到声明性代理。智能智能 Microsoft 365 Copilot 副驾驶® 副驾驶®支持使用以下方法创建的 UI 小组件。

MCP 应用 - MCP 的扩展，使 MCP 服务器能够向主机提供交互式用户界面。
OpenAI 应用 SDK - 基于 MCP 应用标准构建 ChatGPT 应用的工具，具有额外的 ChatGPT 功能。

有关 MCP 服务器插件示例，请参阅 GitHub 上智能智能 Microsoft 365 Copilot 副驾驶® 副驾驶®的基于 MCP 的交互式 UI 示例。

有关支持哪些 MCP 应用或 OpenAI 应用 SDK 功能的详细信息，请参阅 Copilot 中支持的 MCP 应用功能。

MCP 应用的先决条件

Copilot 扩展性选项的要求中指定的要求
提供 UI 小组件或可以修改以实现 UI 小组件的远程 MCP 服务器
用于查看 MCP 服务器响应的工具，例如 MCP 检查器
Visual Studio Code
Microsoft 365 代理工具包 (版本 6.6.1 或更高版本)

MCP 应用的 MCP 服务器要求

身份验证 - 支持 OAuth 2.1 和 Microsoft Entra 单一登录 (SSO) 。出于开发目的，支持匿名身份验证。有关身份验证的详细信息，请参阅在代理中为 API 插件配置身份验证。
允许的 URL - MCP 服务器和标识提供者应允许以下 URL。
- CORS 的小组件主机 URL - Copilot 在 MCP 服务器特定的主机下呈现小组件 UI，URL 如下： {hashed-mcp-domain}.widget-renderer.usercontent.microsoft.com，其中 {hashed-mcp-domain} 是 MCP 服务器域的 SHA-256 哈希。可以使用小组件主机 URL 生成器基于 MCP 服务器 URL 生成主机 URL。
- OAuth 2.1 重定向 URI：
  - https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect for Copilot
  - https://vscode.dev/redirectVisual Studio Code使用代理工具包提取工具
- Microsoft Entra SSO 重定向 URI：
  - https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect for Copilot
  - Visual Studio Code当前不支持用于提取工具的 SSO
UI 小组件 - 必须根据 MCP 应用或 OpenAI 应用 SDK 要求实现 UI 小组件。

Copilot 中 MCP 应用的最佳做法

用户体验设计

有关 UX 设计最佳做法的详细信息，请参阅适用于智能智能 Microsoft 365 Copilot 副驾驶® 副驾驶® 的声明性代理中的 MCP 应用的用户体验指南。

验证 API 可用性

window.openai.*并非所有 API 在每个平台或主机上都可用。不支持的 API 为 undefined。始终检查 API 可用性，并在 API 不可用时提供回退。

示例

这种简单的模式通过在调用 API 之前检查来避免运行时错误。

if (window.openai.callTool) {
  const result = await window.openai.callTool({ name: 'myTool', params: {} });
} else {
  // Handle unsupported case — show fallback UI, skip the feature, etc.
}

在此示例中，仅当主机支持 API 时，才会呈现进入全屏模式的 requestDisplayMode 按钮。

function FullScreenButton() {
  // Don't render the button if the host doesn't support it
  if (!window.openai.requestDisplayMode) {
    return null;
  }

  return (
    <button onClick={() => window.openai.requestDisplayMode({ mode: 'fullscreen' })}>
      Enter Fullscreen
    </button>
  );
}

或者，小组件可以检查启动时使用的所有 API 的可用性，并相应地启用/禁用功能。

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

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

// Use at widget startup
const capabilities = detectCapabilities();

if (!capabilities.canCallTools) {
  // Show a reduced-functionality experience
}

创建声明性代理

打开Visual Studio Code并选择左侧活动栏中的“Microsoft 365 代理工具包”图标。
在“代理工具包”任务窗格中 选择“创建新代理/应用 ”。
选择“ 声明性代理”。
选择“ 添加操作”，然后选择“ 使用 MCP 服务器启动”。如果出现提示，请选择 “远程 MCP 服务器”。
输入 MCP 服务器的 URL。
选择代理项目的位置。
输入代理的名称。

完成这些步骤后，Agents Toolkit 会为代理生成所需的文件，并打开一个新的Visual Studio Code窗口，其中加载了代理项目。

更新和旁加载代理

打开 .vscode/mcp.json 文件。在文件编辑器中选择“ 开始” 按钮。
在文件编辑器中选择 “ATK：从 MCP 提取操作 ”按钮，然后选择“ ai-plugin.json”。
选择代理要使用的工具，然后选择“ 确定”。请确保至少选择一个具有 UI 小组件的工具。
选择适用的身份验证类型。

重要

如果 MCP 服务器正在开发中，并且未实现身份验证，则跳过此步骤。将身份验证添加到服务器后，需要手动将身份验证添加到清单。
选择左侧活动栏中 的“Microsoft 365 代理工具包 ”图标。
在“ 帐户 ”窗格中，选择“ 登录到 Microsoft 365”。 (如果已登录，请继续执行下一步) 。
确认“ 已启用自定义应用上传” 和 “已启用 Copilot 访问” 显示在 Microsoft 365 帐户下。如果没有，请与组织管理员检查。有关详细信息，请参阅 Copilot 扩展性选项的要求。
在“ 生命周期 ”窗格中，选择“ 预配”。
如果出现提示，请添加身份验证详细信息。
等待工具包报告完成预配。

测试代理

打开浏览器并转到 https://m365.cloud.microsoft/chat。
在左侧边栏中选择代理。如果未看到代理，请选择“ 所有代理”。
要求代理执行调用 MCP 服务器的内容。
出现提示时，允许代理连接到 MCP 服务器。
代理呈现 UI 小组件。

如果小组件未按预期显示或行为不正常，请参阅排查智能智能 Microsoft 365 Copilot 副驾驶® 副驾驶®中的 MCP 应用问题。

Copilot 中支持的 MCP 应用功能

智能智能 Microsoft 365 Copilot 副驾驶® 副驾驶®支持以下功能。

组件网桥

OpenAI 应用 SDK	MCP 应用等效项	是否支持？
`window.openai.toolInput`	`app.ontoolinput`	✅
`window.openai.toolOutput`	`app.ontoolresult`	✅
`window.openai.toolResponseMetadata`	`app.ontoolresult` → `params._meta`	✅
`window.openai.widgetState`	—	✅
`window.openai.setWidgetState(state)`	不直接可用。使用替代机制，包括 `app.updateModelContext()`	✅
`window.openai.callTool(name, args)`	`app.callServerTool({ name, arguments })`	✅
`window.openai.sendFollowUpMessage({ prompt })`	`app.sendMessage({ ... })`	✅
`window.openai.uploadFile(file)`	—	❌
`window.openai.getFileDownloadUrl({ fileId })`	—	❌
`window.openai.requestDisplayMode(...)`	`app.requestDisplayMode({ mode })`	✅ 仅全屏 ()
`window.openai.requestModal(...)`	—	❌
`window.openai.notifyIntrinsicHeight(...)`	`app.sendSizeChanged({ width, height })`	✅
`window.openai.openExternal({ href })`	`app.openLink({ url })`	✅
`window.openai.setOpenInAppUrl({ href })`	—	✅
`window.openai.theme`	`app.getHostContext()?.theme`	✅
`window.openai.displayMode`	`app.getHostContext()?.displayMode`	✅
`window.openai.maxHeight`	`app.getHostContext()?.viewport?.maxHeight`	✅
`window.openai.safeArea`	`app.getHostContext()?.safeAreaInsets`	✅
`window.openai.view`	—	✅
`window.openai.userAgent`	`app.getHostContext()?.userAgent`	✅
`window.openai.locale`	`app.getHostContext()?.locale`	✅
—	`app.ontoolinputpartial`	❌
—	`app.ontoolcancelled`	❌
—	`app.getHostContext()?.availableDisplayModes`	❌
—	`app.getHostContext()?.toolInfo`	❌
—	`app.onhostcontextchanged`	❌
—	`app.onteardown`	❌
—	`app.sendLog({ level, data })`	❌
—	`app.getHostVersion()`	❌
—	`app.getHostCapabilities()`	✅

工具描述符_meta字段

OpenAI 应用 SDK	MCP 应用等效项	是否支持？
`_meta["openai/outputTemplate"]`	`_meta.ui.resourceUri`	✅
`_meta["openai/widgetAccessible"]`	`_meta.ui.visibility` (string[])	❌
`_meta["openai/visibility"]`	`_meta.ui.visibility` (string[])	✅
`_meta["openai/toolInvocation/invoking"]`	—	❌
`_meta["openai/toolInvocation/invoked"]`	—	❌
`_meta["openai/fileParams"]`	—	❌
`_meta["securitySchemes"]`	—	❌

工具描述符注释

OpenAI 应用 SDK	MCP 应用等效项	是否支持？
`readOnlyHint`	`readOnlyHint`	✅
`destructiveHint`	`destructiveHint`	❌
`openWorldHint`	`openWorldHint`	❌
`idempotentHint`	`idempotentHint`	❌

组件资源_meta域

OpenAI 应用 SDK	MCP 应用等效项	是否支持？
`_meta["openai/widgetDescription"]`	—	❌
`_meta["openai/widgetPrefersBorder"]`	`_meta.ui.prefersBorder`	❌
`_meta["openai/widgetCSP"]`	`_meta.ui.csp`	✅
`_meta["openai/widgetDomain"]`	`_meta.ui.domain`	❌
—	`_meta.ui.permissions`	❌

CSP 对象中的属性

OpenAI 应用 SDK	MCP 应用等效项	是否支持？
`connect_domains`	`connectDomains`	✅
`resource_domains`	`resourceDomains`	✅
`frame_domains`	`frameDomains`	❌
`redirect_domains`	—	❌
—	`baseUriDomains`	❌

主机提供的工具结果_meta字段

OpenAI 应用 SDK	MCP 应用等效项	是否支持？
`_meta["openai/widgetSessionId"]`	—	❌

客户端提供的_meta字段

OpenAI 应用 SDK	MCP 应用等效项	是否支持？
`_meta["openai/locale"]`	`_meta["openai/locale"]`	✅
`_meta["openai/userAgent"]`	`_meta["openai/userAgent"]`	✅
`_meta["openai/userLocation"]`	`_meta["openai/userLocation"]`	✅
`_meta["openai/subject"]`	—	❌

有关 Copilot 中 MCP 应用的常见问题

什么是 MCP 应用？

MCP 应用是由 MCP 服务器提供的交互式 UI 小组件，可直接在智能智能 Microsoft 365 Copilot 副驾驶® 副驾驶®内呈现。它们将声明性代理扩展到仅文本响应之外，从而提供丰富的体验，例如数据可视化效果、表单和任务管理界面。

MCP 应用和 OpenAI 应用 SDK 之间有何区别？

MCP 应用是 MCP 标准的开放扩展，使 MCP 服务器能够向任何兼容的主机提供交互式 UI。 OpenAI 应用 SDK 基于 MCP 应用标准构建，并添加了特定于 ChatGPT 的额外功能。智能智能 Microsoft 365 Copilot 副驾驶® 副驾驶®支持这两者，但并非所有功能都可用。有关详细信息，请参阅 Copilot 中支持的 MCP 应用功能。

是否可以在开发期间不使用身份验证使用 MCP 应用？

是。出于开发目的，支持匿名身份验证。但是，在部署到生产环境之前，需要添加身份验证。 OAuth 2.1 和 Microsoft Entra 单一登录 (SSO) 是支持的身份验证方法。有关详细信息，请参阅在代理中为 API 插件配置身份验证。

反馈

此页面是否有帮助？

Last updated on 2026-05-13