How to Add Microsoft Entra ID Authentication and Tool-Level Authorization to an MCP Server

MCP servers can expose databases, APIs, SaaS applications, and operational tools to AI agents. Microsoft Entra ID authenticates the user, application, or agent and issues an access token. Datawiza Agent Gateway then uses that identity context, including scopes, roles, and claims, to enforce which MCP servers, tools, actions, and downstream resources the caller may access.

This guide shows how to protect an existing self-hosted HTTP-based MCP server with Microsoft Entra ID and Datawiza Agent Gateway. The gateway sits in front of the MCP server, automatically publishes OAuth Protected Resource Metadata, validates Entra-issued access tokens, applies server-, tool-, and action-level policy, and forwards only approved requests. The backend MCP server remains focused on tools and business logic instead of implementing enterprise OAuth discovery and token validation itself.

What this guide shows

• Register the protected MCP endpoint as an API in Microsoft Entra ID.
• Connect interactive MCP clients with authorization code and PKCE, or connect unattended agents with an appropriate workload identity flow.
• Automatically publish OAuth Protected Resource Metadata so compatible MCP clients can discover Microsoft Entra ID as the authorization server.
• Validate Entra access tokens before requests reach the MCP server.
• Enforce least-privilege access by MCP server, tool, action, user, application, workload, and environment.
• Keep the backend MCP server private and record allowed and denied decisions.

Follow the Claude setup tutorial or the ChatGPT setup tutorial for exact client-specific configuration.

What you will build

You will place Datawiza Agent Gateway in front of an existing HTTP-based MCP server. The client connects to a trusted HTTPS endpoint on the gateway, while the backend MCP server remains reachable only from the private network path.

• Microsoft Entra ID authenticates the user, application, workload, or agent and issues an OAuth access token.
• Datawiza publishes the protected resource metadata and returns the OAuth discovery challenge required by compatible MCP clients.
• Datawiza validates the token's signature, issuer, tenant, audience, lifetime, scopes, roles, and relevant identity claims.
• Datawiza evaluates MCP server-, tool-, and action-level policy before forwarding the request.
• The private MCP server receives only approved traffic and continues to execute its existing tools.
• Allowed and denied requests are recorded with identity and policy context.

Microsoft Entra ID OAuth architecture for MCP servers

For an interactive client such as ChatGPT, Claude, Visual Studio Code, or Cursor, Datawiza first exposes OAuth Protected Resource Metadata for the MCP endpoint. The client discovers Microsoft Entra ID as the authorization server, then uses Entra's OAuth 2.0 authorization-code flow with PKCE, satisfying the relevant OAuth 2.1 security requirements used by MCP. The client presents the resulting bearer access token to Datawiza Agent Gateway, which validates it and evaluates authorization policy before forwarding the request.

Autonomous agents use the same enforcement point but may obtain tokens differently. An unattended workload can use the OAuth 2.0 client-credentials flow and application roles. An agent acting for a signed-in user can use a delegated or on-behalf-of design when downstream operations must preserve user context. In each case, the resulting bearer token is presented to Datawiza for validation and least-privilege policy enforcement.

• The MCP client, user, application, or agent obtains an access token from Microsoft Entra ID.
• The client sends the MCP request and bearer access token to the Datawiza-protected endpoint.
• Datawiza validates token integrity, issuer, tenant, audience, expiration, scopes, roles, and relevant claims.
• Policy decides which MCP server, tool, action, data path, and environment the identity may reach.
• Only approved requests reach the backend MCP server; the decision is logged.

Why put an identity-aware agent gateway in front of your MCP server?

Microsoft Entra ID can authenticate a user, application, workload, or agent and issue an access token. The protected endpoint must still validate that token, map identity claims to MCP permissions, enforce the decision, and record the activity. Rebuilding those controls in every MCP server produces duplicated security logic and inconsistent policy.

Datawiza Agent Gateway centralizes this enforcement in front of existing MCP servers. That gives identity and security teams one policy point while MCP developers keep their services focused on tools and business logic.

• Protect existing HTTP-based MCP servers without adding OAuth discovery or token-validation libraries to each server or changing tool code.
• Automatically provide OAuth Protected Resource Metadata and direct compatible MCP clients to Microsoft Entra ID.
• Apply consistent issuer, tenant, audience, signature, expiration, scope, role, and claim checks.
• Enforce least-privilege server-, tool-, and action-level policy beyond broad OAuth scopes.
• Keep backend MCP servers private while exposing one controlled HTTPS endpoint to approved clients.
• Record the user, client, workload or agent, tool call, matched policy, and outcome in one audit trail.

