diff --git a/msteams-platform/m365-apps/agent-connectors.md b/msteams-platform/m365-apps/agent-connectors.md index 27c14f5e750..93e15acc854 100644 --- a/msteams-platform/m365-apps/agent-connectors.md +++ b/msteams-platform/m365-apps/agent-connectors.md @@ -1,85 +1,83 @@ --- title: Register MCP Servers as Agent Connectors for Microsoft 365 -description: Register your MCP server in the Microsoft 365 app manifest to enable access to your tools from agents like the Channel Agent in Teams. +description: Register your MCP server in the Microsoft 365 app manifest to enable access to your tools from agents in Teams. #customer intent: As a developer, I want to register my MCP server as an agent connector so that Microsoft 365 agents can access my external tools and services. -ms.date: 01/28/2026 +ms.date: 04/24/2026 ms.topic: how-to ms.subservice: m365apps --- -# Register MCP servers as agent connectors for Microsoft 365 (preview) - -Agents in Microsoft 365, such as [Channel Agent](/microsoftteams/set-up-channel-agent-teams) in Microsoft Teams, can connect to external systems through *agent connectors* declared in the app manifest. This article shows you how to register your remote Model Context Protocol (MCP) server in the Microsoft 365 app manifest, enabling Microsoft 365 agents to securely discover, select, and invoke MCP tools that your server exposes. +# Register MCP servers as agent connectors for Microsoft 365 +Agents in Microsoft 365 can connect to external systems through *agent connectors* declared in the app manifest. This article shows you how to register your remote Model Context Protocol (MCP) server in the Microsoft 365 app manifest, enabling Microsoft 365 agents to securely discover, select, and invoke MCP tools that your server exposes. + Microsoft 365 agents use agent connectors to communicate with external systems. For MCP servers, the connector provides: - The network endpoint of your MCP server - Authentication and authorization configuration -- Tool definitions (inline or dynamically discovered) +- Tool definitions - Optional metadata that helps agents orchestrate the right tool during user interactions -Once registered, your MCP server becomes available to any Microsoft 365 agent capable of using MCP, including the Channel Agent in Microsoft Teams. +Once registered, your MCP server becomes available to any Microsoft 365 agent capable of using MCP. ## Prerequisites Before you begin, ensure you have: -- A test tenant [enabled with Teams public preview](/microsoftteams/public-preview-doc-updates) features (for testing your MCP integration with Teams Channel Agent) +- A test tenant to validate your MCP integration - A working MCP server with a secure public endpoint -- Authentication credentials (OAuth configuration or API key) +- Authentication credentials ([OAuth configuration](../messaging-extensions/api-based-oauth.md#configure-oauth-in-developer-portal) or [API key](../messaging-extensions/api-based-secret-service-auth.md#api-key-authentication)) ## Add the agent connector to your manifest -First, declare your MCP server in the [agentConnectors](/microsoft-365/extensibility/schema/root-agent-connectors?view=m365-app-prev&preserve-view=true) array at the root level of your app manifest. +First, declare your MCP server in the [agentConnectors](/microsoft-365/extensibility/schema/root-agent-connectors) array at the root level of your app manifest. 1. Open your Microsoft 365 app manifest (`manifest.json`) file. 2. Locate or create the root-level `agentConnectors` array. -3. Add a new connector object with a unique `id`, display name, and description: +3. Add a new connector object with a unique `id`, `displayName`, and `description`: ````json { - "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json", - "manifestVersion": "devPreview", + "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.27/MicrosoftTeams.schema.json", + "manifestVersion": "1.27", ... - "agentConnectors": [ - { - "id": "my-mcp-server", - "displayName": "My Automation Server", - "description": "Provides workflow automation and task management tools.", - "toolSource": { - "remoteMcpServer": { - "mcpServerUrl": "https://mcp.mycompany.com" - } + "agentConnectors": [ + { + "id": "my-mcp-server", + "displayName": "My Automation Server", + "description": "Provides workflow automation and task management tools.", + "toolSource": { + "remoteMcpServer": { + "mcpServerUrl": "https://mcp.example.com" } } - ] - } + } + ] } ```` -Each connector must have a unique `id` that distinguishes it from other connectors in your manifest. The `toolSource` object must include exactly one of `remoteMcpServer`, `localMcpServer`, or `plugin`. - -For MCP servers, use **remoteMcpServer** unless your server runs locally within the Teams client environment (advanced scenarios). +Each connector must have a unique `id` that distinguishes it from other connectors in your manifest. ## Configure the remote MCP server endpoint Define how Microsoft 365 connects to your MCP server using the `remoteMcpServer` object. -1. Within your connector's [toolSource](/microsoft-365/extensibility/schema/root-agent-connectors-tool-source?view=m365-app-prev&preserve-view=true), specify the `remoteMcpServer` endpoint: +1. Within your connector's [toolSource](/microsoft-365/extensibility/schema/root-agent-connectors-tool-source), specify the `remoteMcpServer` endpoint: -````json -"toolSource": { - "remoteMcpServer": { - "mcpServerUrl": "https://mcp.mycompany.com" - } -} -```` + ````json + "toolSource": { + "remoteMcpServer": { + "mcpServerUrl": "https://mcp.example.com" + } + } + ```` 2. Ensure your endpoint uses HTTPS (for HTTP connections) or WSS (for WebSocket connections). @@ -91,10 +89,8 @@ Specify how Microsoft 365 retrieves credentials when calling your MCP server. Th - **None**: No authentication required - **OAuthPluginVault**: OAuth 2.0 tokens stored inside Microsoft’s secure vault - +- **DynamicClientRegistration**: Dynamic OAuth client registration ### Use OAuth authentication @@ -102,7 +98,7 @@ For OAuth 2.0 tokens stored in Microsoft's secure vault, specify authorization t ````json "remoteMcpServer": { - "mcpServerUrl": "https://mcp.mycompany.com", + "mcpServerUrl": "https://mcp.example.com", "authorization": { "type": "OAuthPluginVault", "referenceId": "my-oauth-config" @@ -114,7 +110,6 @@ The `referenceId` points to a secure [OAuth configuration that you register in D When setting up your OAuth app with a third-party authentication provider, ensure that you add `https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect` to the list of allowed redirect endpoints. - ### Use no authentication @@ -137,11 +131,8 @@ For enterprise scenarios, prefer OAuth over API keys to align with security best ## Define tool discovery -Choose how Microsoft 365 agents discover the tools your MCP server provides. Currently only inline tool definitions are supported. - -You can use inline definitions if your toolset is static, or dynamic discovery if your toolset changes frequently. - - +Configure how Microsoft 365 agents discover the tools your MCP server provides. + -### Use inline tool definitions - For static toolsets that don't change frequently, add an `mcpToolDescription` object with your tool definitions: ````json "remoteMcpServer": { - "mcpServerUrl": "https://mcp.mycompany.com", + "mcpServerUrl": "https://mcp.example.com", "authorization": { "type": "ApiKeyPluginVault", "referenceId": "my-apikey" }, "mcpToolDescription": { "description": { - // Tool definitions following MCP protocol schema + "file": "toolDescription.json" } } } @@ -173,14 +161,14 @@ For static toolsets that don't change frequently, add an `mcpToolDescription` ob The `description` object must match the schema returned by your MCP server's `tools/list` response. -## Example schema + ## Validate your configuration -Before deploying your app, verify that your manifest and MCP server are correctly configured. +Before deploying your agent or app, verify that your manifest and MCP server are correctly configured. 1. Use the [Microsoft 365 app package validation](https://dev.teams.microsoft.com/tools/store-validation) tool in Developer Portal to check your manifest for errors. -2. Verify your MCP server responds correctly to handshake messages by testing the connection manually. +2. Verify if your MCP server responds correctly to handshake messages by testing the connection manually. 3. Confirm that your `tools/list` endpoint returns schema-compliant tool definitions: @@ -260,9 +248,9 @@ Before deploying your app, verify that your manifest and MCP server are correctl Validate your integration by testing with actual Microsoft 365 agents. -1. Deploy your app to a test environment. +1. Deploy your agent or app to a test environment. -2. Open a [Channel Agent](/microsoftteams/set-up-channel-agent-teams) in Microsoft Teams or another Microsoft 365 agent that supports MCP. +2. Open a Microsoft 365 agent that supports MCP. 3. Test natural language commands that should trigger your tools: - "Create a task in my project management system"