Azure API Management Gateway with Entra ID Authentication MCP server

This guide demonstrates how to set up and use a secure MCP (Model Context Protocol) server using Azure API Management as an AI Gateway. The solution implements the latest MCP Authorization specification, providing a secure way to deploy and access MCP servers.

Prerequisites

Before deploying the Remote MCP Server, ensure you have:

• Azure subscription
• Azure CLI installed
• Azure Developer CLI (azd) installed

Installation

Registering Resource Provider

First, register the required resource provider:

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

# OR using Azure PowerShell
Register-AzResourceProvider -ProviderNamespace Microsoft.App

# Check registration status (PowerShell)
(Get-AzResourceProvider -ProviderNamespace Microsoft.App).RegistrationState

Deploying the Solution

Deploy the complete solution using Azure Developer CLI:

azd up

This command provisions:

• Azure API Management service (the AI Gateway)
• Azure Function App with MCP server implementation
• All required supporting resources

The deployment will output the URLs for your API Management endpoints that you'll need for testing.

Testing with MCP Inspector

To verify your deployment is working properly:

1. Install and run MCP Inspector:

npx @modelcontextprotocol/inspector

2. Open the MCP Inspector web application by clicking the URL displayed in the terminal (typically http://127.0.0.1:6274/#resources)

3. Configure the inspector:

   • 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

4. Click List Tools to see available tools

5. Select a tool and click Run Tool to test functionality

Understanding the Architecture

The deployed solution provides a secure MCP server with multiple security layers:

Security Features

• OAuth 2.0/PKCE Authentication Flow: Implements the MCP Authorization specification
• API Management Gateway: Handles authentication, authorization, and routing
• Azure Functions Backend: Executes MCP tools and operations
• Managed Identities: Eliminates need for service credentials

Key Components

• OAuth API (/oauth/*): Implements the OAuth 2.0 authorization server
• MCP API (/mcp/*): Provides the actual MCP protocol endpoints
• Azure Function App: Hosts the MCP server implementation
• Storage Account: Stores function code and application data

The system employs multiple security layers:

• OAuth 2.0/PKCE authentication with Entra ID
• Encrypted session keys for secure access
• Function-level security with host keys
• Azure platform security mechanisms

Usage Scenarios

The MCP server can be used for various AI operations through the standardized MCP protocol. Common scenarios include:

• Accessing AI tools through a secure, standardized interface
• Managing tool access permissions through OAuth consent flows
• Running AI operations with proper authentication and authorization
• Integrating with existing MCP-compatible clients

The solution is designed to work with any MCP-compatible client, providing a secure way to access AI capabilities through the Model Context Protocol.

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