Connect Dynamics 365 CX MCP Server - Service through Agent 365 Tooling Gateway

Important

US NOTICE: Enabling this feature will allow data to egress outside of the FedRAMP High boundary. Users should confirm with their Tenant Administrator that this feature meets their organization’s specific security requirements and compliance obligations.

Use the Dynamics 365 CX Model Context Protocol (MCP) Server - Service to connect Customer Service data and tools to Microsoft Copilot Studio agents or other MCP clients that support HTTP-based MCP connections. Agent 365 Tooling Gateway (ATG) provides the Microsoft-hosted gateway that fronts the Customer Service MCP server and handles authentication to Dataverse.

This article explains how to:

Understand how Agent 365 Tooling Gateway authentication works for the Dynamics 365 CX MCP Server - Service.
Configure a Copilot Studio agent to use the Dynamics 365 CX MCP Server - Service server through Agent 365 Tooling Gateway.
Connect supported external MCP clients, such as Cursor, ChatGPT, Claude Code, Visual Studio Code, and GitHub Copilot CLI.
Troubleshoot common setup and authentication issues.

How Agent 365 Tooling Gateway authentication works

Agent 365 Tooling Gateway is an OAuth 2.0-protected resource. Each MCP server URL that the gateway fronts exposes OAuth discovery metadata through an anonymous discovery endpoint.

GET https://<ring-host>/.well-known/oauth-protected-resource/mcp/environments/<environment-id>/servers/mcp_D365CX_Service

The discovery response tells the MCP client which authorization server, resource audience, and scopes to use.

{
  "resource_name": "mcp_D365CX_Service",
  "resource": "https://<ring-host>/mcp/environments/<environment-id>/servers/mcp_D365CX_Service",
  "authorization_servers": [
    "https://login.microsoftonline.com/organizations/v2.0"
  ],
  "scopes_supported": [
    "https://<ring-host>/mcp/environments/<environment-id>/servers/mcp_D365CX_Service/.default",
    "openid",
    "profile",
    "offline_access"
  ],
  "bearer_methods_supported": [
    "header"
  ]
}

The MCP client requests a token for the Agent 365 Tooling Gateway resource. Agent 365 Tooling Gateway then performs the on-behalf-of exchange that allows the request to reach Dataverse.

Key considerations

The token audience is tooling gateway, not the Dynamics 365 CX MCP Server - Service directly.
The OAuth scope uses the Agent 365 Tooling Gateway resource URL and ends with /.default.
The /.default scope doesn't support incremental or dynamic user consent. Admin consent must be granted in advance in the customer tenant.
The scope is specific to the ring, environment, and server. Each ring and environment requires its own connector configuration.
Discovery-capable clients can read the OAuth metadata automatically. Copilot Studio custom connector setup might require you to enter OAuth values manually.

Prerequisites

Use the System Administrator or Omnichannel Administrator role to configure the MCP server.
Use the Customer Service Representative or CSR Manager role to use the MCP server and its tools.
The Dynamics 365 CX MCP Server - Service must be configured and available in the Copilot Studio tools list.
Dataverse environment ID. This is required in the Agent 365 Tooling Gateway server URL. The environment ID must belong to the same ring as the Agent 365 Tooling Gateway host.
Correct Agent 365 Tooling Gateway ring host and app ID.
Tenant admin or delegated admin-consent permissions.
Non-production tenant account for Test or PreProd, when you connect to non-production Agent 365 Tooling Gateway rings.

Note

The environment ID in the URL must belong to the same ring as the Agent 365 Tooling Gateway host. For example, a Test-ring environment ID doesn't resolve on the PreProd or Prod host.

Important

Enabling connections between Dynamics 365 and non-Dynamics 365 services, including Microsoft or external services, will allow data to egress outside of the Dynamics 365 FedRAMP High boundary. Data flowing from Dynamics 365 to other services will be processed and stored according to the terms, compliance commitments, and data residency and handling requirements of the destination service.

This data might include queries and other data submitted to agents by users in your organization. Before enabling MCP server connections for your organization, your Tenant Administrator should confirm that these connections meet their data security, compliance, residency, and governance requirements.

Agent 365 Tooling Gateway ring hosts and app IDs

Agent 365 Tooling Gateway uses separate hosts and Microsoft Entra app IDs for each ring. Use the host and app ID that match the target environment.

Ring	Gateway host	Microsoft Entra app ID
Test	`https://test.agent365.svc.cloud.dev.microsoft`	`05879165-0320-489e-b644-f72b33f3edf0`
PreProd	`https://preprod.agent365.svc.cloud.dev.microsoft`	`4585d2c8-61e2-4f6a-a2a5-707519abf91c`
Prod	`https://agent365.svc.cloud.microsoft`	`ea9ffc3e-8a23-4a7d-836d-234d7c7565c1`

Use this server URL format for all rings:

https://<ring-host>/mcp/environments/<environment-id>/servers/mcp_D365CX_Service

The /mcp/environments/ path segment is required. If you omit it, the request returns 404 RouteNotFound.

The Agent 365 Tooling Gateway app is a Microsoft first-party app registration. Before a client app can request a token for it, the tooling gateway service principal must exist in the customer tenant and the delegated permission must be admin-consented.

As a tenant admin, open the following admin-consent URL. Replace <customer-tenant-id> with the customer tenant ID and <ATG-ring-app-id> with the app ID for the target ring.

https://login.microsoftonline.com/<customer-tenant-id>/adminconsent?client_id=<ATG-ring-app-id>

Sign in as a tenant admin and approve the request. Microsoft Entra creates the Agent 365 Tooling Gateway resource service principal under Enterprise applications in the customer tenant.

