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
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.

Prerequisites

Before you begin, ensure you have:

A test tenant to validate your MCP integration
A working MCP server with a secure public endpoint
Authentication credentials (OAuth configuration or API key)

Add the agent connector to your manifest

First, declare your MCP server in the agentConnectors array at the root level of your app manifest.

Open your Microsoft 365 app manifest (manifest.json) file.
Locate or create the root-level agentConnectors array.
Add a new connector object with a unique id, displayName, and description:

{
  "$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.example.com"
        }
      }
    }
  ]
}

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.

Within your connector's toolSource, specify the remoteMcpServer endpoint:

"toolSource": {
  "remoteMcpServer": {
    "mcpServerUrl": "https://mcp.example.com"
  }
}

Ensure your endpoint uses HTTPS (for HTTP connections) or WSS (for WebSocket connections).

The endpoint must be publicly accessible and respond to MCP protocol handshake messages. Microsoft 365 agents establish long-lived connections to this endpoint.

Configure authentication

Specify how Microsoft 365 retrieves credentials when calling your MCP server. The following values are currently supported for MCP server authentication:

None: No authentication required
OAuthPluginVault: OAuth 2.0 tokens stored inside Microsoft’s secure vault
ApiKeyPluginVault: API key stored in a vault and referenced by ID
DynamicClientRegistration: Dynamic OAuth client registration
AzureKeyVault: Secrets stored in your own Azure Key Vault instance

Use OAuth authentication

For OAuth 2.0 tokens stored in Microsoft's secure vault, specify authorization type OAuthPluginVault in your configuration:

"remoteMcpServer": {
  "mcpServerUrl": "https://mcp.example.com",
  "authorization": {
    "type": "OAuthPluginVault",
    "referenceId": "my-oauth-config"
  }
}

The referenceId points to a secure OAuth configuration that you register in Developer Portal. For details, see Configure OAuth in Developer Portal.

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 API key authentication

For API keys stored in a vault, configure the authorization type as ApiKeyPluginVault:

"authorization": {
  "type": "ApiKeyPluginVault",
  "referenceId": "my-apikey"
}

The referenceId points to an API key that you register in Developer Portal. For details, see API key authentication.

Use dynamic client registration

Dynamic client registration enables Microsoft 365 to register as an OAuth client with your MCP server at runtime using the RFC 7591 protocol. This approach is useful when your server supports dynamic OAuth flows and you don't want to pre-register client credentials.

Configure the authorization type as DynamicClientRegistration with a referenceId:

"authorization": {
  "type": "DynamicClientRegistration",
  "referenceId": "my-dcr-config"
}

The referenceId points to a dynamic client registration configuration that you register in Developer Portal. This configuration provides the necessary authorization values that Microsoft 365 uses when negotiating client credentials with your MCP server's OAuth registration endpoint.

Your server must:

Expose a RFC 7591 compliant client registration endpoint.
Return a client_id and client_secret that Microsoft 365 can use to obtain access tokens.
Support token refresh for long-lived sessions.

Use Azure Key Vault authentication

Azure Key Vault authentication allows you to store and manage your MCP server credentials in your own Azure Key Vault instance. This gives you full control over secret lifecycle management, including rotation, access policies, and audit logging.

Configure the authorization type as AzureKeyVault:

"authorization": {
  "type": "AzureKeyVault",
  "referenceId": "my-keyvault-secret"
}

The referenceId points to a secret identifier registered in Developer Portal that maps to your Azure Key Vault secret.

To set up Azure Key Vault authentication:

Store your MCP server credentials (API key or client secret) as a secret in your Azure Key Vault.
Grant the Microsoft 365 service principal access to read the secret by configuring an access policy or Azure RBAC role on your vault.
Register the secret reference in Developer Portal and note the registration ID.
Use the registration ID as the referenceId in your manifest.

Use no authentication

If your server doesn't require authentication (not recommended for production), set the authorization type to None or omit the authorization object entirely.

