Connect to MCP using Microsoft Entra ID¶

Connect Claude or ChatGPT to the Timextender MCP Server using your own Microsoft Entra ID tenant as the identity provider, so users sign in with OAuth 2.1 instead of an API key.

Prerequisites¶

• A Microsoft Entra ID tenant you can register applications in.
• A deployed MCP Server, reachable over HTTPS at a public hostname.
• Rights to add a connector in Claude or ChatGPT. Both desktop apps use a connector created in the browser, so you need browser access for either one.
• The Azure CLI, installed and signed in. Run az login and select the tenant you are configuring.
• Administrator access to the MCP Server host, to run the Timextender MCP Configurator.

Entra ID supports neither Dynamic Client Registration nor Client ID Metadata Documents, so an MCP client cannot register itself. You create the client application in advance and give the connector its ID and secret. If your identity provider is Auth0, use Connect to MCP using Auth0 instead.

Check the rights you need¶

Run this to find out whether you need a directory role:

az rest --method get --url 'https://graph.microsoft.com/v1.0/policies/authorizationPolicy' --query "defaultUserRolePermissions.allowedToCreateApps"

Global Administrator is not required. Consent is not required either, because you pre-authorize the client application on the server application, which removes the consent step.

Understanding the two app registrations¶

This procedure creates two Entra ID app registrations with different jobs. Both have an Application (client) ID, which is Entra ID's label for any registration's identifier.

Each registration references the other once, in opposite directions. On the client application you add a permission pointing at the server application. On the server application you pre-authorize the client application. Both registrations are single tenant.

Register one server application per MCP Server deployment. The token's aud claim is the server application's identifier, so two deployments sharing one registration would each accept tokens issued for the other. The client application holds only redirect URIs and a delegated permission, and can be shared across your deployments.

Register the server application¶

1. Go to Entra ID > App registrations > New registration.
2. Enter a name that identifies the deployment, select Accounts in this organizational directory only, and select Register. Do not add a redirect URI. This registration never has one.
3. Go to Expose an API > Application ID URI > Add, and accept the default value of api://<server-app-client-id>.
4. Select Add a scope. Enter mcp.access as the scope name, leave Who can consent set to Admins only, and complete the four display name and description fields. Your users read these in the Microsoft consent dialog, so write them for that audience, for example "Query your data through the MCP server".
5. Set the access token version to 2. See Set the access token version below.
6. Go to App roles > Create app role and add MCP.Query and MCP.Admin, both with allowed member type Users/Groups. Do not assign them to anyone.

Server application Overview blade, showing the Application (client) ID and the Application ID URI.

Expose an API blade on the server application, showing the mcp.access delegated scope.

The Edit a scope panel, showing mcp.access with its consent display names and descriptions completed.

Record the Application (client) ID from this registration's Overview blade. You enter it into the MCP Server configuration later.

The app roles are defined for future use. Nothing reads them yet, and a token issued to an unassigned user carries no roles claim. Defining them now means you do not have to change the registration when role based authorization is added.

Set the access token version¶

The access token version is not exposed as a form field. You set it by editing the registration's JSON manifest.

1. Go to Entra ID > App registrations > your server application > Manifest.
2. Find the token version key and set it to 2. The key has two names, and which one appears depends on which manifest editor your tenant serves.
3. Select Save, reload the blade, and confirm the value was saved.

Manifest editor on the server application, with the access token version set to 2.

App roles blade on the server application, showing MCP.Query and MCP.Admin.

Register the client application¶

1. Go to Entra ID > App registrations > New registration.
2. Enter a name, select Accounts in this organizational directory only, and select Register.
3. Go to Authentication > Add a platform > Web, and add the callback URLs for the client you are setting up. See Callback URLs below. Clear both Implicit grant checkboxes.
4. Go to Authentication > Advanced settings and turn off Allow public client flows.
5. Go to Certificates & secrets > New client secret. Enter a description and an expiry, select Add, then copy the Value immediately. Entra ID shows it once.
6. Go to API permissions > Add a permission > My APIs, select your server application, select Delegated permissions, select mcp.access, then select Add permissions. No consent is needed.

Authentication blade on the client application, showing the callback URLs under the Web platform.

API permissions blade on the client application, showing the delegated mcp.access permission.

Record the Application (client) ID from this registration. You enter it into the connector dialog later.

Use the Web platform. Claude and ChatGPT redeem the authorization code from their own backends, and Web is the platform that accepts a backend redemption. It also makes the registration a confidential client, which is why the client secret is required.