Prerequisites

• A Microsoft Entra ID tenant.
• Permission to create app registrations, expose API permissions, and grant consent where required.
• An existing HTTP-based MCP server reachable from the gateway over an internal network path.
• A public HTTPS hostname and trusted certificate for the protected MCP endpoint.
• A Datawiza Agent Gateway deployment in your cloud, private network, on-premises environment, or Datawiza-hosted service.
• An MCP client such as ChatGPT, Claude, Visual Studio Code, Cursor, or an agent workflow.

Configuration reference

Step 1: Register the MCP server as a protected API

Create an Entra app registration that represents the MCP endpoint as an OAuth-protected API. The resource app defines the API identifier and permissions requested by clients. It does not need a browser redirect URI because users do not sign in directly to the resource app.

Under Expose an API, configure an Application ID URI and define at least one delegated scope for signed-in user access. In Datawiza's documented ChatGPT and Claude pattern, the protected MCP URL is used as the Application ID URI so the MCP resource requested by the client aligns with the gateway configuration.

Microsoft reference: Configure an application to expose a web API.

Application ID URI and access-token audience are not always identical

Do not assume that the Application ID URI always appears unchanged in the access token's aud claim. Microsoft documents that v2 access tokens use the protected API's client ID as aud. A v1 access token can use the client ID or the resource URI, depending on how the token was requested.

The current Datawiza ChatGPT and Claude tutorials use the resource app's default v1 token behavior and configure the protected MCP URL as the Application ID URI and gateway audience. If your resource app requests v2 access tokens, inspect the actual ver, iss, and aud claims and configure the gateway to match the token issued by your tenant. Never accept a token merely because Microsoft Entra ID issued it; its audience must identify your protected MCP resource.

Use an access token, not an ID token

An ID token tells a client application that a user signed in. It is not intended to authorize calls to the MCP API. The MCP client must present an access token issued for the protected MCP resource. Datawiza validates that access token before forwarding the request.

Step 2: Register the MCP client or agent

Create a separate Entra client app registration for the MCP client that initiates authentication. Configure the redirect URI required by that client, grant permission to request the resource app's delegated scope, and apply admin consent according to your organization's policy. Interactive clients use Entra's OAuth 2.0 authorization-code flow with PKCE, satisfying the relevant OAuth 2.1 security requirement used by MCP.

Choose the identity pattern

• Signed-in user: use authorization code with PKCE. Delegated permissions normally appear in scp.
• Unattended agent or workload: use client credentials. Application permissions normally appear in roles.
• Agent acting for a signed-in user: use a delegated or on-behalf-of design when downstream operations must preserve user context.

Tested MCP clients

Datawiza has tested this Entra ID authentication pattern end to end with ChatGPT, Claude, Visual Studio Code, and Cursor. Redirect URIs, client registration requirements, and connection settings differ by client, so use the current client-specific tutorial where one is available rather than copying settings from another client.

Step 3: Put Datawiza Agent Gateway in front of the MCP server

Configure the gateway's public service with the protected MCP hostname and point its backend to the existing private MCP server. The client connects only to the Datawiza-protected endpoint; the backend server does not need to be directly reachable from the internet.

Configure Entra ID access-token authentication with the actual issuer and audience expected for your resource app. Datawiza validates the token on every request before the backend sees it. Use a trusted TLS certificate because hosted MCP clients commonly reject self-signed certificates.

How the MCP client learns about Microsoft Entra ID

Datawiza Agent Gateway automatically publishes OAuth Protected Resource Metadata for the protected MCP endpoint. When an unauthenticated compatible client connects, the gateway returns 401 Unauthorized and uses the WWW-Authenticate challenge to point the client to the resource metadata. That metadata identifies Microsoft Entra ID as the authorization server and supplies the protected resource information needed to begin the OAuth flow. The backend MCP server does not need to implement this discovery behavior.

