DEV Community: René Nijkamp

Azure APIM MCP Audit Logging Without Breaking Everything

René Nijkamp — Wed, 03 Dec 2025 17:19:36 +0000

Azure APIM MCP Audit Logging Without Breaking Everything

In Part 2, we locked down security. Now let's talk about observability.

You need audit logging for compliance. You need distributed tracing for debugging. You need error handling for production resilience.

Here's the problem: by default, you have none of that.

Out of the box, APIM passes MCP requests through with zero logging. You have no idea if someone's calling tools/list or tools/call. You can't tell which API requests are actually MCP traffic. No audit trail. No visibility. Just requests flowing through in the dark. Not what you want, not what compliance wants, not what security wants.

And when you try to add logging? That's when you discover the fun part: accessing the response body in APIM policies causes requests to hang indefinitely.

I found this out the hard way. Days of debugging. Requests hanging. Timeouts everywhere. The fix? Don't touch the response body. Ever.

This issue has been reported to Microsoft,it is on their radar. But here's the reality: MCP servers are in preview. When you work with preview functionality, you carry the burden of working around these rough edges yourself. That's the tax you pay for being early.

Let me show you how to get the observability you need, without the trial and erroring I went through.

Observability Architecture

The Response Body Problem

What You'd Normally Do

In a typical APIM setup, especially during development, you'd log the response body:

<outbound>
    <log-to-eventhub logger-id="my-logger">
        @{
            return new JObject(
                new JProperty("request", context.Request.Body.As<string>()),
                new JProperty("response", context.Response.Body.As<string>())  // HANGS
            ).ToString();
        }
    </log-to-eventhub>
</outbound>

This will hang your requests. The response never completes. Clients timeout.

Why This Happens

When you access context.Response.Body in the <outbound> section:

I dont have access to the APIM MCP internals, but: I suspect that APIM MCP tries to buffer the entire response, which can be large, which can be streaming. If its in memory buffer, it might just trigger errors there. If its streaming, it will block until everything is read, which is not going to happen until the client reads it... In short, a deadlock, no bueno, and you break production.

The frustrating part? This behavior isn't called out clearly in the main policy documentation. The policy is saved without any warnings, and you wonder why suddenly you get timeout errors. After a lot of trial and error, or if you're lucky, someone (Hi there ;) ) warns you first. Probably just one of those things that happens in preview.

Microsoft is aware of this issue, it's been reported and is on their radar.

The good news: there's a reliable workaround that gives you everything compliance needs.

The Solution: Log Metadata, Not Payloads

You can't log response bodies. Fine. Log everything else instead—and it turns out that's exactly what you need for compliance anyway:

<outbound>
    <log-to-eventhub logger-id="mcp-audit-logger">
        @{
            var mcpMethod = "";
            var mcpId = "";

            // Extract MCP method from request body (safely)
            try {
                var requestBody = context.Request.Body.As<JObject>(preserveContent: true);
                mcpMethod = requestBody["method"]?.ToString() ?? "";
                mcpId = requestBody["id"]?.ToString() ?? "";
            } catch {
                mcpMethod = "parse-error";
            }

            return new JObject(
                // Request metadata
                new JProperty("timestamp", DateTime.UtcNow.ToString("o")),
                new JProperty("requestId", context.RequestId),
                new JProperty("subscriptionId", context.Subscription?.Id ?? "none"),
                new JProperty("subscriptionName", context.Subscription?.Name ?? "none"),

                // MCP-specific
                new JProperty("mcpMethod", mcpMethod),
                new JProperty("mcpId", mcpId),

                // Response metadata (SAFE - no body access)
                new JProperty("statusCode", context.Response.StatusCode),
                new JProperty("statusReason", context.Response.StatusReason),

                // Timing
                new JProperty("elapsedMs", context.Elapsed.TotalMilliseconds),

                // Client info
                new JProperty("clientIp", context.Request.IpAddress),
                new JProperty("userAgent", context.Request.Headers.GetValueOrDefault("User-Agent", ""))
            ).ToString();
        }
    </log-to-eventhub>
    <base />
</outbound>

Key points:

context.Request.Body.As<JObject>(preserveContent: true) is safe in <outbound>
context.Response.StatusCode is safe
context.Response.Body is NOT safe
Wrap parsing in try-catch for malformed requests
If you have any other headers you want to log, you can add them quite easily to the JObject.

Logging Tool Discovery

Tracking who is executing tools is needed, but what about who's discovering your tools?. Who hasnt seen the IP port scans in his life, this is not much else than that. To log these activities, a policy snippet needs to be added to the Inbound section, since this request will never hit any outbound services (and therefore policies)

<inbound>
    <!-- After security checks, before backend -->
    <choose>
        <when condition="@(context.Request.Body.As<JObject>(preserveContent: true)["method"]?.ToString() == "tools/list")">
            <log-to-eventhub logger-id="mcp-audit-logger" partition-id="0">
                @{
                    return new JObject(
                        new JProperty("eventType", "discovery"),
                        new JProperty("timestamp", DateTime.UtcNow.ToString("o")),
                        new JProperty("requestId", context.RequestId),
                        new JProperty("subscriptionId", context.Subscription?.Id ?? "none"),
                        new JProperty("subscriptionName", context.Subscription?.Name ?? "none"),
                        new JProperty("clientIp", context.Request.IpAddress),
                        new JProperty("userAgent", context.Request.Headers.GetValueOrDefault("User-Agent", "")),
                        new JProperty("mcpMethod", "tools/list")
                    ).ToString();
                }
            </log-to-eventhub>
        </when>
    </choose>
</inbound>

Why log discovery separately?

