Edit

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.

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

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

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

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

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

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.

Validate your configuration

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

  1. Use the Microsoft 365 app package validation tool in Developer Portal to check your manifest for errors.

  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:

    • Each tool has a unique name and description
    • Input schemas are valid JSON Schema
    • Required and optional parameters are clearly defined

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

  5. Ensure your endpoint supports TLS 1.2 or higher.

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

  1. Deploy your agent or app to a test environment.

  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"
    • "Update the status of ticket number 123"
    • "Search for open issues assigned to me"

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

  5. 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
  • Validate the JSON schema of inline tool definitions

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.

  • Last updated on