Protected resource discovery and client registration are separate concerns. Microsoft Entra ID does not support OAuth Dynamic Client Registration, so the current Datawiza patterns still use pre-registered Entra client applications. For ChatGPT, choose User-Defined OAuth Client and enter the Entra client ID. For Claude Code or Claude.ai, provide the pre-registered client ID through the documented command or advanced settings. Datawiza then validates the resulting bearer access token on every request. Do not assume that DCR, CIMD, redirect URIs, or client-registration behavior are identical across clients.

Step 4: Connect the MCP client to the protected endpoint

Configure the MCP client with the Datawiza-protected URL, not the internal server URL. For interactive clients, the user completes the Entra authorization flow and the client attaches the resulting bearer access token to subsequent MCP requests. For unattended agents, configure the approved workload token flow instead of borrowing a human user's token.

Use the dedicated Claude MCP server tutorial or ChatGPT MCP server tutorial for exact redirect URIs, Entra registration fields, gateway settings, and test steps.

Step 5: Add MCP server-, tool-, and action-level authorization

A valid Entra access token establishes trusted identity context. It does not grant blanket permission to every tool. Datawiza can evaluate scopes, app roles, groups, tenant, client application, user or service principal, agent context, target server, tool, action, and environment before allowing the request.

Practical least-privilege example

Suppose an Entra group named MCP-Finance-Readers needs invoice visibility but must not initiate or alter payments. After token validation, Datawiza can apply a policy that allows read tools and denies sensitive write tools:

• Allow list_invoices.
• Allow get_invoice.
• Allow search_vendors.
• Deny create_payment.
• Deny update_bank_account.
• Deny delete_vendor.

Authentication confirms who or what is calling. Tool-level authorization determines what that identity may do after authentication succeeds.

Use stable Entra claims for policy

Use tid for the trusted tenant, oid for the stable user or service-principal identity, azp in v2 tokens or appid in v1 tokens for the calling client, scp for delegated permissions, roles for application permissions, aud for the intended resource, and iss for the trusted issuer. Prefer stable identifiers such as oid and tid for authorization. Names, email addresses, and preferred_username are mutable display values and should not be the primary authorization key.

For a broader policy model, see MCP access control.

What Datawiza removes from the MCP server

Without a shared enforcement layer, every MCP server team may need to implement and maintain the same identity controls. Datawiza centralizes the following capabilities in front of the server:

• OAuth Protected Resource Metadata, Microsoft Entra discovery, and access-token validation.
• Signature, issuer, tenant, audience, lifetime, scope, role, and identity checks.
• User, client, workload, and agent identity mapping.
• MCP server-, tool-, and action-level policy enforcement.
• Allowed- and denied-request logging with policy context.

The backend MCP server generally does not need to implement enterprise OAuth or Entra token validation. Some deployments still require network, DNS, TLS, routing, client registration, or identity-context configuration.

Step 6: Test authentication, authorization, and audit

Test failure paths as deliberately as the successful connection:

• Call the protected endpoint without a token and confirm it returns 401 Unauthorized with a WWW-Authenticate challenge pointing to valid protected resource metadata.
• Reject an expired token, an ID token, and an access token issued for another tenant or API.
• Allow a read-only identity to call an approved read tool.
• Return 403 Forbidden when that valid identity calls a denied write or administrative tool.
• Verify that caller context, MCP server, tool, matched policy, decision, and outcome appear in the audit trail.

Use 401 when authentication is missing or invalid. Use 403 when authentication is valid but the identity lacks permission for the requested operation.

Common Entra ID MCP authentication problems

The client cannot discover the protected resource metadata

Symptom: the client reaches the MCP endpoint but does not begin the Entra authorization flow. Confirm that the public endpoint returns the expected 401 challenge, that its protected resource metadata URL is reachable over trusted HTTPS, and that the metadata identifies the correct Entra authorization server and MCP resource.

The client sends an ID token

Symptom: sign-in succeeds but the MCP request is rejected. Inspect the bearer token and confirm it is an access token issued for the MCP resource, with the expected aud and either scp for delegated access or roles for application access.

The access-token audience does not match

Symptom: a correctly signed token still receives 401. Inspect ver and aud in the actual access token, then align the Entra resource app, requested scope, and gateway audience. V1 and v2 token audiences can use different formats.

The issuer is wrong for the token version

Symptom: signature validation succeeds but issuer validation fails. Inspect ver and iss, then configure the gateway for the issuer associated with the token version actually emitted by the resource app.

The redirect URI is rejected