Security monitoring: Who is checking for tools, and are they allowed to. It can be a forgotten attack surface. So better log it.
Usage analytics: Track which clients are discovering vs actually using tools. If there is an overload of tool discovery calls, you might have an issue in one of your agents.
Compliance: Auditors want to know who accessed what capabilities, even if they didn't invoke them
Performance: Separate partition for discovery logs (partition-id="0") keeps them isolated from invocation logs

This gives you the complete picture: discovery → invocation → response → errors.

Setting Up Event Hub Logging

Reality check: You need Event Hub for production audit logging. Application Insights alone won't give you the retention, queryability, and compliance guarantees you need. Yes, it's another Azure service. Yes, it adds complexity. But it's the right tool for immutable audit trails. Event Hub also very easily integrates with tools like Datadog or Grafana, or whatever SIEM you use for your end product.

If you're running a small pilot, you can skip this and use App Insights only. For regulated environments? Event Hub is non-negotiable.

1. Create Event Hub

# Variables
RESOURCE_GROUP="rg-apim-mcp"
LOCATION="westeurope"
EVENTHUB_NAMESPACE="eh-apim-mcp-logs"
EVENTHUB_NAME="mcp-audit-logs"

# Create namespace
az eventhubs namespace create \
  --resource-group $RESOURCE_GROUP \
  --name $EVENTHUB_NAMESPACE \
  --location $LOCATION \
  --sku Standard

# Create event hub
az eventhubs eventhub create \
  --resource-group $RESOURCE_GROUP \
  --namespace-name $EVENTHUB_NAMESPACE \
  --name $EVENTHUB_NAME \
  --partition-count 4 \
  --message-retention 7

# Get connection string
az eventhubs namespace authorization-rule keys list \
  --resource-group $RESOURCE_GROUP \
  --namespace-name $EVENTHUB_NAMESPACE \
  --name RootManageSharedAccessKey \
  --query primaryConnectionString -o tsv

2. Create APIM Logger

# Get APIM instance
APIM_NAME="apim-mcp-prod"

# Create logger
az apim logger create \
  --resource-group $RESOURCE_GROUP \
  --service-name $APIM_NAME \
  --logger-id "mcp-audit-logger" \
  --logger-type azureEventHub \
  --connection-string "Endpoint=sb://eh-apim-mcp-logs.servicebus.windows.net/;..." \
  --description "MCP audit logging"

Or via Azure Portal:

Navigate to your APIM instance
APIs → Loggers → + Add
Name: mcp-audit-logger
Type: Azure Event Hub
Connection string: (paste from above)
Create

3. Configure Named Values (Optional)

If you're managing multiple environments (dev/staging/prod), use named values. If you're just testing, hard-code it and move on:

az apim nv create \
  --resource-group $RESOURCE_GROUP \
  --service-name $APIM_NAME \
  --named-value-id "audit-logger-id" \
  --display-name "audit-logger-id" \
  --value "mcp-audit-logger"

Then reference in policy:

<log-to-eventhub logger-id="{{audit-logger-id}}">

Complete Production Logging Policy

Here's the full policy with audit logging integrated:

