Client ID Metadata Documents in Microsoft Entra ID (preview)
In brief
The page now explains CIMD’s role in AI agents connecting to MCP servers and adds compatibility tables for tested clients and Microsoft MCP servers, including supported and unsupported entries.
What Entra admins need to know
Administrators can check CIMD compatibility before deploying MCP integrations and verify that custom clients host metadata at a stable HTTPS URL on a controlled domain.
This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.
Documentation change
The comparison below shows only the changed extract. Use the full-page view for complete context.
#customer-intent: As an identity architect or developer, I want to understand how Microsoft Entra ID supports Client ID Metadata Documents so that I can decide whether CIMD is appropriate for my MCP client scenario.
Client ID Metadata Documents in Microsoft Entra ID (preview)
Client ID Metadata Documents (CIMD) are a new way to register OAuth clients with Entra ID. CIMD is primarily used by AI agents that need to connect to remote MCP servers.
Why CIMD
AI agents may use many different MCP servers to perform work. Some of these MCP servers may be secured by Entra's OAuth server — e.g. WorkIQ, Azure Storage MCP, or enterprise-built MCP servers. Others may be secured by a different OAuth server — e.g. GitHub, Workday, Slack. For general purpose AI agents, it's impractical to know all MCP servers it will use, and therefore impractical to know all OAuth servers the AI agent will encounter. The AI agent needs a way to dynamically register itself with an OAuth server and obtain a client ID.
Client ID Metadata Documents (CIMD) let an OAuth client identify itself by using an HTTPS URL as its OAuth client_id value instead of a preassignedpre-registered client ID. TheA JSON document at that public URL contains the client's OAuth metadata. Microsoftmetadata, such as its redirect URIs and client credentials. This allows an OAuth server, such as Entra ID retrievesID, to fetch the JSON document and validatesuse it to securely issue access tokens to the document, represents the client as an agent identity in the tenant, and issues tokens under the tenant's existing consent and security policies.client.
CIMD is useful when a client must connect to many authorization servers with which it has no prior relationship. For example, an MCP clientAI agent can discover remote Model Context Protocol (MCP) servers at runtime, and each server might use a different authorization server. Requiring every client to be registered with every authorization server doesn't scale.
CIMD is defined by the OAuth Client ID Metadata Document specification. The MCP authorization specification recommends CIMD for clients that don't have another supported registration mechanism.
How CIMD works with Microsoft Entra ID
A typical CIMD authorization flow has the following steps:
An MCP client that discovers many remote servers at runtime is the primary scenario.
CIMD-enabled clients
The following table lists clients that have been tested and validated against Entra's CIMD support.
| Client | Client ID Metadata Document | Preview compatibility |
|---|---|---|
| Claude Code | https://claude.ai/oauth/claude-code-client-metadata | Supported. |
| Claude | https://claude.ai/oauth/mcp-oauth-client-metadata | Supported. |
| Codex | https://chatgpt.com/oauth/codex/client.json | Supported. |
| ChatGPT | https://chatgpt.com/oauth/client.json | Not supported. Its confidential-client authentication flow isn't supported by the Microsoft Entra preview. |
| Visual Studio Code | https://vscode.dev/oauth/client-metadata.json | Not supported. Microsoft first-party clients do not use CIMD. |
| GitHub Copilot | https://github.com/copilot/desktop/client-metadata.json | Not supported. Microsoft first-party clients do not use CIMD. |
| Custom client built with the official MCP SDKs | Host a metadata document at a stable HTTPS URL on a domain you control. | Supported. |
| Custom client implementation | Host a metadata document at a stable HTTPS URL on a domain you control. | Supported. |
CIMD-enabled MCP servers
The following table is a non-exhaustive list of Microsoft MCP servers that have confirmed CIMD support.
| MCP server | Remote MCP server URL | CIMD testing status |
|---|---|---|
| Custom enterprise-built MCP server | -- | Supported, see guide here. |
| Microsoft MCP for IT Admins | https://mcp.svc.cloud.microsoft/admin | Not supported yet. |
| Azure Management MCP (ARM) | https://mcp.management.azure.com | Not supported yet. |
| Azure DevOps MCP | https://mcp.dev.azure.com/{organization} | Not supported yet. |
| Work IQ MCP | https://workiq.svc.cloud.microsoft/mcp | Not supported yet. |
| Fabric IQ MCP | https://fabriciq.svc.cloud.microsoft/v1/mcp/fabriciq | Not supported yet. |
| Foundry MCP | https://mcp.ai.azure.com | Not supported yet. |
| Microsoft Sentinel MCP | https://sentinel.microsoft.com/mcp/data-exploration | Not supported yet. |
| Dataverse MCP | https://{dataverseOrgName}.crm.dynamics.com/api/mcp | Not supported yet. |
Supported capabilities and limitations
The following table summarizes the capabilities and limitations of CIMD-backed agent identities.
| Acting as an OAuth resource or token audience | Not supported |
| ID tokens or SAML tokens for user sign-in | Not supported |
| Shared client secrets | Not supported |
| Confidential-client authentication, including private_key_jwt | Not supported during preview; keys in the metadata document aren't processed |
| Microsoft first-party clients using CIMD | Not supported; use the existing first-party registration process |
| Publisher verification or Microsoft 365 certification | Not supported |
| Multiple agent identities sharing one blueprint | Not supported |
| Agent user accounts | Not supported |
- No app-only tokens: CIMD clients can't use the client credentials grant.
- Audience restriction: Microsoft Entra ID doesn't issue tokens whose audience is the CIMD client.
Consent and permissions for clients using CIMD
UnderEntra treats clients using CIMD as unverified, and honors existing tenant consent policy. This means that the default recommended consent policy,following rules apply:
| Tenant Setting | What users can consent to |
|---|---|
| Default consent policy | Users can sign-in to CIMD clients. This creates an agent identity in the tenant. Users can only grant a very limited set of OAuth scopes to openid and User.Read in Microsoft Graph. Risk-based step up prevents users from granting any other permissions to CIMD clients. |
| Do not allow user consent | In tenants that have disabled user consent via the Do not allow user consent setting in Entra Admin Center, users cannot consent to CIMD clients. This means they cannot add CIMD clients to their tenant, nor can they grant OAuth |
| Other consent policy | Using consent policy, tenants can allow users to consent to CIMD clients. Administrators have fine-grained control over the conditions when user consent is allowed. |
Admin controls for CIMD clients. Sensitive
Tenants can prevent users from adding CIMD clients or granting them new permissions require administrator consent. For administrator guidance, see Manage CIMD clients in Microsoft Entra IDvia consent policy. Use either of these approaches:
- Block all user consent, via the Do not allow user consent setting in Entra Admin Center.
- Allow user consent only for apps from verified publishers.
Either of these policies will prevent non-admin users from adding CIMD clients to a tenant. Follow Manage app consent policies to configure consent policy in your tenant.
To enable the use of a specific agent or client using CIMD, administrators can individually add agent identities to their tenant by providing the CIMD URL. This can be done via Entra Admin Center or Microsoft Graph APIs. See Managing CIMD clients.
Governance considerations
- Entra doesn't provide a tenant-managed domain allowlist or blocklist for CIMD URLs.
- Losing control of the document URL or its domain can affect every tenant that trusts that client identity.
UseAlways use least-privilege delegated permissions, preapprove clients that need sensitive access, monitor their sign-ins, and remove identities that are no longer required.
Related content
@@ -3,7 +3,7 @@ title: Client ID Metadata Documents in Microsoft Entra ID titleSuffix: Microsoft Entra Agent ID description: Learn how Client ID Metadata Documents let OAuth clients identify themselves to Microsoft Entra ID without prior client registration. ms.topic: concept-article-ms.date: 09/21/2026+ms.date: 10/30/2026 ai-usage: ai-assisted #customer-intent: As an identity architect or developer, I want to understand how Microsoft Entra ID supports Client ID Metadata Documents so that I can decide whether CIMD is appropriate for my MCP client scenario.@@ -11,16 +11,22 @@ ai-usage: ai-assisted # Client ID Metadata Documents in Microsoft Entra ID (preview) -Client ID Metadata Documents (CIMD) let an OAuth client identify itself by using an HTTPS URL instead of a preassigned client ID. The document at that URL contains the client's OAuth metadata. Microsoft Entra ID retrieves and validates the document, represents the client as an agent identity in the tenant, and issues tokens under the tenant's existing consent and security policies.+Client ID Metadata Documents (CIMD) are a new way to register OAuth clients with Entra ID. CIMD is primarily used by AI agents that need to connect to remote MCP servers. > [!IMPORTANT] > Client ID Metadata Document support in Microsoft Entra ID is in public preview. This preview is provided without a service-level agreement and isn't recommended for production workloads. Some features might be unsupported or have constrained capabilities. For more information, see [Universal License Terms for Online Services](https://www.microsoft.com/licensing/terms/product/ForOnlineServices/all). -CIMD is useful when a client must connect to many authorization servers with which it has no prior relationship. For example, an MCP client can discover remote Model Context Protocol (MCP) servers at runtime, and each server might use a different authorization server. Requiring every client to be registered with every authorization server doesn't scale.+## Why CIMD -CIMD is defined by the [OAuth Client ID Metadata Document specification](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/). The MCP authorization specification recommends CIMD for clients that don't have another supported registration mechanism.+AI agents may use many different MCP servers to perform work. Some of these MCP servers may be secured by Entra's OAuth server — e.g. WorkIQ, Azure Storage MCP, or enterprise-built MCP servers. Others may be secured by a different OAuth server — e.g. GitHub, Workday, Slack. For general purpose AI agents, it's impractical to know all MCP servers it will use, and therefore impractical to know all OAuth servers the AI agent will encounter. The AI agent needs a way to dynamically register itself with an OAuth server and obtain a client ID. -## How CIMD works with Microsoft Entra ID+Client ID Metadata Documents (CIMD) let an OAuth client identify itself by using an HTTPS URL as its OAuth `client_id` value instead of a pre-registered client ID. A JSON document at that public URL contains the client's OAuth metadata, such as its redirect URIs and client credentials. This allows an OAuth server, such as Entra ID, to fetch the JSON document and use it to securely issue access tokens to the client.++CIMD is useful when a client must connect to many authorization servers with which it has no prior relationship. For example, an AI agent can discover remote Model Context Protocol (MCP) servers at runtime, and each server might use a different authorization server. Requiring every client to be registered with every authorization server doesn't scale.++CIMD is defined by the [OAuth Client ID Metadata Document specification](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/).++## How CIMD works A typical CIMD authorization flow has the following steps: @@ -63,6 +69,37 @@ Implementers should always prefer pre-registration of a client with Entra when p An MCP client that discovers many remote servers at runtime is the primary scenario. +## CIMD-enabled clients++The following table lists clients that have been tested and validated against Entra's CIMD support.++| Client | Client ID Metadata Document | Preview compatibility |+| --- | --- | --- |+| Claude Code | https://claude.ai/oauth/claude-code-client-metadata | Supported. |+| Claude | https://claude.ai/oauth/mcp-oauth-client-metadata | Supported. |+| Codex | https://chatgpt.com/oauth/codex/client.json | Supported. |+| ChatGPT | https://chatgpt.com/oauth/client.json | Not supported. Its confidential-client authentication flow isn't supported by the Microsoft Entra preview. |+| Visual Studio Code | https://vscode.dev/oauth/client-metadata.json | Not supported. Microsoft first-party clients do not use CIMD. |+| GitHub Copilot | https://github.com/copilot/desktop/client-metadata.json | Not supported. Microsoft first-party clients do not use CIMD. |+| Custom client built with the official MCP SDKs | Host a metadata document at a stable HTTPS URL on a domain you control. | Supported. |+| Custom client implementation | Host a metadata document at a stable HTTPS URL on a domain you control. | Supported. |++## CIMD-enabled MCP servers++The following table is a non-exhaustive list of Microsoft MCP servers that have confirmed CIMD support.++| MCP server | Remote MCP server URL | CIMD testing status |+| --- | --- | --- |+| Custom enterprise-built MCP server | -- | Supported, see [guide here](/entra/agent-id/secure-mcp-server-with-entra-id). |+| [Microsoft MCP for IT Admins](https://github.com/microsoft/EnterpriseMCP) | `https://mcp.svc.cloud.microsoft/admin` | Not supported yet. |+| [Azure Management MCP (ARM)](/azure/azure-resource-manager/management/azure-resource-manager-mcp-quickstart) | `https://mcp.management.azure.com` | Not supported yet. |+| [Azure DevOps MCP](/azure/devops/mcp-server/remote-mcp-server) | `https://mcp.dev.azure.com/{organization}` | Not supported yet. |+| [Work IQ MCP](/microsoft-365/copilot/extensibility/work-iq/mcp/quickstart/github-copilot-cli) | `https://workiq.svc.cloud.microsoft/mcp` | Not supported yet. |+| [Fabric IQ MCP](/fabric/iq/connectors/fabric-iq-mcp) | `https://fabriciq.svc.cloud.microsoft/v1/mcp/fabriciq` | Not supported yet. |+| [Foundry MCP](/azure/foundry/mcp/get-started) | `https://mcp.ai.azure.com` | Not supported yet. |+| [Microsoft Sentinel MCP](/azure/sentinel/datalake/sentinel-mcp-tools-overview) | `https://sentinel.microsoft.com/mcp/data-exploration` | Not supported yet. |+| [Dataverse MCP](/power-apps/maker/data-platform/data-platform-mcp) | `https://{dataverseOrgName}.crm.dynamics.com/api/mcp` | Not supported yet. |+ ## Supported capabilities and limitations The following table summarizes the capabilities and limitations of CIMD-backed agent identities.@@ -77,6 +114,8 @@ The following table summarizes the capabilities and limitations of CIMD-backed a | Acting as an OAuth resource or token audience | Not supported | | ID tokens or SAML tokens for user sign-in | Not supported | | Shared client secrets | Not supported |+| Confidential-client authentication, including `private_key_jwt` | Not supported during preview; keys in the metadata document aren't processed |+| Microsoft first-party clients using CIMD | Not supported; use the existing first-party registration process | | Publisher verification or Microsoft 365 certification | Not supported | | Multiple agent identities sharing one blueprint | Not supported | | Agent user accounts | Not supported |@@ -96,7 +135,26 @@ Microsoft Entra ID applies the following protections: - **No app-only tokens:** CIMD clients can't use the client credentials grant. - **Audience restriction:** Microsoft Entra ID doesn't issue tokens whose audience is the CIMD client. -Under the default recommended consent policy, users can consent only to low-risk OAuth permissions for CIMD clients. Sensitive permissions require administrator consent. For administrator guidance, see [Manage CIMD clients in Microsoft Entra ID](manage-client-id-metadata-document-clients.md).+## Consent and permissions for clients using CIMD++Entra treats clients using CIMD as unverified, and honors existing tenant consent policy. This means that the following rules apply:++| Tenant Setting | What users can consent to |+| -------------- | ------------------------- |+| Default consent policy | Users can sign-in to CIMD clients. This creates an agent identity in the tenant. Users can only grant a very limited set of OAuth scopes to CIMD clients, such as `openid` and `User.Read` in Microsoft Graph. [Risk-based step up](/entra/identity/enterprise-apps/configure-risk-based-step-up-consent) prevents users from granting any other permissions to CIMD clients. |+| Do not allow user consent | In tenants that have disabled user consent via the **Do not allow user consent** setting in Entra Admin Center, users cannot consent to CIMD clients. This means they cannot add CIMD clients to their tenant, nor can they grant OAuth scopes to CIMD clients. |+| Other consent policy | Using [consent policy](/entra/identity/enterprise-apps/manage-app-consent-policies), tenants can allow users to consent to CIMD clients. Administrators have fine-grained control over the conditions when user consent is allowed. |++## Admin controls for CIMD++Tenants can prevent users from adding CIMD clients or granting them new permissions via [consent policy](/entra/identity/enterprise-apps/manage-app-consent-policies). Use either of these approaches:++- Block all user consent, via the **Do not allow user consent** setting in Entra Admin Center.+- Allow user consent only for apps from verified publishers.++Either of these policies will prevent non-admin users from adding CIMD clients to a tenant. Follow [Manage app consent policies](/entra/identity/enterprise-apps/manage-app-consent-policies) to configure consent policy in your tenant.++To enable the use of a specific agent or client using CIMD, administrators can individually add agent identities to their tenant by providing the CIMD URL. This can be done via Entra Admin Center or Microsoft Graph APIs. See [Managing CIMD clients](./manage-client-id-metadata-document-clients.md). ## Governance considerations @@ -109,7 +167,7 @@ Before using CIMD, account for the following considerations: - Entra doesn't provide a tenant-managed domain allowlist or blocklist for CIMD URLs. - Losing control of the document URL or its domain can affect every tenant that trusts that client identity. -Use least-privilege delegated permissions, preapprove clients that need sensitive access, monitor their sign-ins, and remove identities that are no longer required.+Always use least-privilege delegated permissions, preapprove clients that need sensitive access, monitor their sign-ins, and remove identities that are no longer required. ## Related content 