Symptom: Entra returns a redirect mismatch during sign-in. Register the exact callback produced by the MCP client. ChatGPT, Claude Code, Claude.ai, Visual Studio Code, and Cursor can use different callback patterns.

The client requests the wrong scope or resource

Symptom: consent or token issuance fails. Confirm that the client app has permission to the resource app's scope and that the requested resource, Application ID URI, client registration, and protected endpoint are consistent.

Authentication succeeds, but authorization is too broad

Symptom: any valid Entra identity can call every tool. Add explicit policies for server, tool, action, environment, group, role, user, client, workload, or agent context. A valid token should be an input to policy, not blanket approval.

Advanced: Conditional Access and Microsoft Entra Agent ID

Conditional Access can influence sign-in and token issuance using signals such as MFA, user risk, location, and device posture. Datawiza then makes the MCP-specific authorization decision after authentication: whether the validated identity may call a particular server, tool, or action.

For agents hosted and governed through Microsoft's agent platform, an Entra agent identity can provide a distinct runtime identity for the agent. This can complement user and client identity, but it does not automatically replace MCP-specific authorization at the protected endpoint, and not every MCP client or agent supports Entra Agent ID.

What this architecture does and does not do

• It adds Microsoft Entra access-token validation in front of an HTTP-based MCP server.
• It automatically publishes OAuth Protected Resource Metadata for compatible MCP clients.
• It enforces identity-aware server-, tool-, and action-level policies and keeps the backend private.
• It supports the tested Entra flow patterns for ChatGPT, Claude, Visual Studio Code, and Cursor, with client-specific configuration.
• It does not define the correct business permissions for every MCP tool; your team owns the policy model.
• It does not replace downstream application authorization or automatically preserve user identity across every downstream service.
• It does not apply this remote OAuth pattern to local STDIO MCP servers, which use a different credential model.

Entra ID MCP server FAQ

Does MCP use OAuth 2.1 or OAuth 2.0 with Microsoft Entra ID?

The MCP authorization specification applies OAuth 2.1 security requirements. Microsoft Entra ID documents its endpoints as OAuth 2.0. In this deployment, an interactive MCP client uses Entra's authorization-code flow with PKCE, receives an OAuth access token for the MCP resource, and presents it to Datawiza for validation and MCP-specific authorization.

Can I add Entra ID authentication without changing my MCP server code?

Yes, for an existing HTTP-based MCP server that can be placed behind the gateway. Datawiza handles Entra access-token validation and policy enforcement before forwarding approved requests. Network, DNS, TLS, routing, and client registration still need to be configured.

Do I need separate resource and client app registrations?

For delegated user authentication, the clean pattern uses a resource app for the protected MCP API and a client app for the MCP client and its redirect URIs. App-only workloads use application permissions and may require a separate client or service-principal design.

Does a valid Entra access token authorize every MCP tool?

No. Token validation establishes trusted identity context. Authorization must still decide which MCP server, tool, action, data path, and environment that identity may access.

Does this work with ChatGPT, Claude, Visual Studio Code, Cursor, and autonomous agents?

Datawiza has tested the interactive Entra flow with those four MCP clients. Client registration and redirect settings differ. Autonomous agents can use the same gateway enforcement point with client credentials, delegated access, or an on-behalf-of design appropriate to their identity model.

Does the backend MCP server need to be public?

No. The Datawiza-protected endpoint must be reachable by the MCP client, but the backend MCP server can remain on a private network and accept traffic only from Datawiza Agent Gateway.

Next step

Start with one MCP server and a small set of read-only tools. Confirm Entra token validation, define narrow tool permissions, test denied requests, and review the audit trail before expanding to sensitive write actions or additional servers.

For implementation details, follow the Claude MCP tutorial or ChatGPT MCP tutorial. To review your architecture with an engineer, book a demo.

Explore Datawiza Agent Gateway for centralized identity, least-privilege policy, credential handling, and audit across MCP and API connections.

Related MCP resources

• MCP Gateway for enterprise AI agents
• MCP server authentication and authorization provider guides
• MCP access control
• AI agent access control

Primary technical sources

• Microsoft identity platform access tokens
• Microsoft access-token claims reference
• Configure an application to expose a web API
• Microsoft OAuth 2.0 authorization-code flow
• Microsoft OAuth 2.0 client-credentials flow
• MCP authorization specification (2025-11-25)