<policies>
    <inbound>
        <!-- Security policies from Part 2 -->
        <choose>
            <when condition="@(context.Request.Headers.GetValueOrDefault(\"Ocp-Apim-Subscription-Key\", \"\") == \"\")">
                <return-response>
                    <set-status code="401" reason="Unauthorized" />
                    <set-body>{"error": "Subscription key required"}</set-body>
                </return-response>
            </when>
        </choose>

        <set-variable name="originalSubKey" 
                      value="@(context.Request.Headers.GetValueOrDefault(\"Ocp-Apim-Subscription-Key\", \"\"))" />
        <set-variable name="originalJwtToken" 
                      value="@(context.Request.Headers.GetValueOrDefault(\"Authorization\", \"\"))" />

        <!-- Store request timestamp for elapsed time calculation -->
        <set-variable name="requestStartTime" value="@(DateTime.UtcNow)" />

        <base />

        <rate-limit calls="100" renewal-period="60" />

        <choose>
            <when condition="@(context.Subscription == null || context.Subscription.Id == null)">
                <return-response>
                    <set-status code="401" reason="Unauthorized" />
                    <set-body>{"error": "Invalid subscription key"}</set-body>
                </return-response>
            </when>
        </choose>

        <set-header name="Ocp-Apim-Subscription-Key" exists-action="override">
            <value>@((string)context.Variables["originalSubKey"])</value>
        </set-header>
        <set-header name="Authorization" exists-action="override">
            <value>@((string)context.Variables["originalJwtToken"])</value>
        </set-header>

        <!-- Distributed tracing - preserve existing or generate new -->
        <set-header name="X-Request-ID" exists-action="skip">
            <value>@(context.RequestId)</value>
        </set-header>

        <!-- Log tool discovery requests -->
        <choose>
            <when condition="@(context.Request.Body.As<JObject>(preserveContent: true)["method"]?.ToString() == "tools/list")">
                <log-to-eventhub logger-id="mcp-audit-logger" partition-id="0">
                    @{
                        return new JObject(
                            new JProperty("eventType", "discovery"),
                            new JProperty("timestamp", DateTime.UtcNow.ToString("o")),
                            new JProperty("requestId", context.RequestId),
                            new JProperty("subscriptionId", context.Subscription?.Id ?? "none"),
                            new JProperty("subscriptionName", context.Subscription?.Name ?? "none"),
                            new JProperty("clientIp", context.Request.IpAddress),
                            new JProperty("userAgent", context.Request.Headers.GetValueOrDefault("User-Agent", "")),
                            new JProperty("mcpMethod", "tools/list")
                        ).ToString();
                    }
                </log-to-eventhub>
            </when>
        </choose>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <!-- Audit logging (SAFE - no response body access) -->
        <log-to-eventhub logger-id="mcp-audit-logger">
            @{
                var mcpMethod = "";
                var mcpId = "";
                var userId = "";

                // Extract MCP details
                try {
                    var requestBody = context.Request.Body.As<JObject>(preserveContent: true);
                    mcpMethod = requestBody["method"]?.ToString() ?? "";
                    mcpId = requestBody["id"]?.ToString() ?? "";
                } catch {
                    mcpMethod = "parse-error";
                }

                // Extract user ID from JWT (if present)
                try {
                    var authHeader = context.Request.Headers.GetValueOrDefault("Authorization", "");
                    if (!string.IsNullOrEmpty(authHeader) && authHeader.StartsWith("Bearer ")) {
                        var token = authHeader.Substring(7);
                        var jwt = System.IdentityModel.Tokens.Jwt.JwtSecurityTokenHandler.ReadJwtToken(token);
                        userId = jwt.Claims.FirstOrDefault(c => c.Type == "sub")?.Value ?? "";
                    }
                } catch {
                    userId = "jwt-parse-error";
                }

                return new JObject(
                    // Timestamps
                    new JProperty("timestamp", DateTime.UtcNow.ToString("o")),
                    new JProperty("requestStartTime", ((DateTime)context.Variables["requestStartTime"]).ToString("o")),

                    // Request metadata
                    new JProperty("requestId", context.RequestId),
                    new JProperty("operationId", context.Operation?.Id ?? ""),
                    new JProperty("apiId", context.Api?.Id ?? ""),

                    // Subscription details
                    new JProperty("subscriptionId", context.Subscription?.Id ?? "none"),
                    new JProperty("subscriptionName", context.Subscription?.Name ?? "none"),

                    // User context
                    new JProperty("userId", userId),
                    new JProperty("clientIp", context.Request.IpAddress),
                    new JProperty("userAgent", context.Request.Headers.GetValueOrDefault("User-Agent", "")),

                    // MCP-specific
                    new JProperty("mcpMethod", mcpMethod),
                    new JProperty("mcpId", mcpId),

                    // Response metadata (SAFE)
                    new JProperty("statusCode", context.Response.StatusCode),
                    new JProperty("statusReason", context.Response.StatusReason),

                    // Performance
                    new JProperty("elapsedMs", context.Elapsed.TotalMilliseconds),
                    new JProperty("backendTimeMs", context.Response.Headers.GetValueOrDefault("X-Backend-Time", "0")),

                    // Errors
                    new JProperty("isError", context.Response.StatusCode >= 400),
                    new JProperty("lastError", context.LastError?.Message ?? "")
                ).ToString();
            }
        </log-to-eventhub>

        <!-- Response headers - return the request ID (original or generated) -->
        <set-header name="X-Request-ID" exists-action="skip">
            <value>@(context.Request.Headers.GetValueOrDefault("X-Request-ID", context.RequestId))</value>
        </set-header>
        <set-header name="X-RateLimit-Limit" exists-action="override">
            <value>100</value>
        </set-header>
        <set-header name="X-RateLimit-Window" exists-action="override">
            <value>60</value>
        </set-header>

        <base />
    </outbound>
    <on-error>
        <!-- Error logging -->
        <log-to-eventhub logger-id="mcp-audit-logger">
            @{
                return new JObject(
                    new JProperty("timestamp", DateTime.UtcNow.ToString("o")),
                    new JProperty("requestId", context.RequestId),
                    new JProperty("subscriptionId", context.Subscription?.Id ?? "none"),
                    new JProperty("isError", true),
                    new JProperty("errorSource", context.LastError?.Source ?? ""),
                    new JProperty("errorReason", context.LastError?.Reason ?? ""),
                    new JProperty("errorMessage", context.LastError?.Message ?? ""),
                    new JProperty("statusCode", context.Response.StatusCode),
                    new JProperty("elapsedMs", context.Elapsed.TotalMilliseconds)
                ).ToString();
            }
        </log-to-eventhub>

        <base />
    </on-error>
</policies>

Distributed Tracing

Request ID Propagation

Of course you want to be able to trace a request from end-to-end. Because, whats the use otherwise besides just burning money on logs?
The policy above includes:

<!-- Inbound: Preserve existing or generate new -->
<set-header name="X-Request-ID" exists-action="skip">
    <value>@(context.RequestId)</value>
</set-header>

<!-- Outbound: Return the request ID (original or generated) -->
<set-header name="X-Request-ID" exists-action="skip">
    <value>@(context.Request.Headers.GetValueOrDefault("X-Request-ID", context.RequestId))</value>
</set-header>

Use exists-action="skip" instead of "override". This preserves any X-Request-ID that's already present from upstream services (AI agents, proxies, gateways). Only generate a new one if it doesn't exist.

THe part in outbound makes sure we actually send this to the backend service, of course its your responsibility that it uses that ID for its own logging, and propagates it downstream as well.
We dont want to break the chain.

What to Monitor

Once Event Hub is streaming your logs, pipe them to whatever observability platform you're using:

Common destinations:

Grafana Cloud - Event Hub → Grafana Alloy → Grafana Cloud (uses Loki backend)
Datadog - Event Hub → Azure Function forwarder → Datadog
Splunk - Event Hub → Splunk HEC connector
Application Insights - Built-in Azure integration if you're all-in on Azure

The Event Hub JSON format (shown in the policy above) works with pretty much any log aggregator. You're getting structured JSON with timestamps, request IDs, and all the metadata you need.

Key metrics to track:

Request Metrics: Requests/min, error rate by status code, P50/P95/P99 latency, rate limit hits (429s)

MCP-Specific: tools/list vs tools/call distribution, per-tool error rates, per-subscription usage patterns