For enterprise scenarios, prefer OAuth over API keys to align with security best practices and administrator expectations.

Define tool discovery

Configure how Microsoft 365 agents discover the tools your MCP server provides. Use static inline tool definitions when your toolset is stable, or enable dynamic tool discovery when your toolset changes frequently.

Use static tool definitions

For static toolsets that don't change frequently, add an mcpToolDescription object with your tool definitions:

"remoteMcpServer": {
  "mcpServerUrl": "https://mcp.example.com",
  "authorization": {
    "type": "ApiKeyPluginVault",
    "referenceId": "my-apikey"
  },
  "mcpToolDescription": {
    "description": {
      "file": "toolDescription.json"
    }
  }
}

The description object must match the schema returned by your MCP server's tools/list response.

Use dynamic tool discovery

Dynamic tool discovery allows Microsoft 365 agents to fetch your tool list at runtime by calling your server's tools/list method. This approach is recommended when your toolset changes frequently, as it eliminates the need to republish your app each time tools are added, updated, or removed.

To enable dynamic tool discovery, omit the mcpToolDescription from your remoteMcpServer configuration:

"remoteMcpServer": {
  "mcpServerUrl": "https://mcp.example.com",
  "authorization": {
    "type": "OAuthPluginVault",
    "referenceId": "my-oauth-config"
  }
}

When mcpToolDescription is omitted, Microsoft 365 agents:

Connect to your MCP server endpoint.
Call the tools/list method to retrieve the available tools at runtime.
Update the available tool list without requiring a manifest republish.

Your MCP server must return a valid tools/list response that includes each tool's name, description, and input schema.

Validate your configuration

Before deploying your agent or app, verify that your manifest and MCP server are correctly configured.

Use the Microsoft 365 app package validation tool in Developer Portal to check your manifest for errors.
Verify if your MCP server responds correctly to handshake messages by testing the connection manually.
Confirm that your tools/list endpoint returns schema-compliant tool definitions:
- Each tool has a unique name and description
- Input schemas are valid JSON Schema
- Required and optional parameters are clearly defined
Test your authorization configuration:
- Verify the referenceId points to a valid secret
- Confirm tokens or keys are correctly retrieved
- Test token refresh if using OAuth
Ensure your endpoint supports TLS 1.2 or higher.
Verify error messages and retry semantics for failed tool calls.

Test with Microsoft 365 agents

Validate your integration by testing with actual Microsoft 365 agents.

Deploy your agent or app to a test environment.
Open a Microsoft 365 agent that supports MCP.
Test natural language commands that should trigger your tools:
- "Create a task in my project management system"
- "Update the status of ticket number 123"
- "Search for open issues assigned to me"
Verify that:
- Tools appear in the agent's available actions
- User consent prompts display when required
- Tool calls execute successfully
- Responses are processed correctly
- Error conditions are handled gracefully
Test across multiple tenants if your scenario requires multi-tenant support.

Troubleshoot common issues

If your MCP server isn't working as expected, check these common issues:

Agent can't connect to your server

Verify your endpoint is publicly accessible
Confirm your endpoint uses HTTPS or WSS
Check firewall and network security settings
Ensure your server responds to MCP handshake messages

Tools don't appear in agents

Verify tools/list returns valid tool definitions
Check that tool descriptions are clear and complete
For static definitions, validate the JSON schema of your inline tool definitions
For dynamic discovery, confirm mcpToolDescription is omitted and your server correctly responds to tools/list at runtime

Authentication failures

Verify the referenceId matches your stored secret configuration
Test that OAuth tokens are valid and not expired
Confirm API keys have the necessary permissions
Check authorization header format in outbound requests

Tool calls fail or time out

Review your server logs for errors
Verify input parameter validation is working correctly
Check that responses follow MCP protocol format
Ensure your server handles concurrent requests

Next steps

When ready, submit your app for partner certification and publishing.

Feedback

Was this page helpful?

Last updated on 2026-06-24