Callback URLs¶

Add both Claude URIs. The client uses one or the other depending on which domain the user is on, and a missing URI produces an intermittent failure that follows the user rather than the configuration.

Entra ID does not support wildcards in redirect URIs, so each ChatGPT connector needs its own entry. A workspace level connector is a single entry shared by everyone in the workspace.

The value of an existing secret cannot be retrieved from the portal, the Azure CLI or Microsoft Graph. If you lose it, create a replacement:

az ad app credential reset --id <client-app-client-id> --append --display-name "<credential-name>" --years 1 --query password -o tsv

Pre-authorize the client application¶

1. Go to Entra ID > App registrations > your server application > Expose an API.
2. Under Authorized client applications, select Add a client application.
3. Enter the client application's Application (client) ID, select mcp.access, and select Add application.

Authorized client applications on the server application, with the client application added and mcp.access selected.

Pre-authorization makes the delegated permission usable without consent from a user or an administrator, even though mcp.access is marked as requiring admin consent. This is what keeps the procedure within the rights described in Check the rights you need.

Verify the registrations¶

Run these commands and compare the output against the expected results. Both checks work before the MCP Server is deployed.

az ad app show --id <server-app-client-id> --query "{appIdUri:identifierUris, tokenVersion:api.requestedAccessTokenVersion, scopes:api.oauth2PermissionScopes[].value, roles:appRoles[].value, spa:spa.redirectUris, web:web.redirectUris, publicClient:publicClient.redirectUris}"

az ad app show --id <client-app-client-id> --query "{web:web.redirectUris, spa:spa.redirectUris, publicClient:publicClient.redirectUris, requests:requiredResourceAccess[].resourceAppId, appIdUri:identifierUris}"

az ad app show --id <client-app-client-id> --query "passwordCredentials[].{name:displayName, expires:endDateTime}"

az ad app show --id <server-app-client-id> --query "api.preAuthorizedApplications"

A redirect URI on the server application, or an empty web list on the client application, means the two registrations have been swapped. Review Understanding the two app registrations.

Two entries in requests is expected. One is your server application. The other is Microsoft Graph, which Entra ID adds to every new registration along with a default User.Read permission. It plays no part here and does not need removing.

Verify the token claims¶

A token that decodes correctly confirms your tenant configuration, so any later failure is in the MCP Server configuration or the connector.

$token = az account get-access-token --scope "api://<server-app-client-id>/mcp.access" --query accessToken -o tsv

$payload = $token.Split('.')[1].Replace('-','+').Replace('_','/')
while ($payload.Length % 4 -ne 0) { $payload += '=' }
[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($payload)) |
    ConvertFrom-Json | Select-Object iss, aud, scp, ver, azp, appid, azpacr, roles | Format-List

The Azure CLI is itself a client, so it needs pre-authorizing on your server application for this check. Remove it afterwards. It is not part of the deployed configuration.

Record the aud value. It is the server application's Application (client) ID, and it goes into the MCP Server's Audience setting. It is not the client application's ID.

Configure the MCP Server¶

Complete this on the machine that runs the MCP Server.

1. Open the Timextender MCP Configurator.
2. Go to the OAuth tab.
3. For Identity provider, select Microsoft Entra ID.
4. Complete the fields listed below.
5. Turn on Enable OAuth sign-in.
6. Select Save Configuration, and restart the service when prompted.

The OAuth tab in the Timextender MCP Configurator, with Microsoft Entra ID selected and the fields completed.

There is no Client ID field. Under Entra ID the MCP Server never holds one. It goes into the connector dialog instead.

API key authentication continues to work whether or not OAuth is turned on. Turning on OAuth adds a second way to authenticate.

Use the Configurator rather than editing files. It runs the server's validators before writing, so it cannot save a configuration the server would refuse to start on. Selecting Microsoft Entra ID also turns off the Client ID Metadata Document advertisement, because Entra ID supports neither that nor Dynamic Client Registration.

Which value goes where¶

Where the settings are stored¶

After restarting, confirm the startup log records Resource-server identity provider: EntraId with no configuration error above it.

The server fails closed on invalid configuration. A /common or /organizations authority, a blank or placeholder value, a scope that is not an absolute api:// URI, or scopes naming two different applications each make the server refuse to start and name the setting. A missing /v2.0 suffix or a non-GUID audience produce warnings only, because a tenant issuing version 1 tokens legitimately uses those forms.

