Azure API Management Gateway with Entra ID Authentication MCP server for AI agents

This article provides step-by-step instructions for setting up and using a secure MCP (Model Context Protocol) server with Azure API Management. The solution creates a secure gateway that implements the MCP Authorization specification, allowing for authenticated access to AI models and tools.

Deployment Instructions

Prerequisites

Before deploying the MCP server, ensure you have:

Registered the required Azure resource provider:

# Using Azure CLI
az provider register --namespace Microsoft.App --wait

# Using Azure PowerShell
Register-AzResourceProvider -ProviderNamespace Microsoft.App
# Check registration status after some time
(Get-AzResourceProvider -ProviderNamespace Microsoft.App).RegistrationState

Installed the Azure Developer CLI (azd) from https://aka.ms/azd

Deployment Steps

Deploy all required Azure resources (API Management service, Function App, and supporting infrastructure) with a single command:

azd up

This command will:

Provision all necessary Azure resources
Deploy the MCP server code to Azure Functions
Configure API Management as the AI Gateway
Set up the proper security and authentication flows

Testing the MCP Server

Using MCP Inspector

Install and launch the MCP Inspector tool:
```
npx @modelcontextprotocol/inspector
```
Open the MCP Inspector web app by CTRL-clicking the URL displayed in the terminal (typically http://127.0.0.1:6274/#resources)
Configure the connection:
- Set the transport type to SSE
- Enter your API Management endpoint URL:
```
https://<apim-servicename-from-azd-output>.azure-api.net/mcp/sse
```
Click Connect to establish a connection to your MCP server
Click List Tools to see available tools
Select a tool and click Run Tool to test its functionality

Architecture Overview

The deployed solution includes:

Azure API Management - Acts as the central security gateway handling authentication, authorization, and request routing
Azure Function App - Hosts the MCP server implementation in Python 3.11
Azure Storage Account - Provides storage for function app code and application data
Managed Identities - Enables secure service-to-service authentication without secrets
Application Insights - Provides monitoring and telemetry

Security Features

The MCP server implements the following security measures:

OAuth 2.0/PKCE authentication flows per MCP specification
Session key encryption/decryption for secure API access
Request validation and proper header injection
Managed identities for secure service-to-service authentication
Optional network isolation with private endpoints

Using the MCP API

The MCP server exposes two main endpoints:

Server-Sent Events Endpoint

Used for establishing real-time communication:

GET https://<apim-servicename>.azure-api.net/mcp/sse

This endpoint requires a valid encrypted session token in the Authorization header.

Message Endpoint

Used for sending MCP protocol messages:

POST https://<apim-servicename>.azure-api.net/mcp/message

This endpoint handles tool invocations and other MCP protocol messages. It also requires proper authorization.

Both endpoints enforce a comprehensive security policy that validates and decrypts session keys, performs token validation, and ensures proper backend authentication.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "remote-mcp-apim-functions-python" '{"command":"npx","args":["@modelcontextprotocol/client"],"transport":"sse","url":"https://{apim-servicename}.azure-api.net/mcp/sse"}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "remote-mcp-apim-functions-python": {
            "command": "npx",
            "args": [
                "@modelcontextprotocol/client"
            ],
            "transport": "sse",
            "url": "https://{apim-servicename}.azure-api.net/mcp/sse"
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "remote-mcp-apim-functions-python": {
            "command": "npx",
            "args": [
                "@modelcontextprotocol/client"
            ],
            "transport": "sse",
            "url": "https://{apim-servicename}.azure-api.net/mcp/sse"
        }
    }
}

3. Restart Claude Desktop for the changes to take effect