You can also provision the service principal manually and grant admin consent as follows:

az ad sp create --id <ATG-ring-app-id>

New-MgServicePrincipal -AppId "<ATG-ring-app-id>"

Create a client Microsoft Entra app for Copilot Studio

To configure a custom connector in Copilot Studio, create your own confidential client app in Microsoft Entra ID. This app isn't the Dynamics 365 first-party app and only requires permission to access the Agent 365 Tooling Gateway resource scope.

In the Microsoft Entra admin center, complete the following steps:

Create a Microsoft Entra app registration by following the steps in Register an application. Make sure you use a single-tenant app registration.
Create a client secret for the app registration. Learn more in Add a client secret. Copy the secret value. You use this value when you configure OAuth in Copilot Studio.
Go to API permissions, and then select Add a permission.
Select APIs my organization uses.
Search for the Agent 365 Tooling Gateway app by using the app ID for the target ring.
Add the delegated permission that the Agent 365 Tooling Gateway app exposes for McpServers.D365Service.All.
Select Grant admin consent.

Leave the web redirect URI empty until Copilot Studio generates the callback URL during connector setup.

Add MCP server to agent

Open Copilot Studio, and then open or create an agent.

Follow the steps in Add tools and resources from a Model Context Protocol (MCP) server to your agent to create a new MCP server and provide the following details:

Field	Value
Server name	Enter a clear name, such as `Dynamics 365 CX MCP Server through ATG`.
Server description	Describe the available capabilities so the orchestrator can route requests to this server. For example, `Use Dynamics 365 Customer Experience tools to list, read, and update cases; search knowledge; view activity timelines; and draft emails.`
Server URL	`https://<ring-host>/mcp/environments/<environment-id>/servers/mcp_D365CX_Service`
Authentication	Select OAuth 2.0.

Enter the OAuth values that Agent 365 Tooling Gateway discovery metadata provides. Use manual configuration unless your Copilot Studio environment supports dynamic OAuth discovery for MCP servers.

Field	Value
Client ID	The client ID of the Microsoft Entra app that you created for Copilot Studio.
Client secret	The client secret value from the Microsoft Entra app.
Authorization URL	`https://login.microsoftonline.com/<customer-tenant-id>/oauth2/v2.0/authorize`
Token URL	`https://login.microsoftonline.com/<customer-tenant-id>/oauth2/v2.0/token`
Refresh URL	Same as the token URL.
Scope	`<ATG ring App ID>/.default` For example: Prod `ea9ffc3e-8a23-4a7d-836d-234d7c7565c1/.default`, Test `05879165-0320-489e-b644-f72b33f3edf0/.default`

After you create the OAuth configuration, Copilot Studio displays a callback URL. Copy the callback URL and add it as a Web redirect URI on the Microsoft Entra app that you created for Copilot Studio.

Create the connection and add the tool

In your Copilot Studio agent, complete the following steps:

In the Add tool dialog, select Create a new connection.
Sign in with an account that has access to the target Customer Service environment.
For Test or PreProd, use a non-production tenant account. A production or corporate tenant account on a non-production ring can trigger the TenantBlocked error.
Add the tool to the agent.
Publish the agent.

Optionally, if you want to use your agent in Customer Service, go to the Channels tab and connect the agent to Dynamics 365 Customer Service.

Configure discovery-capable MCP clients

Discovery-capable MCP clients, such as Visual Studio Code, GitHub Copilot CLI, Cursor, ChatGPT, and Claude Code, can retrieve tooling gateway OAuth metadata automatically. For these clients, configure the MCP server URL and let the client handle sign-in.

Note

No manual OAuth endpoint, client ID, scope, or secret is required for clients that support OAuth discovery for MCP servers.

Visual Studio Code

In Visual Studio Code, open the command palette by pressing Ctrl+Shift+P.
Enter MCP: Add Server.
Select HTTP or Server sent Events.
Add the Customer Service MCP server URL.

{
  "servers": {
    "d365-customer-service": {
      "type": "http",
      "url": "https://<ring-host>/mcp/environments/<environment-id>/servers/mcp_D365CX_Service"
    }
  },
  "inputs": []
}

GitHub Copilot CLI

Add the server to .mcp.json.

{
  "mcpServers": {
    "d365-customer-service": {
      "type": "http",
      "url": "https://<ring-host>/mcp/environments/<environment-id>/servers/mcp_D365CX_Service"
    }
  }
}

Cursor

Open Cursor.
Open Settings.
Go to Features > MCP Servers.
Select Add MCP Server.
Add the server configuration.

{
  "mcpServers": {
    "d365-customer-service": {
      "url": "https://<ring-host>/mcp/environments/<environment-id>/servers/mcp_D365CX_Service"
    }
  }
}

Replace <environment-id> with the Dataverse environment ID for the target environment.

ChatGPT

Open Settings > Connectors > MCP Servers.
Add the Customer Service MCP server URL.

https://<ring-host>/mcp/environments/<environment-id>/servers/mcp_D365CX_Service

Select Connect.
Sign in when the Microsoft authentication flow opens.
Verify that the available MCP tools are registered.

Claude Code

When Claude Code makes its first MCP request, it discovers the Agent 365 Tooling Gateway OAuth metadata, opens Microsoft sign-in, and stores tokens locally after the user authenticates.

Configure the MCP server in Claude Code.

{
  "mcpServers": {
    "d365-customer-service": {
      "transport": {
        "type": "http",
        "url": "https://<ring-host>/mcp/environments/<environment-id>/servers/mcp_D365CX_Service"
      }
    }
  }
}

Feedback

Was this page helpful?

Last updated on 2026-07-30