Connect Claude¶

Complete every preceding section first. The first connection attempt against a URL fixes what the client stores about that URL.

1. In Claude, add a custom connector.
2. Enter a name, and enter your server's /mcp endpoint as the Server URL, for example https://<your-mcp-server-host>/mcp.
3. Continue to the OAuth options.
4. For Sign-in, select Sign in now.
5. For OAuth client, select Use your own OAuth client.
6. Enter the client application's Application (client) ID as the Client ID, and the client secret as the Client secret.
7. Complete the connector and sign in when prompted.

Claude's Add custom connector dialog, with a name and the server's /mcp URL entered.

Claude's OAuth client settings, with Sign in now and Use your own OAuth client selected and the client ID and secret entered.

The dialog has no endpoint or scope fields. Claude reads the authorization endpoint, token endpoint and scope from your MCP Server's metadata, which is why the server configuration must be complete first.

When the connector is connected, the MCP Server's five read-only tools are listed and can be called. Two log entries on a successful connection are expected: a server/discover handler failure, because the client calls a method this server does not implement and the request is answered anyway, and a 401 immediately after a successful tool call, which is the probe that starts the OAuth flow.

Claude Desktop uses the connector you created in the browser. There is nothing else to configure.

Connect ChatGPT¶

ChatGPT requires one redirect URI per connector, added to the client application before you sign in.

1. In ChatGPT, go to Settings > Apps & Connectors > Advanced settings > Developer mode, then select Create.
2. Enter your server's /mcp endpoint as the Connection URL.
3. For Authentication, select OAuth, then open Advanced OAuth settings.
4. For Registration method, select User-Defined OAuth Client. ChatGPT reports the other two methods as unavailable.
5. Copy the Callback URL that ChatGPT displays, and add it to the client application's Web redirect URIs in Entra ID. See Register the client application.
6. Enter the client application's Application (client) ID as the OAuth Client ID, and the client secret as the OAuth Client Secret. The secret is required despite the field being labelled optional.
7. Set Token endpoint auth method to client_secret_post, leave the pre-selected default scope of api://<server-app-client-id>/mcp.access selected, set Base scopes to offline_access, then select Create and sign in when prompted.

ChatGPT's connector dialog in User-Defined OAuth Client mode, with the server URL and client ID entered.

ChatGPT's prompt to sign in with the MCP Server connector.

You do not enter any OAuth endpoints. The MCP Server serves your tenant's authorization server document, so ChatGPT finds the authorize and token endpoints itself.

ChatGPT Desktop uses the connector you created in the browser. There is nothing else to configure.

Troubleshooting¶

Several of these produce an identical 401 response, so match on the distinguishing observable rather than trying fixes in turn. Start with the server's startup log, which names most configuration errors, and a decoded token.

Recover a client that cached the wrong metadata¶

This failure has a distinctive signature: a correctly configured server, a generic credentials or permissions error, and no entries in the server log, because the failure occurs at Entra ID before your server is contacted.

To read the underlying error code, open your browser's developer tools, turn on Preserve log before signing in, and inspect the redirect back from Microsoft. The provider's code appears in the error return URL as entra_aadsts_code. A code of AADSTS9010010 with a resource parameter naming your server's URL confirms this failure. Under a correct setup the authorize request carries no resource parameter.

The only known recovery is to give the MCP Server a new hostname. The cached state is held against the origin, not against a connector record, so deleting the connector does not clear it.

The organization level Connectors list with the overflow menu open, showing Delete and Refresh tools list.

Conditional Access policies¶

If you hold Global Reader or a security role, you can list the tenant's policies:

az rest --method get --url 'https://graph.microsoft.com/v1.0/identity/conditionalAccess/policies?$select=displayName,state'

A Forbidden or AccessDenied response is expected when you hold only application registration rights. The error names the roles that would allow you to read the policies. In that case, ask whoever administers Conditional Access whether any policy requires a compliant or hybrid joined device for users signing in to a new cloud application, and whether that application can be excluded.

A tenant without Entra ID P1 or P2 cannot have Conditional Access policies, so an empty result means the policies are untested rather than absent. Adding a licence and a policy later reintroduces this.

Related articles¶

• Connect to MCP using Auth0
• Configure HTTPS for MCP Server
• Connect to MCP using HTTP Mode
• Manage API Keys for MCP Server
• Connect Prepare Instance to Microsoft Fabric