Microsoft 365 Copilot 外掛程式可將支援的Microsoft體驗連線至遠端模型內容通訊協定 (MCP) 伺服器所提供的工具。 外掛程式套件包含連線配置,伺服器單獨執行。
使用 Work IQ 開發工具 (WIQD) 來建立、驗證及封裝您的外掛程式。 從 使用 Work IQ 開發工具建置外掛程式開始。
下列各節為需要手動編輯資訊清單的開發人員說明基礎設定。 在 Microsoft 365 應用程式資訊清單的陣列中 agentConnectors 註冊外掛程式的遠端 MCP 伺服器。 即使可安裝套件稱為外掛程式,此結構描述識別碼仍會保留 agentConnectors 。
重要
此設定使用 Microsoft 365 應用程式資訊清單,而不是用於宣告式代理程式動作的 MCP 外掛程式資訊清單。 它也與代理程式 365 CLI 註冊路由分開。 如需這些替代方案,請參閱 建置或重複使用 MCP 伺服器。 僅支援 MCP 並無法為此註冊模型建立支援。
先決條件
開始之前,請確定您已:
- 支援透過設定
agentConnectors外掛程式的測試租用戶和目標 Microsoft 體驗。 - 運作中的 MCP 伺服器,具有可公開存取的 HTTPS 端點、TLS 1.2 或更新版本,以及目標體驗所支援的傳輸。
- Microsoft 365 應用程式套件,其資訊清單版本受目標體驗和您選擇的授權類型支援。
- 為伺服器登錄的授權設定,例如 OAuth 設定 或 API 金鑰設定,除非伺服器允許匿名存取。
如需 WIQD 伺服器需求和 Copilot Cowork 工具描述需求,請參閱 Work IQ 開發工具。
將 MCP 伺服器新增至您的應用程式資訊清單
在應用程式資訊清單根層級的 agentConnectors 陣列中宣告您的 MCP 伺服器。
- 開啟 Microsoft 365 應用程式套件中的應用程式資訊清單。
- 找出或建立根層級
agentConnectors陣列。 - 新增具有唯一
id、 adisplayName、 adescription及 atoolSource的項目,以識別您的遠端 MCP 伺服器。
下列 JSON 是要合併到現有應用程式資訊清單中的片段,而不是完整的應用程式資訊清單:
{
"$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.30/MicrosoftTeams.schema.json",
"manifestVersion": "1.30",
"agentConnectors": [
{
"id": "my-mcp-server",
"displayName": "My Automation Server",
"description": "Provides workflow automation and task management tools.",
"toolSource": {
"remoteMcpServer": {
"mcpServerUrl": "https://mcp.example.com/mcp",
"authorization": {
"type": "OAuthPluginVault",
"referenceId": "my-oauth-config"
},
"mcpToolDescription": {
"file": "toolDescription.json"
}
}
}
}
]
}
將端點和授權參照取代為您的伺服器值。 每個項目都idagentConnectors必須是唯一的。 將其他必要的應用程式資訊清單屬性保留在現有檔案中。
設定伺服器端點
將 toolSource.remoteMcpServer.mcpServerUrl 設定為 HTTPS 端點。 確認伺服器可從目標體驗連線,並回應 MCP 初始化和後續通訊協定要求。
設定驗證
設定在 之內agentConnectors[].toolSource.remoteMcpServer。authorization 下表列出授權類型及其設定。 如需結構描述詳細資訊,請參閱 授權結構描述。
| 授權類型 | 設定 |
|---|---|
None |
不需驗證。 只有在伺服器允許匿名存取時才使用。 |
OAuthPluginVault |
OAuth 設定會儲存在 Microsoft 保存庫中,並由識別碼參考。 |
ApiKeyPluginVault |
儲存在保存庫中並由識別碼參照的 API 金鑰設定。 |
DynamicClientRegistration |
識別碼參考的動態 OAuth 用戶端註冊設定。 |
AzureKeyVault |
識別碼參考的 Azure Key Vault 設定。 需要主機支援。 |
ConnectionVault (開發人員預覽) |
識別碼參考的連線設定。 |
結構描述值無法保證目標體驗中的支援。 選擇方法之前,請先檢查其驗證需求。
識別 referenceId 從資訊清單中分開取得的設定。 請勿將 API 金鑰、存取權杖、用戶端密碼或密碼值放在此欄位或應用程式資訊清單的其他位置。
使用 OAuth 驗證
針對儲存在 Microsoft 保存庫中的 OAuth 2.0 權杖,請使用下列 authorization 物件:
{
"type": "OAuthPluginVault",
"referenceId": "my-oauth-config"
}
在 開發者入口網站 中登錄 OAuth 設定,並將傳回的設定 ID 用作 referenceId。 如需詳細資訊,請參閱 在開發者入口網站中設定 OAuth。
將下列回呼 URL 新增至 OAuth 提供者註冊中允許的重新導向 URI:
https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect
使用 API 金鑰驗證
對於儲存在保存庫中的 API 金鑰,請使用下列 authorization 物件:
{
"type": "ApiKeyPluginVault",
"referenceId": "my-apikey"
}
在 開發者入口網站中註冊金鑰,然後以 my-apikey 傳回的註冊識別碼取代。 如需詳細資料,請參閱 API 金鑰驗證。
使用動態用戶端註冊
動態用戶端登錄可讓主機使用 RFC 7591 向 MCP 伺服器註冊為 OAuth 用戶端。 兩者都必須支援註冊流程。 Microsoft Entra ID 不提供 RFC 7591 註冊端點;對受 Entra 保護的伺服器使用靜態 OAuth 註冊。
使用下列 authorization 物件:
{
"type": "DynamicClientRegistration",
"referenceId": "my-dcr-config"
}
在 開發人員入口網站 中登錄組態,並以其參考 ID 取代 my-dcr-config 。 組態提供主機在交涉用戶端認證時所使用的授權值。
您的伺服器必須:
- 公開 RFC 7591 用戶端註冊端點。
- 傳回主機的 OAuth 流程所需的用戶端註冊資訊。
- 在需要長時間工作階段時支援權杖重新整理。
使用 Azure Key Vault 驗證
AzureKeyVault 包含在應用程式資訊清單結構描述 1.29 和 1.30 中。 只有在目標體驗記錄 Azure Key Vault 整合,以及取得設定參考的程序時才使用它。
使用下列 authorization 物件:
{
"type": "AzureKeyVault",
"referenceId": "my-keyvault-config"
}
遵循該整合的認證儲存和存取需求,並以 my-keyvault-config 傳回的參照取代。 僅憑資訊清單宣告不會授與對密碼的存取權。
使用連線保存庫驗證
注意
連線保存庫驗證在開發人員預覽中提供。 使用開發人員預覽應用程式資訊清單結構描述進行設定 ConnectionVault; 它不適用於一般可用的應用程式資訊清單結構描述。
如需支援的連線保存庫整合,請使用下列 authorization 物件:
{
"type": "ConnectionVault",
"referenceId": "shared_example"
}
shared_example取代為目標整合提供的連線參照。
不使用驗證
如果您的伺服器允許匿名存取,請在主機允許時設定authorization.typeNone或省略authorization。
針對生產和企業案例偏好已驗證的存取權,以及在支援的情況下優先使用 API 金鑰之上的 OAuth。
定義工具探索
當工具集已修正時使用封裝工具定義,或在應用程式資訊清單版本和目標主機都支援時使用動態探索。
使用靜態工具定義
在您的應用程式套件中包含工具描述檔案,並在 中引用它。remoteMcpServer 路徑是相對於應用程式套件的路徑。 使用伺服器 tools/list 結果中的工具定義,包括每個工具的名稱、描述和輸入結構描述。 例如,最小 toolDescription.json 的檔案可以包含:
{
"mcpToolDescription": {
"file": "toolDescription.json"
}
}
{
"tools": [
{
"name": "get_task",
"description": "Gets a task by its identifier.",
"inputSchema": {
"type": "object",
"properties": {
"taskId": {
"type": "string",
"description": "The identifier of the task."
}
},
"required": [
"taskId"
]
}
}
]
}
讓套件定義與伺服器保持一致。
使用動態工具探索
動態探索可讓主機在執行階段 tools/list 擷取工具清單,而不是依賴封裝的定義。
應用程式資訊清單版本 1.29 或更新版本允許您省略 mcpToolDescription。 舊版需要此檔案。 即使已是 1.29 版或更新版本,Copilot Cowork 仍然需要工具描述檔案。 使用 WIQD,請透過 --tool-description; 請參閱 Work IQ 開發工具來提供。
對於支援動態探索的目標體驗,請省略 mcpToolDescription ,以便透過 擷取定義 tools/list。 傳回工具名稱、描述和輸入結構描述,並測試如何重新整理對工具集的變更。
驗證並測試您的外掛程式
在部署之前驗證套件,然後在目標體驗中進行測試:
- 根據其宣告的結構描述驗證完整的應用程式資訊清單,並在開發人員入口網站中使用 應用程式套件驗證 。
- 確認端點回應 MCP 初始化,以及封裝檔案或
tools/list提供有效的工具定義。 - 透過目標體驗支援的程序,將套件部署到您的測試租用戶。 完成任何必要的管理員核准或存取設定。 部署不會取代使用者登入、同意或來源服務的權限。
- 測試伺服器公開作業的提示,例如「搜尋指派給我的未解決問題」,或對於具有寫入工具的伺服器,「更新票證號碼 123 的狀態」。
- 確認預期的工具可用、同意提示會在需要時出現,工具呼叫會傳回預期的結果。 如果適用,請測試 OAuth 權杖重新整理。
- 檢查無效輸入、無法使用服務、授權錯誤和逾時的失敗,包括重試行為。
- 如果您的案例需要多租用戶支援,請跨租用戶進行測試。
常見問題疑難排解
| 問題 | 支票 |
|---|---|
| 無法連線到伺服器 | 端點協助工具、HTTPS、傳輸支援、防火牆設定和 MCP 初始化。 |
| 工具未出現 | 封裝檔案路徑和有效定義,或支援具有 mcpToolDescription 省略和有效 tools/list. |
| 驗證失敗 | Registered referenceId、認證有效性、權限、同意和輸出授權標頭。 |
| 工具呼叫失敗或逾時 | 伺服器記錄、輸入驗證、MCP 回應格式、並行、逾時和重試。 |