Microsoft Entra Agent ID
General

Secure Mcp Server With Entra Id

In brief

The guide now specifies canonical MCP endpoint URLs, metadata discovery through the server origin and WWW-Authenticate header, fully qualified scopes, and v2 token claim values.

What Entra admins need to know

Review MCP registration, discovery responses, scopes, and validation logic. v2 tokens use the resource application's client-ID GUID for aud and the short scope name in scp.

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.

Prerequisites

  • A Microsoft Entra tenant.
  • An HTTPS endpoint for the MCP server.with a nonempty path and no trailing slash, such as https://mcp.contoso.com/mcp.
  • Permission to create an app registration and grant consent.
  • An MCP client that supports OAuth protected-resource metadata.

Register the MCP server

  1. Register an application for the MCP server.
  2. Set anthe Application ID URI that uniquely identifiesto the server.MCP server's canonical endpoint URL, such as https://mcp.contoso.com/mcp.
  3. Expose the delegated scopes required by MCP clients.
  4. Define application roles only if the server supports app-only access.
  5. Record the tenant ID, application client ID, and Application ID URI.

Publish protected-resource metadata

Publish a metadata document at <server-urlorigin>/.well-known/oauth-protected-resource, such as https://mcp.contoso.com/.well-known/oauth-protected-resource, and advertise its URL in the WWW-Authenticate header. This metadata URL is separate from the MCP endpoint at https://mcp.contoso.com/mcp. MCP clients that support OAuth protected-resource discovery fetch this document to find the authorization server and supported scopes before requesting a token.

The following example shows a minimal document for a Microsoft Entra-backed MCP server:

{
  "resource": "https://mcp.contoso.comcom/mcp",
  "authorization_servers": [
    "https://login.microsoftonline.com/<tenant-id>/oauth21/2026-08"
  ],
  "scopes_supported": [
    "https://mcp.contoso.com/mcp/mcp.access"
  ],
  "bearer_methods_supported": [
    "header"
}
  • resource — The canonical MCP server URL registered as the Application ID URI registered for the MCP server.URI. This value must match the client's OAuth resource parameter. For v2 access tokens, the token's aud claimis the server expects in incoming tokens.resource application's client-ID GUID, not this URL.
  • authorization_servers — The Microsoft Entra authorization server URL,For CIMD support, advertise the versioned identifier https://login.microsoftonline.com/<tenant>/oauth21/2026-08. Use your tenant ID for a server that accepts users from a single tenant, or commonorganizations for a server that accepts users from any organization. Clients append /.well-known/openid-configuration to this URL to discover the authorization and token endpoints. This field contains an authorization server identifier, not the full discovery-document URL, and must not contain a query string or fragment. The ordinary /v2.0 discovery identifier is used for conventional integrations, but doesn't select the versioned CIMD endpoints.
  • scopes_supported — The fully qualified delegated scopes exposed by the MCP server.server: the registered Application ID URI plus the exact scope name. For example, https://mcp.contoso.com/mcp and mcp.access produce https://mcp.contoso.com/mcp/mcp.access. List only the scopes clients need to call the server.
  • bearer_methods_supported — Set to ["header"] to indicate that clients must send the token in the Authorization request header.

For the full metadata format and discovery behavior, see the MCP authorization specification.

On an unauthenticated request, return a 401 response whose WWW-Authenticate header points to the metadata document and lists the required fully qualified scope:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.contoso.com/.well-known/oauth-protected-resource", scope="https://mcp.contoso.com/mcp/mcp.access"

Validate access tokens

Require an access token on protected MCP requests. Validate the token's signature, issuer, audience, lifetime, tenant, client, and permissions. Always use a supported library to validate access tokens.

UseFor v2 tokens issued to your MCP server, the MCP serverfollowing claims are issued:

ValueExpected value
isshttps://login.microsoftonline.com/<issuing-tenant-id>/v2.0
audYour resource application's Application client-ID URI or client ID as the expected audience, according to its registration. Enforce delegated scopes from GUID
scp and application permissions fromThe short, case-sensitive scope value, such as rolesmcp.access.

For the complete validation checklist, see Validate Agent ID tokens in a downstream API.

Use one of these client identity models:

  • A registered Agent ID.
  • A local public-client Agent ID using authorization code flow with PKCE.
  • A Client ID Metadata Document URL when preregistrationpre-registration isn't practical.

The MCP server doesn't need different token-validation logic for CIMD clients. Microsoft Entra ID still issues the access token, and the server validates it against the same issuer and audience policy.

Related content

Daily Entra.News

Get daily email updates

Get a concise summary of the latest Microsoft Entra updates delivered straight to your inbox.

Loading the secure signup form…