Create an OAuth MCP Server with Azure Entra ID

Learn how to create and deploy an OAuth2-authenticated MCP server using Azure Entra ID and fastMCP, then integrate it with TrueFoundry AI Gateway.

This guide demonstrates how to write a MCP server, add OAuth based authentication to it using Azure Entra ID (formerly Azure AD) as the identity provider and then integrate it with the TrueFoundry gateway. The setup below explains both the user authentication and machine-to-machine authentication scenarios:

• User Authentication: Authenticate specific users through the AI Gateway using the Authorization Code flow with refresh tokens
• Machine-to-Machine Authentication: Enable programmatic access without user interaction using the Client Credentials grant flow

The entire code for the steps described below can be found in this Github link: https://github.com/truefoundry/getting-started-examples/tree/main/calculator-oauth-mcp-server

If callers already have an Entra user access token and you need the Gateway to exchange it for a Entra-protected MCP token via On-Behalf-Of, see Azure Entra On-Behalf-Of (OBO) for MCP.

Guide to creating the MCP server and adding OAuth

1. Write a basic MCP Server and test it locally

   Let’s start by writing a basic MCP server that provides a get_me tool.

   server.py

   from fastmcp import FastMCP
   
   mcp = FastMCP("Demo 🚀")
   
   @mcp.tool
   def add(a: int, b: int) -> int:
       """Add two numbers"""
       return a + b
   
   @mcp.tool
   def subtract(a: int, b: int) -> int:
       """Subtract two numbers"""
       return a - b
   
   if __name__ == "__main__":
       mcp.run(transport="streamable-http", stateless_http=True)
   

   Run the server locally:

   python server.py
   

   Your MCP server will be available at http://localhost:8000/mcp. Test the server using this Python script:

   test.py

   import asyncio
   from fastmcp import Client
   
   async def main():
       async with Client("http://127.0.0.1:8000/mcp") as client:
           tools = await client.list_tools()
           print(tools)
           result = await client.call_tool(
               name="add", 
               arguments={"a": 1, "b": 2}
           )
           print(result)
   
   asyncio.run(main())
   

   This MCP server is running without any authentication. Enable OAuth next by registering the server in Microsoft Entra ID, then adding JWT verification to the code.