Security: Unauthorized attempts (401/403), invalid subscription keys, unusual client IPs, rate limit violations

Performance Considerations

What to Log (And What Not To)

Always log: Request metadata, response status codes, timing, security context, and errors. These are safe, fast, and give you what compliance needs.

Never log: Response bodies (hangs requests), large payloads (kills performance), or sensitive data (violates compliance). Anything that slows down the critical path or exposes PII or PCI is out.

The metadata-only approach handles millions of requests without breaking a sweat. You dont want to introduce verbose logs, slowing down your performance and loose money on people bailing out.

Sampling Strategy

For high-volume APIs:

<!-- Log 100% of errors, 10% of successes -->
<choose>
    <when condition="@(context.Response.StatusCode >= 400)">
        <log-to-eventhub logger-id="mcp-audit-logger">
            @{ /* full logging */ }
        </log-to-eventhub>
    </when>
    <when condition="@(new Random().Next(100) < 10)">
        <log-to-eventhub logger-id="mcp-audit-logger">
            @{ /* sampled logging */ }
        </log-to-eventhub>
    </when>
</choose>

Compliance & Audit Requirements

Data Retention

(Do check this with your compliance team, these are just guidelines)

Event Hub: 7-90 days retention
Log Analytics: 30-365 days retention
Archive Storage: Unlimited (cold storage)

Audit Trail Fields

For compliance (SOC2, ISO 27001):

{
  "timestamp": "2025-11-05T10:30:45.123Z",
  "requestId": "abc-123-def-456",
  "userId": "user@company.com",
  "subscriptionName": "Company-Production",
  "mcpMethod": "tools/call",
  "toolName": "processPayment",
  "statusCode": 200,
  "clientIp": "203.0.113.42",
  "action": "execute",
  "resource": "/api/payment",
  "result": "success"
}

Note: If you have a WAF in front of your APIM, make sure to collect WAF logs as well, because they contain important security events (blocked attacks, suspicious IPs, etc).

GDPR Considerations

During my career I have made my mistakes, and seen others make them. To prevent you ending up sanitizing logs, which is probably going to ruin your weekend, here are some guidelines:

For user data:

Don't log full request/response bodies (they can contain PII, PCI data)
Log user IDs, but only if needed (pseudonymized from JWT claims)
Support data deletion requests (Event Hub retention handles this)
Implement retention policies (compliance will ask for this)

Before You Go Live

Core Requirements (Everyone needs this):

Event Hub logger configured
Audit logging policy deployed
Response body access removed (no hanging, although you will notice this quite fast)
Request IDs propagated to backends (preserving upstream IDs)
Log retention policies set (check with compliance team)
Sampling configured for high volume (if needed)

Monitoring Stack (Choose your poison):

Event Hub → Your SIEM/observability platform (Datadog, Grafana, Splunk, etc.)
Or Application Insights (if you're all-in on Azure)
Dashboards created (whatever tool you use)
Alerts configured for errors/latency/security events to disrupt your sleep

What's Next

Security: locked down. Observability: sorted. Now let's tackle the elephant in the room: automation.

Coming soon: Part 4 - GitOps for Azure APIM MCP: Custom Automation Guide

MCP servers don't support Terraform or ARM templates yet. Microsoft knows this is a gap and it's on the roadmap. In the meantime, I'll show you ideas how to automate deployments using custom REST API scripts and CI/CD pipelines—because manual Portal clicks don't scale. This is still something we have to implement, but lets drill down on the concept!

I'm a Product Architect at Backbase, where I design cloud-native banking platforms serving millions of users. The patterns in this series come from real production implementations at enterprise scale. Views are my own.

How are you handling APIM observability? Share your patterns in the comments.

Follow me on LinkedIn for more Azure and platform engineering content.

Securing Azure APIM MCP Servers in Production

René Nijkamp — Tue, 25 Nov 2025 22:06:04 +0000

Securing Azure APIM MCP Servers in Production

In Part 1, I covered the good, bad, and ugly of Azure APIM MCP. Now let's talk about the security gaps you need to address before going to production.

Here's the reality: As a preview feature, Azure APIM MCP has permissive defaults that work great for prototyping but need hardening for production. You'll need to add security policies manually—Microsoft is actively working on better defaults, but let's not wait. Here's how to lock it down today.

Let's break down what's exposed by default and the patterns to secure it.

The `/tools/list` Authentication Issue

The Problem

Let's start with the most obvious one. The /tools/list endpoint—used for tool discovery—doesn't enforce subscription key validation by default.

Anyone can enumerate your available tools without credentials:

# No authentication required
curl -X POST https://your-apim.azure-api.net/your-api-mcp/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

# Returns full list of exposed tools
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {"name": "getCustomer", "description": "..."},
      {"name": "updateProfile", "description": "..."},
      {"name": "processPayment", "description": "..."}
    ]
  }
}

This is information disclosure—tool names and descriptions can reveal business logic, which you'll want to lock down for production environments.

The Fix: Explicit Subscription Key Validation

Add subscription key validation to your MCP server policy:

