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 ashttps://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
- Register an application for the MCP server.
- Set
anthe Application ID URIthat uniquely identifiesto theserver.MCP server's canonical endpoint URL, such ashttps://mcp.contoso.com/mcp. - Expose the delegated scopes required by MCP clients.
- Define application roles only if the server supports app-only access.
- Record the tenant ID, application client ID, and Application ID URI.
Publish protected-resource metadata
Publish a metadata document at <server-, such as urlorigin>/.well-known/oauth-protected-resourcehttps://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 IDURI registered for the MCP server.URI. This value must match the client's OAuthresourceparameter. For v2 access tokens, the token'saudclaimis theserver 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 identifierhttps://login.microsoftonline.com/<tenant>/oauth21/2026-08. Use your tenant ID for a server that accepts users from a single tenant, orfor a server that accepts users from any organization. Clients appendcommonorganizations/.well-known/openid-configurationto 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.0discovery identifier is used for conventional integrations, but doesn't select the versioned CIMD endpoints.scopes_supported— The fully qualified delegated scopes exposed by the MCPserver.server: the registered Application ID URI plus the exact scope name. For example,https://mcp.contoso.com/mcpandmcp.accessproducehttps://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 theAuthorizationrequest 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:
| Value | Expected value |
|---|---|
iss | https://login.microsoftonline.com/<issuing-tenant-id>/v2.0 |
aud | Your resource application's |
scp | The short, case-sensitive scope value, such as |
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. AClient ID Metadata Document URL whenpreregistrationpre-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
@@ -19,14 +19,14 @@ This guidance supports Microsoft identity platform v2.0 access tokens only. ## Prerequisites - A Microsoft Entra tenant.-- An HTTPS endpoint for the MCP server.+- An HTTPS endpoint 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.-1. Set an Application ID URI that uniquely identifies the server.+1. Set the Application ID URI to the MCP server's canonical endpoint URL, such as `https://mcp.contoso.com/mcp`. 1. Expose the delegated scopes required by MCP clients. 1. Define application roles only if the server supports app-only access. 1. Record the tenant ID, application client ID, and Application ID URI.@@ -35,18 +35,18 @@ Grant only the permissions required by the tools and resources that the server e ## Publish protected-resource metadata -Publish a metadata document at `<server-url>/.well-known/oauth-protected-resource`. MCP clients that support OAuth protected-resource discovery fetch this document to find the authorization server and supported scopes before requesting a token.+Publish a metadata document at `<server-origin>/.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: ```json {- "resource": "https://mcp.contoso.com",+ "resource": "https://mcp.contoso.com/mcp", "authorization_servers": [ "https://login.microsoftonline.com/<tenant-id>/oauth21/2026-08" ], "scopes_supported": [- "mcp.access"+ "https://mcp.contoso.com/mcp/mcp.access" ], "bearer_methods_supported": [ "header"@@ -54,18 +54,31 @@ The following example shows a minimal document for a Microsoft Entra-backed MCP } ``` -- **`resource`** — The Application ID URI registered for the MCP server. This value must match the `aud` claim the server expects in incoming tokens.-- **`authorization_servers`** — The Microsoft Entra authorization server URL, `https://login.microsoftonline.com/<tenant>/oauth21/2026-08`. Use your tenant ID for a server that accepts users from a single tenant, or `common` 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.-- **`scopes_supported`** — The delegated scopes exposed by the MCP server. List only the scopes clients need to call the server.+- **`resource`** — The canonical MCP server URL registered as the Application ID URI. This value must match the client's OAuth `resource` parameter. For v2 access tokens, the token's `aud` is the resource application's client-ID GUID, not this URL.+- **`authorization_servers`** — 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 `organizations` 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: 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](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization). +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+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.+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. -Use the MCP server's Application ID URI or client ID as the expected audience, according to its registration. Enforce delegated scopes from `scp` and application permissions from `roles`.+For v2 tokens issued to your MCP server, the following claims are issued:++| Value | Expected value |+| --- | --- |+| `iss` | `https://login.microsoftonline.com/<issuing-tenant-id>/v2.0` |+| `aud` | Your resource application's client-ID GUID |+| `scp` | The short, case-sensitive scope value, such as `mcp.access` | For the complete validation checklist, see [Validate Agent ID tokens in a downstream API](how-to-validate-agent-tokens-downstream-api.md). @@ -139,10 +152,7 @@ The client discovers the protected-resource metadata, signs in or authenticates 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](client-id-metadata-documents.md) URL when preregistration 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.+- A [Client ID Metadata Document](client-id-metadata-documents.md) URL when pre-registration isn't practical. ## Related content 