2. Register the MCP server in Microsoft Entra ID

   Create the resource app, expose scopes, create the client app, and grant API permissions. Follow Microsoft Entra app setup and collect tenant ID, audience (API client ID), client ID, client secret, issuer, JWKS URI, and custom scopes (api://{API_CLIENT_ID}/... plus offline_access).

3. Modify MCP server code to add OAuth Token verification

   Create a .env file to add the environment variables and modify the server.py file to add the JWT verification.

   server.py

   from fastmcp import FastMCP
   import os
   from fastmcp.server.auth.providers.jwt import JWTVerifier
   from dotenv import load_dotenv
   from starlette.requests import Request
   from starlette.responses import RedirectResponse
   
   load_dotenv()
   
   # Configure JWT verification using JWKS
   token_verifier = JWTVerifier(
       jwks_uri=os.getenv("OAUTH_JWKS_URI"),
       issuer=os.getenv("OAUTH_ISSUER"),
       audience=os.getenv("OAUTH_AUDIENCE"),
   )
   
   # Bearer token authentication
   mcp = FastMCP("Demo 🚀", auth=token_verifier)
   
   # Forward .well-known/oauth-authorization-server to Azure's OpenID configuration
   @mcp.custom_route("/.well-known/oauth-authorization-server", methods=["GET", "HEAD", "OPTIONS"], include_in_schema=False)
   async def oauth_well_known(request: Request):
       """Redirect to Azure's OpenID configuration endpoint."""
       return RedirectResponse(os.environ.get("OAUTH_ISSUER") + "/.well-known/openid-configuration", status_code=307)
   
   @mcp.tool
   def add(a: int, b: int) -> int:
       """Add two numbers"""
       return a + b
   
   @mcp.tool
   def subtract(a: int, b: int) -> int:
       """Subtract two numbers"""
       return a - b
   
   if __name__ == "__main__":
       mcp.run(transport="streamable-http", host="0.0.0.0", port=8000, stateless_http=True)
   

   Replace {TENANT_ID} with your Azure tenant ID and {API_CLIENT_ID} with the Application ID of your CalculatorMCPServer app registration.

   Important: The audience should be just the client ID (e.g., 15a6b7c9-1b09-4e1a-9f38-53db81e18b05), not the full api:// URI. Azure tokens contain only the client ID in the aud claim.

4. Get the token and call the MCP server in test.py (Machine-to-Machine authentication)

   In Step 1, we had a script to test the MCP server locally. After adding the OAuth token verification to the MCP server in the previous step, we need to modify the script to get the token and then call the MCP server. If you call the MCP server without a token, it will return a 401 Unauthorized error.

   test.py

   import asyncio
   from fastmcp import Client
   import requests
   
   # Configuration
   TENANT_ID = "12345678-1234-1234-1234-123456789abc"
   TOKEN_ENDPOINT = f"https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token"
   CLIENT_ID = "abcdef12-3456-7890-abcd-ef1234567890"
   CLIENT_SECRET = "your-client-secret"
   SCOPE = "api://9876543-5678-5678-5678-987654321def/.default"  # Note: .default for client credentials
   
   # Request token
   response = requests.post(
       TOKEN_ENDPOINT,
       data={
           "grant_type": "client_credentials",
           "client_id": CLIENT_ID,
           "client_secret": CLIENT_SECRET,
           "scope": SCOPE
       }
   )
   
   print(response.json())
   response.raise_for_status()
   token_data = response.json()
   access_token = token_data["access_token"]
   
   print(f"Access Token: {access_token}")
   print(f"Expires in: {token_data['expires_in']} seconds")
   
   # Call the MCP server
   async def main():
       async with Client("http://localhost:8000/mcp", auth=access_token) as client:
           tools = await client.list_tools()
           print(tools)
           result = await client.call_tool(
               name="add", 
               arguments={"a": 1, "b": 2}
           )
           print(result)
   
   asyncio.run(main())
   

   For client credentials flow with Azure Entra ID, use the scope format api://{client-id}/.default to request all application permissions. The token will contain the short scope names (e.g., calculator.add calculator.subtract) in the scp claim, but you request them using the .default suffix.

   This is exactly how you will be doing Machine-to-Machine authentication to the MCP server. Code snippets to get the token in different ways are outlined below:

   Using cURL

   # Set your values
   TENANT_ID="12345678-1234-1234-1234-123456789abc"
   TOKEN_ENDPOINT="https://login.microsoftonline.com/${TENANT_ID}/oauth2/v2.0/token"
   CLIENT_ID="abcdef12-3456-7890-abcd-ef1234567890"
   CLIENT_SECRET="your-client-secret"
   SCOPE="api://9876543-5678-5678-5678-987654321def/.default"
   
   # Request access token
   curl -X POST "${TOKEN_ENDPOINT}" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "client_id=${CLIENT_ID}" \
     -d "client_secret=${CLIENT_SECRET}" \
     -d "scope=${SCOPE}"
   

   Response:

   {
     "token_type": "Bearer",
     "expires_in": 3599,
     "ext_expires_in": 3599,
     "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc..."
   }
   

   Azure Entra ID uses scope parameter (not audience) and requires the .default suffix for client credentials flow.

   Using Python

   import requests
   
   # Configuration
   TENANT_ID = "12345678-1234-1234-1234-123456789abc"
   TOKEN_ENDPOINT = f"https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token"
   CLIENT_ID = "abcdef12-3456-7890-abcd-ef1234567890"
   CLIENT_SECRET = "your-client-secret"
   SCOPE = "api://9876543-5678-5678-5678-987654321def/.default"
   
   # Request token
   response = requests.post(
       TOKEN_ENDPOINT,
       data={
           "grant_type": "client_credentials",
           "client_id": CLIENT_ID,
           "client_secret": CLIENT_SECRET,
           "scope": SCOPE
       }
   )
   
   response.raise_for_status()
   token_data = response.json()
   access_token = token_data["access_token"]
   
   print(f"Access Token: {access_token}")
   print(f"Expires in: {token_data['expires_in']} seconds")
   

   Using Python with MSAL

   from msal import ConfidentialClientApplication
   
   # Configuration
   TENANT_ID = "12345678-1234-1234-1234-123456789abc"
   CLIENT_ID = "abcdef12-3456-7890-abcd-ef1234567890"
   CLIENT_SECRET = "your-client-secret"
   AUTHORITY = f"https://login.microsoftonline.com/{TENANT_ID}"
   SCOPE = ["api://9876543-5678-5678-5678-987654321def/.default"]
   
   # Create MSAL app
   app = ConfidentialClientApplication(
       CLIENT_ID,
       authority=AUTHORITY,
       client_credential=CLIENT_SECRET
   )
   
   # Acquire token
   result = app.acquire_token_for_client(scopes=SCOPE)
   
   if "access_token" in result:
       access_token = result["access_token"]
       print(f"Access Token: {access_token}")
       print(f"Expires in: {result['expires_in']} seconds")
   else:
       print(f"Error: {result.get('error')}")
       print(f"Description: {result.get('error_description')}")
   
5. Host the MCP server and get the endpoint URL

   Now that we have tested the MCP server locally, we will add it to the AI Gateway to enable user authentication and allow the MCP server to be accessed via the AI Gateway. To add the MCP server to the AI Gateway, we need to get the endpoint URL of the MCP server. Hence, we need to host the MCP server on a public URL.

   If you are using the TrueFoundry AI Deployment product, this can be done by creating a service deployment, choosing your Github repository containing the MCP server code above. Otherwise, you can host it on a VM or a Kubernetes cluster or any hosting provider of your choice.

   Remember to add the environment variables for the MCP server:

   Variable	Value	Description
   OAUTH_JWKS_URI	https://login.microsoftonline.com/{TENANT_ID}/discovery/v2.0/keys	JSON Web Key Set URI for token verification
   OAUTH_ISSUER	https://login.microsoftonline.com/{TENANT_ID}/v2.0	Azure Entra ID issuer URI
   OAUTH_AUDIENCE	{API_CLIENT_ID}	Application (client) ID of your CalculatorMCPServer (API)

   The MCP server only needs these environment variables to validate OAuth tokens. It doesn’t need the Client ID or Client Secret since it’s only validating tokens, not generating them.

   After deployment, you will have the endpoint URL of the MCP server. Let’s consider it https://calculator-oauth-mcp-server.example.com for the rest of the steps. After deploying, check once using the test.py script above by changing the MCP server URL to the deployed URL. You should be able to fetch the tools from the MCP server.

6. Add the MCP server to the TrueFoundry AI Gateway

   You will need to have a MCP server group to be able to add the MCP server to the TrueFoundry AI Gateway. Please refer to the Getting Started guide to create a MCP server group.

   1. In your MCP Server Group, click Add MCP Server

   2. Select Remote MCP

   3. Configure the server:

      • Name: calculator-mcp-azure-oauth
      • Description: OAuth-authenticated MCP server with Azure Entra ID
      • URL: Your deployed service endpoint (e.g., https://calculator-oauth-mcp-server.example.com/mcp)
      • Transport: streamable-http
      • Authentication Type: Select OAuth2

   4. In the OAuth2 configuration section, provide the Azure credentials:

      • OAuth2 Client ID: Your CalculatorMCPClient application client ID
      • OAuth2 Client Secret: Your CalculatorMCPClient client secret

   The AI Gateway will automatically discover the OAuth2 Authorization URL, Token URL, and other configuration details from your MCP server’s /.well-known/oauth-authorization-server endpoint once you provide the MCP server URL.

   Important - Azure Custom Scopes: Azure’s well-known endpoint only includes generic OpenID scopes (openid, profile, email, offline_access). You must manually add your custom API scopes in the OAuth2 configuration:

   • OAuth2 Scopes: Manually enter your scopes in the format:
     • api://{API_CLIENT_ID}/calculator.add
     • api://{API_CLIENT_ID}/calculator.subtract
     • offline_access (to enable automatic token refresh)

   Replace {API_CLIENT_ID} with your CalculatorMCPServer Application (client) ID (e.g., api://15a6b7c9-1b09-4e1a-9f38-53db81e18b05/calculator.add).

   You can also store the client id and secrets in truefoundry secrets and reference them by FQN in the configuration.

   5. Set access control: Select teams or users who should have access to this MCP server

   Managers of the MCP Server Group automatically have access to all servers in the group.

   

   6. Click Save to add the MCP server
      • The server will appear in your MCP Server Group
      • Users can now connect and use the server through the AI Gateway
7. Test the MCP server in the Playground

   1. Navigate to the Playground in the AI Gateway
   2. Click Add Tool/MCP Servers
   3. Find your calculator-mcp-azure-oauth in the list
   4. Click Connect Now to initiate OAuth authorization

   

   5. You’ll be redirected to Azure to authorize access
   6. Sign in with your Azure account and consent to the requested permissions
   7. You’ll be redirected back to the AI Gateway
   8. The AI Gateway will store your OAuth tokens securely and refresh them automatically when they expire
   9. You’ll see the add and subtract tools from your MCP server
   10. Select the tools and click Done
   11. Try sending a prompt like Add 1 and 2. Use the tools provided
   12. The tool will return the result from your MCP server