Almanac
Microsoft/d365ci-dataDynamics 365

Consultant-focused KB for Microsoft Dynamics 365 Customer Insights – Data: implementation notes, gotchas, and configuration decisions beyond the official docs — across data unification, customer profiles, segments, measures and insights, predictions and AI, Dataverse integration, Copilot, and administration.

d365ci-data/08-administration/feature-mcp-server-agent365-tooling-gateway.md
feature-mcp-server-agent365-tooling-gateway.mdv1 · history
CurrentApplies to AllUpdated 3 weeks agoSource Microsoft Learn ↗

What it does

Agent 365 Tooling Gateway is the Microsoft-hosted gateway in front of the Customer Insights MCP server. It's an OAuth 2.0 protected resource that handles authentication to Dataverse via an on-behalf-of exchange. This is how Copilot Studio agents and external MCP clients (Visual Studio Code, GitHub Copilot CLI, Cursor, ChatGPT, Claude Code) reach the one server that serves both Customer Insights - Data and Journeys.

Key facts

  • The server URL is environment-specific: https://agent365.svc.cloud.microsoft/mcp/environments/<environment-id>/servers/mcp_D365CX_CustomerInsights. The /mcp/environments/ segment is mandatory, otherwise you get 404 RouteNotFound.
  • The token audience is the gateway, not the MCP server. Request either <gateway-app-id>/.default or the named delegated permission McpServers.D365CustomerInsights.All. The gateway app ID on the page is ea9ffc3e-8a23-4a7d-836d-234d7c7565c1.
  • /.default doesn't support dynamic consent, so a tenant admin must grant it in advance. The named permission is user-consentable if your tenant allows user consent.
  • Add offline_access or the client gets no refresh token and the connection dies when the access token expires.
  • Before any client app can request a gateway token, the gateway service principal must exist in your tenant. A tenant admin creates it with az ad sp create --id <app-id> or New-MgServicePrincipal -AppId.
  • In Copilot Studio, check the tools catalogue first: search the MCP filter for Dynamics 365 CX Customer Insights. Adding from the catalogue configures URL and OAuth for you, no app registration or secret needed. A tenant admin can check or block it under Agents > Tools > Registry in the Microsoft 365 admin centre.
  • Manual setup needs your own single-tenant Entra app with a client secret, the delegated permission, admin consent, and the Copilot Studio callback URL added as a Web redirect URI afterwards.
  • Discovery-capable clients just need the URL and read the OAuth metadata themselves. They sign in with their own Entra client app.
  • Prerequisites: System Administrator role, the Dataverse environment ID, the tenant ID, and admin-consent rights for manual or external-client setups.

When to use / skip

Use the gateway whenever an agent outside Dynamics needs Customer Insights tools with Entra-governed access. Use the catalogue route if it's there; fall back to manual setup only when the server isn't listed. Skip external MCP clients entirely if your data-boundary position doesn't allow customer queries to leave the Dynamics 365 boundary: Learn states that enabling these connections lets data, including user queries to agents, leave the FedRAMP High boundary, and tenant admins should confirm requirements first.

Configuration decisions

  • Catalogue or manual setup in Copilot Studio.
  • /.default with pre-granted admin consent, or the named permission with user consent.
  • One connector configuration per environment, since the URL carries the environment ID. The permission itself is the same across environments.
  • Which external clients are permitted at all, and whether they use a client app you register or their own.
  • Who holds the tools registry in the admin centre.

Gotchas

  • Environment ID and tenant ID are different things. Putting the tenant ID in the URL gives 400 EndpointInvalid; the environment ID goes only in the server and discovery URLs, the tenant ID in every login.microsoftonline.com URL.
  • Never provision the gateway with an admin-consent URL aimed at the gateway app. It fails with AADSTS65002 because Entra blocks consent between Microsoft first-party apps. Create the service principal instead and consent on your own client app.
  • A /.default request never fails for a missing permission. Entra quietly issues a token with whatever the client already holds, so a valid token plus 403 Forbidden means the scp claim lacks McpServers.D365CustomerInsights.All. Decode the token.
  • A 403 after a successful external-client sign-in usually means that client's own app hasn't been granted the permission. Grant it, or point the client at an app you registered.
  • Tools missing from the agent point to the user's Dataverse table privileges.

Consultant notes

  • Start the workshop with the data-boundary question, not the OAuth one. The consent plumbing is routine; the governance conversation about ChatGPT or Cursor talking to customer data is not.
  • Get the tenant admin to create the service principal and consent up front. Most stalled engagements here will be a developer waiting for consent.
  • Keep the troubleshooting table from the Learn page in the runbook; each error maps cleanly to one cause.
  • This page covers connection only. For what the tools do, see the tools doc.

Worth rechecking if the gateway app ID, scope names or the catalogue route change, or if more MCP clients get documented.

Was this accurate?
Related
Dynamics 365 Customer Insights – Data KB — Features & Changelog_rootCustomer Insights tenant licensing and how Data and Journeys sit under it09-licensingConnections, third-party consent and API access08-administrationEnabling and restricting Copilot: consent settings and data residency07-copilot-in-ci-dataCustomer Insights MCP server tools06-dataverse-integrationStorage cost model: managed storage, your own lake, and Fabric09-licensing