<policies>
    <inbound>
        <!-- Step 1: Check if subscription key is present -->
        <choose>
            <when condition="@(context.Request.Headers.GetValueOrDefault(\"Ocp-Apim-Subscription-Key\", \"\") == \"\")">
                <return-response>
                    <set-status code="401" reason="Unauthorized" />
                    <set-header name="Content-Type" exists-action="override">
                        <value>application/json</value>
                    </set-header>
                    <set-body>{"error": "Subscription key required"}</set-body>
                </return-response>
            </when>
        </choose>

        <!-- Step 2: Store the subscription key (APIM strips it during processing) -->
        <set-variable name="originalSubKey" 
                      value="@(context.Request.Headers.GetValueOrDefault(\"Ocp-Apim-Subscription-Key\", \"\"))" />

        <base />

        <!-- Step 3: Validate subscription after base processing -->
        <choose>
            <when condition="@(context.Subscription == null || context.Subscription.Id == null)">
                <return-response>
                    <set-status code="401" reason="Unauthorized" />
                    <set-header name="Content-Type" exists-action="override">
                        <value>application/json</value>
                    </set-header>
                    <set-body>{"error": "Invalid subscription key"}</set-body>
                </return-response>
            </when>
        </choose>

        <!-- Step 4: Re-inject subscription key for backend APIs -->
        <set-header name="Ocp-Apim-Subscription-Key" exists-action="override">
            <value>@((string)context.Variables[\"originalSubKey\"])</value>
        </set-header>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Why Re-injection is Necessary

Here's the catch: APIM base policies might strip the Ocp-Apim-Subscription-Key header during policy processing, depending on your base policy configuration. This prevents inbound sensitive data from leaking to downstream services. But your backend APIs need that key for their own validation.

This is different from standard APIM patterns. Normally, APIM validates the request, strips sensitive headers, and calls the backend. Done. With MCP tool calls, the flow is different:

Is that double validation? Yes. It's a tradeoff when you expose your APIs as MCP tools—but it's efficient and easily solvable with the re-injection pattern.

The re-injection pattern:

Store the key in a variable before <base />
Let APIM process the request
Re-inject the key after <base /> so it reaches your backend

Subscription-Based Access Control

Product Authorization Limitation

Normally, APIM's standard access control uses Products—logical groupings of APIs with different access levels (think: Starter, Professional, Enterprise plans for your customers). You check context.Product in policies.

This isn't available for MCP servers yet. context.Product returns null. Microsoft is aware of this limitation, but for now we'll need an alternative approach.

Alternative: Subscription Whitelisting

Use subscription IDs for access control:

<policies>
    <inbound>
        <!-- Basic authentication (from previous example) -->
        <choose>
            <when condition="@(context.Request.Headers.GetValueOrDefault(\"Ocp-Apim-Subscription-Key\", \"\") == \"\")">
                <return-response>
                    <set-status code="401" reason="Unauthorized" />
                    <set-body>{"error": "Subscription key required"}</set-body>
                </return-response>
            </when>
        </choose>

        <set-variable name="originalSubKey" 
                      value="@(context.Request.Headers.GetValueOrDefault(\"Ocp-Apim-Subscription-Key\", \"\"))" />
        <base />

        <!-- Validate subscription exists -->
        <choose>
            <when condition="@(context.Subscription == null || context.Subscription.Id == null)">
                <return-response>
                    <set-status code="401" reason="Unauthorized" />
                    <set-body>{"error": "Invalid subscription key"}</set-body>
                </return-response>
            </when>
        </choose>

        <!-- Subscription whitelist for MCP access -->
        <choose>
            <when condition="@(!new string[] {
                \"sub-id-premium-1\", 
                \"sub-id-premium-2\", 
                \"sub-id-enterprise-1\"
            }.Contains(context.Subscription.Id))">
                <return-response>
                    <set-status code="403" reason="Forbidden" />
                    <set-header name="Content-Type" exists-action="override">
                        <value>application/json</value>
                    </set-header>
                    <set-body>{"error": "Access denied - MCP access not authorized for this subscription"}</set-body>
                </return-response>
            </when>
        </choose>

        <!-- Re-inject subscription key -->
        <set-header name="Ocp-Apim-Subscription-Key" exists-action="override">
            <value>@((string)context.Variables[\"originalSubKey\"])</value>
        </set-header>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Alternative: Subscription Name Pattern

If you don't want to maintain ID lists, use naming conventions:

<when condition="@(!context.Subscription.Name.Contains(\"MCP-Enabled\"))">
    <return-response>
        <set-status code="403" reason="Forbidden" />
        <set-body>{"error": "MCP access not authorized"}</set-body>
    </return-response>
</when>

Then name your subscriptions: Company-ABC-MCP-Enabled, Team-XYZ-MCP-Enabled, etc.

Rate Limiting

This one is critical. Rate limiting for MCP servers is essential—you're exposing APIs to AI agents that can (and will) spam requests if they're having a bad day, giving you a horrible day.

Global Rate Limiting

<policies>
    <inbound>
        <!-- Authentication policies first -->
        <!-- ... -->

        <!-- Rate limiting AFTER authentication -->
        <rate-limit calls="100" renewal-period="60" />

        <!-- Rest of inbound policies -->
    </inbound>
    <outbound>
        <!-- Add rate limit headers to responses -->
        <set-header name="X-RateLimit-Limit" exists-action="override">
            <value>100</value>
        </set-header>
        <set-header name="X-RateLimit-Window" exists-action="override">
            <value>60</value>
        </set-header>
        <base />
    </outbound>
</policies>

Important: Place rate limiting after authentication. Otherwise, attackers can exhaust your rate limits without valid credentials. Don't make it that easy for them.

Rate Limiting Behavior

When limits are exceeded:

APIM returns HTTP 429 (Too Many Requests)
Includes Retry-After header
Counters reset after renewal period

Test it:

# Rapid-fire requests
for i in {1..150}; do
  curl -X POST https://your-apim.azure-api.net/your-api-mcp/mcp \
    -H "Ocp-Apim-Subscription-Key: YOUR_KEY" \
    -d '{"jsonrpc": "2.0", "method": "tools/list", "id": '$i'}' \
    -w "Request $i: %{http_code}\n" \
    -s -o /dev/null
done

# First 100: HTTP 200
# Requests 101+: HTTP 429

User Context Propagation (JWT Tokens)

When you need user context: For authenticated operations where users interact through AI agents, you need to propagate user identity.

The Challenge

Consider the following flow:

Each hop must preserve and validate the JWT token. Let's make sure that happens.

Assumption: Your APIM base policy strips Authorization headers (which is good security practice—limits unwanted token exposure downstream). That's why we need the same re-injection pattern.

JWT Forwarding Policy

<policies>
    <inbound>
        <!-- Subscription key validation -->
        <choose>
            <when condition="@(context.Request.Headers.GetValueOrDefault(\"Ocp-Apim-Subscription-Key\", \"\") == \"\")">
                <return-response>
                    <set-status code="401" reason="Unauthorized" />
                    <set-body>{"error": "Subscription key required"}</set-body>
                </return-response>
            </when>
        </choose>

        <!-- Store BOTH subscription key AND JWT token -->
        <set-variable name="originalSubKey" 
                      value="@(context.Request.Headers.GetValueOrDefault(\"Ocp-Apim-Subscription-Key\", \"\"))" />
        <set-variable name="originalJwtToken" 
                      value="@(context.Request.Headers.GetValueOrDefault(\"Authorization\", \"\"))" />

        <base />

        <!-- Subscription validation -->
        <choose>
            <when condition="@(context.Subscription == null || context.Subscription.Id == null)">
                <return-response>
                    <set-status code="401" reason="Unauthorized" />
                    <set-body>{"error": "Invalid subscription key"}</set-body>
                </return-response>
            </when>
        </choose>

        <!-- Re-inject both headers -->
        <set-header name="Ocp-Apim-Subscription-Key" exists-action="override">
            <value>@((string)context.Variables[\"originalSubKey\"])</value>
        </set-header>
        <set-header name="Authorization" exists-action="override">
            <value>@((string)context.Variables[\"originalJwtToken\"])</value>
        </set-header>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Optional: JWT Validation in APIM

Why validate in APIM? The forwarding pattern passes tokens through without checking them. If you want APIM to verify tokens are valid before they reach your backend, add JWT validation.

This adds an extra security layer—invalid or expired tokens get rejected at the gateway, not at your backend.

<validate-jwt header-name="Authorization" 
              failed-validation-httpcode="401" 
              failed-validation-error-message="Unauthorized. Valid JWT required.">
    <openid-config url="https://your-auth-server/.well-known/openid-configuration" />
    <audiences>
        <audience>https://your-apim.azure-api.net</audience>
    </audiences>
    <required-claims>
        <claim name="scope" match="any">
            <value>mcp:read</value>
            <value>mcp:execute</value>
        </claim>
    </required-claims>
</validate-jwt>

Key configuration points:

openid-config: Points to your identity provider's discovery endpoint (Azure AD, Auth0, Okta, etc.)
audiences: Must match the aud claim in your JWT—typically your APIM gateway URL or API identifier
required-claims: Enforces specific scopes—adjust these to match your authorization model

Complete Production-Ready Security Policy

Putting it all together: Here's the complete security policy combining all the patterns above:

<policies>
    <inbound>
        <!-- CORS (if needed for browser clients) -->
        <cors allow-credentials="false">
            <allowed-origins>
                <origin>https://your-app.com</origin>
            </allowed-origins>
            <allowed-methods>
                <method>POST</method>
                <method>OPTIONS</method>
            </allowed-methods>
            <allowed-headers>
                <header>Content-Type</header>
                <header>Ocp-Apim-Subscription-Key</header>
                <header>Authorization</header>
            </allowed-headers>
        </cors>

        <!-- 1. Subscription key validation -->
        <choose>
            <when condition="@(context.Request.Headers.GetValueOrDefault(\"Ocp-Apim-Subscription-Key\", \"\") == \"\")">
                <return-response>
                    <set-status code="401" reason="Unauthorized" />
                    <set-header name="Content-Type" exists-action="override">
                        <value>application/json</value>
                    </set-header>
                    <set-body>{"error": "Subscription key required"}</set-body>
                </return-response>
            </when>
        </choose>

        <!-- 2. Store headers before base processing -->
        <set-variable name="originalSubKey" 
                      value="@(context.Request.Headers.GetValueOrDefault(\"Ocp-Apim-Subscription-Key\", \"\"))" />
        <set-variable name="originalJwtToken" 
                      value="@(context.Request.Headers.GetValueOrDefault(\"Authorization\", \"\"))" />

        <base />

        <!-- 3. Rate limiting -->
        <rate-limit calls="100" renewal-period="60" />

        <!-- 4. Subscription validation -->
        <choose>
            <when condition="@(context.Subscription == null || context.Subscription.Id == null)">
                <return-response>
                    <set-status code="401" reason="Unauthorized" />
                    <set-header name="Content-Type" exists-action="override">
                        <value>application/json</value>
                    </set-header>
                    <set-body>{"error": "Invalid subscription key"}</set-body>
                </return-response>
            </when>
        </choose>

        <!-- 5. Subscription whitelist -->
        <choose>
            <when condition="@(!new string[] {\"authorized-sub-1\", \"authorized-sub-2\"}.Contains(context.Subscription.Id))">
                <return-response>
                    <set-status code="403" reason="Forbidden" />
                    <set-header name="Content-Type" exists-action="override">
                        <value>application/json</value>
                    </set-header>
                    <set-body>{"error": "MCP access not authorized"}</set-body>
                </return-response>
            </when>
        </choose>

        <!-- 6. Re-inject headers -->
        <set-header name="Ocp-Apim-Subscription-Key" exists-action="override">
            <value>@((string)context.Variables[\"originalSubKey\"])</value>
        </set-header>
        <set-header name="Authorization" exists-action="override">
            <value>@((string)context.Variables[\"originalJwtToken\"])</value>
        </set-header>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <!-- Rate limit headers -->
        <set-header name="X-RateLimit-Limit" exists-action="override">
            <value>100</value>
        </set-header>
        <set-header name="X-RateLimit-Window" exists-action="override">
            <value>60</value>
        </set-header>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Testing Your Security

1. Test Unauthorized Access

# Should fail with 401
curl -X POST https://your-apim.azure-api.net/your-api-mcp/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

2. Test Invalid Subscription Key

# Should fail with 401
curl -X POST https://your-apim.azure-api.net/your-api-mcp/mcp \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: INVALID_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

3. Test Valid Access

# Should succeed with 200
curl -X POST https://your-apim.azure-api.net/your-api-mcp/mcp \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: YOUR_VALID_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

4. Test Rate Limiting

# Rapid requests to trigger 429
for i in {1..150}; do
  curl -s -o /dev/null -w "%{http_code}\n" \
    -X POST https://your-apim.azure-api.net/your-api-mcp/mcp \
    -H "Ocp-Apim-Subscription-Key: YOUR_KEY" \
    -d '{"jsonrpc": "2.0", "method": "tools/list", "id": '$i'}'
done | grep -c "429"
# Should show ~50 (requests 101-150)

Security Checklist

Before going to production:

/tools/list requires subscription key
Invalid subscription keys return 401
Subscription whitelist implemented
Rate limiting configured and tested
JWT tokens forwarded (if needed)
CORS configured correctly (if needed)
Rate limit headers returned
All security tests passing

What's Next

Security is locked down. Now you need observability.

Coming soon: Part 3 - Audit Logging & Monitoring That Actually Works

In Part 3, I'll show you how to implement audit logging without the request-hanging bugs, plus distributed tracing and error handling.

Have security patterns you're using for MCP servers? Share them in the comments.

Follow with me on LinkedIn for more content.

Azure APIM MCP: The Good, The Bad, The Ugly

René Nijkamp — Tue, 18 Nov 2025 17:30:44 +0000

Azure APIM MCP: The Good, The Bad, The Ugly

AI agents need APIs. But not just any APIs—they need discoverable, secure, governed APIs that won't accidentally delete your production database when an LLM hallucinates.

Enter the Model Context Protocol (MCP)—a standardized way to expose APIs as tools that AI agents can discover and invoke safely. And Azure API Management (APIM) now has preview support for it.

Sounds great, right?

Well... sort of. I spent the last few months test driving this for a banking platform, and let me tell you: the Azure Portal screenshots don't tell the whole story.

This is Part 1 of a 4-part series on building production-ready MCP servers on Azure APIM. I'll share what I learned the hard way, so you don't have to.

What is MCP? (And Why Should You Care?)

The Model Context Protocol is OpenAPI for AI agents. It gives agents:

Tool Discovery: Agents ask "what can I do?" and get structured responses
Safe Execution: Schemas prevent garbage-in-garbage-out
Context Awareness: Agents know what tools exist and when to use them

Instead of throwing API endpoints at LLMs and hoping for the best, you give them curated tools with schemas, descriptions, and built-in safety.

Why APIM?

If you already have APIM, why build a separate MCP server? Your API gateway already does:

Authentication & authorization
Rate limiting & throttling
Logging & monitoring
Policy enforcement
Multi-environment management

Why add another service to manage?

Architecture Overview

The Good: What Actually Works

APIM V2 Standard has preview MCP support. When it works, it's solid:

1. Native MCP Server Functionality

Expose APIs as MCP Tools with a few clicks (or REST API calls):

# Discover available tools
curl -X POST https://your-apim.azure-api.net/your-api-mcp/mcp \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: YOUR_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "getCustomer",
        "description": "Retrieve customer information",
        "inputSchema": {
          "type": "object",
          "properties": {
            "id": {"type": "string"}
          },
          "required": ["id"]
        }
      }
    ]
  }
}

2. JSON-RPC 2.0 Protocol

Standard /tools/list and /tools/call endpoints that work with any MCP client:

# Invoke a tool
curl -X POST https://your-apim.azure-api.net/your-api-mcp/mcp \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: YOUR_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "getCustomer",
      "arguments": {"id": "123"}
    },
    "id": 2
  }'

3. APIM Policy Framework

You get the full power of APIM policies:

Rate limiting
Request/response transformation
Header manipulation
Custom validation
Backend routing

This is huge—you can apply enterprise-grade policies to your MCP endpoints.

4. Zero Additional Infrastructure

If you already have APIM (and most enterprises do), you're paying $0 extra for MCP capabilities. No new services to deploy, manage, or monitor.

The Bad: What's Frustrating

Now for the frustrating parts:

1. No Infrastructure as Code Support

This is the biggest gap. Currently, you cannot:

Define MCP servers in ARM templates
Manage them with Terraform
Use Azure Service Operator (ASO)
Deploy via standard GitOps pipelines

For now, you'll need manual Azure Portal configuration or custom REST API automation.

Update: Microsoft has acknowledged this feedback and it's on their roadmap. The team is actively listening to community input on IaC priorities. I'll keep this series updated as features land.

2. Documentation Still Maturing

As with most preview features, documentation is evolving. Some areas that need more coverage:

How context.Product behaves in MCP policies (currently unsupported)
Which headers are preserved through MCP translation
Best practices for user context propagation

The docs cover the core scenarios well, but production edge cases require experimentation. Microsoft is actively expanding the documentation based on community feedback.

3. Preview Tier Considerations

As a preview feature, keep in mind:

Features may evolve based on feedback
Standard preview support channels apply
No production SLA guarantees yet
Breaking changes are possible (though Microsoft typically provides migration paths)

For regulated environments, you'll need to assess your risk tolerance and plan for potential changes.

The Ugly: Known Limitations to Address

These are current limitations that require workarounds in production:

1. The `/tools/list` Authentication Behavior

By default, the /tools/list endpoint doesn't enforce subscription key validation.

This means tools can be enumerated without authentication (by design for some use cases, but problematic for others).

# This works without any authentication :-/
curl -X POST https://your-apim.azure-api.net/your-api-mcp/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

You must manually add subscription key validation in your MCP server policy. (I'll show you how in Part 2)

2. `context.Product` Not Yet Supported

APIM's Product-based access control model isn't currently available for MCP servers. context.Product returns null in MCP policies.

For now, you'll need subscription-level authorization instead of product-based tiers. Microsoft is aware of this limitation.

3. HTTP Status Code Masking

Backend returns HTTP 500? APIM gives you HTTP 200 with an error in the JSON body.

This breaks every standard HTTP error handling pattern:

# Direct API call
curl https://apim.azure-api.net/api/posts/999
# HTTP 500 

# Same API via MCP
curl https://apim.azure-api.net/api-mcp/mcp \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "getPost", "arguments": {"id": "999"}}, "id": 1}'
# HTTP 200 with error in body... Say what now?

Your monitoring tools won't detect errors. Your client libraries won't trigger error handlers.

4. Response Body Access Hangs Requests

If you try to access context.Response.Body in your policies for audit logging, your requests will hang indefinitely.

<!-- This will kill your performance -->
<set-variable name="responseBody" 
              value="@(context.Response.Body.As<string>())" />

You must use workarounds (Content-Length headers, metadata only).

Should You Use Azure APIM for MCP?

Use it if:

You already have APIM infrastructure
You need enterprise-grade security and compliance
You're willing to work around preview quirks
You can accept manual configuration (for now)
You have time to build custom automation

Don't use it if:

You need full IaC support immediately
You can't tolerate preview-tier instability
You require perfect HTTP status code semantics
You need product-based access control
You can't invest time in workarounds

What's Next in This Series

In the remaining parts, I'll show you exactly how to work around these issues:

Part 2: Security - How to fix the /tools/list hole, implement proper authentication, and handle user context propagation
Part 3: Logging & Monitoring - Audit logging without breaking performance, distributed tracing, and error handling
Part 4: GitOps & Automation - Custom REST API automation, Python scripts for OpenAPI processing, and deployment pipelines

Bottom Line

APIM MCP is a solid preview feature that brings MCP capabilities to your existing API infrastructure.

With the right patterns (which I'll share in this series), you can build production-ready MCP servers today. Some areas need custom policies and automation, but that's typical for preview features.

If you're already invested in Azure and APIM, it's a strong choice. You get enterprise-grade infrastructure without standing up new services.

Microsoft is actively improving the feature based on community feedback—expect it to get better with each release.

Next: Part 2 - Securing Azure APIM MCP Servers in Production →

I'm a Product Architect at Backbase, where I design cloud-native banking and integration platforms. The patterns in this series come from real production implementations at enterprise scale. Views are my own.

Have you tried Azure APIM MCP? What's your experience been? Drop a comment on my Linkedin post or Dev.To blog—I'd love to hear your war stories.

Connect with me on LinkedIn for more Azure and platform engineering content.

DEV Community: René Nijkamp

Azure APIM MCP Audit Logging Without Breaking Everything

Azure APIM MCP Audit Logging Without Breaking Everything

Observability Architecture

The Response Body Problem

What You'd Normally Do

Why This Happens

The Solution: Log Metadata, Not Payloads

Logging Tool Discovery

Setting Up Event Hub Logging

1. Create Event Hub

2. Create APIM Logger

3. Configure Named Values (Optional)

Complete Production Logging Policy

Distributed Tracing

Request ID Propagation

What to Monitor

Performance Considerations

What to Log (And What Not To)

Sampling Strategy

Compliance & Audit Requirements

Data Retention

Audit Trail Fields

GDPR Considerations

Before You Go Live

What's Next

Securing Azure APIM MCP Servers in Production

Securing Azure APIM MCP Servers in Production

The /tools/list Authentication Issue

The Problem

The Fix: Explicit Subscription Key Validation

Why Re-injection is Necessary

Subscription-Based Access Control

Product Authorization Limitation

Alternative: Subscription Whitelisting

Rate Limiting

Global Rate Limiting

Rate Limiting Behavior

User Context Propagation (JWT Tokens)

The Challenge

JWT Forwarding Policy

Optional: JWT Validation in APIM

Complete Production-Ready Security Policy

Testing Your Security

1. Test Unauthorized Access

2. Test Invalid Subscription Key

3. Test Valid Access

4. Test Rate Limiting

Security Checklist

What's Next

Azure APIM MCP: The Good, The Bad, The Ugly

Azure APIM MCP: The Good, The Bad, The Ugly

What is MCP? (And Why Should You Care?)

Why APIM?

Architecture Overview

The Good: What Actually Works

1. Native MCP Server Functionality

2. JSON-RPC 2.0 Protocol

3. APIM Policy Framework

4. Zero Additional Infrastructure

The Bad: What's Frustrating

1. No Infrastructure as Code Support

2. Documentation Still Maturing

3. Preview Tier Considerations

The Ugly: Known Limitations to Address

1. The /tools/list Authentication Behavior

2. context.Product Not Yet Supported

3. HTTP Status Code Masking

4. Response Body Access Hangs Requests

Should You Use Azure APIM for MCP?

What's Next in This Series

Bottom Line

The `/tools/list` Authentication Issue

1. The `/tools/list` Authentication Behavior

2. `context.Product` Not Yet Supported