DEV Community: René Nijkamp

Azure APIM MCP Automation: The Bridging Problem

René Nijkamp — Tue, 07 Jul 2026 06:03:50 +0000

Azure APIM MCP Automation: The Bridging Problem

In Part 3, we tackled observability. Now let's talk about the automation elephant in the room.

Azure APIM MCP is in preview. And here's what that means for Infrastructure as Code:

No ARM template support
No Bicep support
No Terraform provider support
No Azure Service Operator (ASO) support

Here's the reality: You can't use standard IaC tooling. You're either clicking through the Azure Portal manually, or you're building custom automation.

But before you rush to build REST API scripts, let's talk about why this problem matters and what it means for your architecture.

Why This Is Different

It's Not Just About Automation

Most IaC gaps are annoying but straightforward: write some REST API calls, wrap them in a script, deploy via pipeline. Done.

MCP is different. And here's why:

AI agents read your API descriptions. Those descriptions become tool definitions that LLMs use to decide when and how to invoke your APIs. A poorly written description? The agent misunderstands. A misleading summary? The agent calls the wrong endpoint. A missing security note? The agent leaks data.

This is a governance problem disguised as an automation problem.

The Real Risks

Without proper governance:

No review of tool descriptions before AI agents see them
No validation of API quality before MCP exposure
No control over which operations become agent-accessible tools
No audit trail of what got exposed and when

This isn't Terraform failing to deploy a VM. This is giving AI agents access to your business logic without proper oversight.

The Governance-First Approach

What We Need

Before worrying about automation tooling, we need:

Source of truth for MCP exposure (which APIs become tools?)
Review gates for tool quality (are descriptions agent-friendly?)
Approval workflows for changes (who decides what gets exposed?)
Audit trail for MCP operations (what changed and when?)
Rollback capability (can we undo a bad exposure?)

This is GitOps territory. Not because of Kubernetes or Helm charts, but because we need:

Version control for configuration
Pull request reviews before changes
Approval gates for production
History of who changed what

OpenAPI as Configuration

Here's the pattern: OpenAPI specifications become your configuration files.

paths:
  /users/{userId}/profile:
    get:
      operationId: getUserProfile
      summary: "Retrieve user profile information"
      description: "Get comprehensive profile data for the authenticated user including preferences, settings, and basic account information. This tool respects user privacy and only returns data the user has permission to access."
      x-mcp-enabled: true  # Governance flag
      parameters:
        - name: userId
          in: path
          required: true
          description: "User identifier - must match authenticated user"
          schema:
            type: string

That x-mcp-enabled: true flag is governance metadata, not just a technical toggle. It says:

Someone reviewed this operation's description
Someone decided AI agents should have access
Someone validated the security model
Someone approved this for MCP exposure

No flag = no MCP exposure. Simple as that.

Conceptual Bridging Approaches

Let's talk about how to bridge the IaC gap until ASO catches up.

Full disclosure: These are patterns we're exploring, not battle-tested solutions. They're based on months of working with APIM MCP and years of GitOps experience, but consider them architectural ideas rather than production-ready implementations.

Pattern 1: Centralized Automation Repository

Concept: Single repository that polls APIM instances, detects APIs with x-mcp-enabled flags, and applies MCP overlays.

Characteristics:

Separation of concerns: Standard API deployment unchanged
Non-invasive: Overlay runs externally, doesn't touch existing workflows
Easy removal: When ASO adds MCP support, delete the overlay repo
Governance preserved: Only APIs with x-mcp-enabled get converted

Trade-offs:

Eventual consistency (polling-based, not real-time)
Requires cross-subscription credentials for multi-tenant scenarios
Centralized monitoring but distributed execution

Pattern 2: Event-Driven Kubernetes Jobs

Concept: ArgoCD PostSync hooks that detect MCP-enabled APIs after deployment and apply conversion.

Characteristics:

Event-driven: Conversion happens immediately after API deployment
Kubernetes-native: Fits existing ArgoCD workflows
Per-cluster isolated: Each cluster handles its own APIM instance

Trade-offs:

Embeds workaround in Helm charts (harder to remove cleanly)
Requires RBAC setup for Kubernetes service accounts
Debugging in pod logs vs centralized logging

Pattern 3: Build-Time Generation

Concept: Maven plugin or build tool generates two outputs: standard API spec + MCP overlay config.

Characteristics:

Zero operational overhead: Automatic for all builds
Fits existing workflows: Maven → Helm → ArgoCD
Centralized logic: One plugin, all APIs benefit

Trade-offs:

Requires modifying build tooling (parent POM, plugins)
Longer development time upfront
Still needs Azure credentials in Kubernetes

What These Patterns Have in Common

All three approaches share critical principles:

OpenAPI spec is single source of truth (no config duplication)
Standard API deployment unchanged (MCP is an overlay, not replacement)
Governed by flags (explicit opt-in via x-mcp-enabled)
Easy to remove (when ASO adds MCP support)
Support full CRUD (create, update, delete MCP exposure)

Which one is right? Depends on your organization:

Centralized control + multi-tenant? Pattern 1
Kubernetes-native + per-cluster isolation? Pattern 2
Minimal operational overhead? Pattern 3

The Governance Framework

Let's break down what governance actually means for MCP exposure.

Review Workflow

Typical approval flow:

Developer → OpenAPI with x-mcp-enabled → Pull Request → 
Domain Review → Security Review → Principal Architect → 
Merge → Automated Deployment → MCP Server Live

What gets reviewed:

Aspect	Review Focus	Risk if Skipped
Description Quality	Is it clear for AI agents?	Misunderstood intent, wrong API calls
Security Model	Auth requirements documented?	Unauthorized access, data leaks
Data Exposure	Sensitive data clearly marked?	Privacy violations, compliance gaps
Operation Safety	Read-only vs write operations?	Accidental data modification
Rate Limiting	Appropriate throttling?	Resource exhaustion, DoS

Tool Quality Standards

Bare minimum for MCP-enabled operations:

# BAD: Too vague for AI agents
get:
  summary: "Get user"
  x-mcp-enabled: true

# GOOD: Clear, actionable, with constraints
get:
  summary: "Retrieve user profile information"
  description: |
    Get comprehensive profile data for the authenticated user including 
    preferences, settings, and basic account information.

    **Authentication required**: User can only access their own profile.
    **Data privacy**: Returns only non-sensitive user data.
    **Rate limit**: 100 requests per minute.
  x-mcp-enabled: true
  security:
    - BearerAuth: []

Why this matters: AI agents rely on descriptions to understand:

What the tool does
When to use it
What data it returns
What permissions are needed

Poor descriptions = poor agent behavior.

CODEOWNERS for MCP

Enforce review requirements:

# In your Git repository
/apis/customer-management/   @customer-team @security-team
/apis/payment-processing/    @payment-team @compliance-team @security-team
/apis/public-data/          @platform-team

# Any file with x-mcp-enabled requires principal architect
**/openapi*.yaml            @principal-architect

This enforces:

Domain experts review their APIs
Security team sees all MCP-enabled operations
Principal architect has final approval

Audit Trail

Git as audit trail:

{
  "commit": "abc123",
  "author": "developer@org.com",
  "timestamp": "2026-01-12T10:30:00Z",
  "changes": [
    {
      "file": "apis/customer-management/openapi.yaml",
      "operation": "/users/{userId}/profile",
      "change": "Added x-mcp-enabled: true",
      "reviewers": ["security-team", "principal-architect"],
      "approved_at": "2026-01-12T11:00:00Z"
    }
  ]
}

Every MCP exposure change lives in Git history. Who changed what, when, and who approved it.

API Quality Prerequisites

Here's an uncomfortable truth: You can't sprinkle MCP on top of a shitty API landscape and expect good results.

What Makes an API "MCP-Ready"?

Not every API should become an MCP tool. Consider:

Characteristic	MCP-Ready	Not MCP-Ready
Documentation	Clear, complete, agent-friendly	Sparse, outdated, human-only
Stability	Versioned, stable contract	Frequent breaking changes
Error Handling	Structured error responses	Generic 500s, no details
Security Model	Well-defined auth/authz	Ad-hoc permissions
Performance	Reliable response times	Intermittent timeouts
Idempotency	Safe retry behavior	Side effects on retry

AI agents are unforgiving consumers. They won't debug your API, they won't file tickets, they'll just fail spectacularly.

The Functional vs Technical API Problem

Here's the hill I'm willing to die on: AI agents need functional APIs, not technical APIs.

Technical APIs (what most orgs have):

# CRUD operations, database-centric
POST /api/v1/customers
GET /api/v1/customers/{id}
PUT /api/v1/customers/{id}
DELETE /api/v1/customers/{id}

POST /api/v1/accounts
GET /api/v1/accounts/{id}
PUT /api/v1/accounts/{id}

AI agent sees this: "I have create, read, update, delete... but what am I actually doing for the user?"

Functional APIs (what agents need):

# Business capabilities, intent-driven
POST /customers/onboard
  - "Onboard a new customer with KYC verification"

POST /customers/{id}/verify-identity
  - "Verify customer identity using government documents"

POST /accounts/open
  - "Open a new bank account for verified customer"

POST /payments/transfer
  - "Transfer money between accounts with fraud checks"

AI agent sees this: "I can onboard customers, verify identities, open accounts, transfer money—I understand the business intent."

Why This Matters for MCP

With technical APIs:

Agent must orchestrate multiple low-level operations
No transaction boundaries (what if step 3 fails?)
Business rules scattered across agent logic
High risk of incorrect sequences

With functional APIs:

Single API call expresses business intent
Transaction handled by backend
Business rules centralized in API
Lower risk, easier to audit

The Refactoring Question

Three paths forward:

APIs already functional? Add MCP flags, deploy
APIs refactorable? Transform technical → functional first
APIs beyond hope? Build new functional APIs from scratch

Don't expose CRUD endpoints to AI agents expecting them to orchestrate business logic. That's a production incident waiting to happen.

Real-World Examples

Bad API (technical, don't MCP-ify this):

/api/customers:
  post:
    summary: "Create customer"
    description: "Insert customer record into database"
    requestBody:
      content:
        application/json:
          schema:
            type: object
            properties:
              firstName: string
              lastName: string
              email: string
              # 50 more fields...

AI agent sees this: "I can create a customer record, but what about KYC? Compliance checks? Account setup? Am I supposed to call other APIs? Which ones?"

Good API (functional, MCP-ready):

/customers/onboard:
  post:
    summary: "Onboard new customer with full verification"
    description: |
      Complete customer onboarding process including:
      - Identity verification (government ID + liveness check)
      - KYC/AML compliance screening
      - Risk assessment
      - Welcome email and account activation

      **Business rules enforced:**
      - Customer must be 18+ years old
      - Must pass identity verification
      - Must clear compliance screening
      - Duplicate detection performed automatically

      **What happens on success:**
      - Customer record created with verified status
      - Welcome email sent
      - Customer can proceed to account opening

      **Authentication required:** Staff or authorized system only
      **Rate limit:** 10 requests per minute
    x-mcp-enabled: true
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [firstName, lastName, dateOfBirth, governmentId]
            properties:
              firstName:
                type: string
                description: "Customer's legal first name"
              lastName:
                type: string
                description: "Customer's legal last name"
              dateOfBirth:
                type: string
                format: date
                description: "Date of birth (must be 18+ years ago)"
              governmentId:
                type: object
                description: "Government-issued identification"
                required: [type, number, issuingCountry]
                properties:
                  type:
                    type: string
                    enum: [passport, drivers_license, national_id]
                  number:
                    type: string
                  issuingCountry:
                    type: string
    responses:
      '201':
        description: "Customer onboarded successfully"
        content:
          application/json:
            schema:
              type: object
              properties:
                customerId:
                  type: string
                  description: "Unique customer identifier"
                verificationStatus:
                  type: string
                  enum: [verified, pending_review]
                nextSteps:
                  type: array
                  items:
                    type: string
                  example: ["Open savings account", "Apply for credit card"]
      '400':
        description: "Invalid input or failed verification"
        content:
          application/json:
            schema:
              type: object
              properties:
                error:
                  type: string
                reason:
                  type: string
                  enum: [underage, failed_identity_check, failed_compliance, duplicate_customer]

AI agent sees this: "Crystal clear. This onboards a customer, handles verification, enforces business rules, tells me what happens next. I know exactly when to use this and what data I need."

Why Technical APIs Fail with AI Agents

Problem 1: Orchestration burden

Technical approach (agent must figure out):
1. POST /customers (create record)
2. POST /kyc-checks (verify identity)
3. GET /kyc-checks/{id} (wait for result)
4. POST /compliance-screenings (AML check)
5. GET /compliance-screenings/{id} (wait for result)
6. PUT /customers/{id} (update status to verified)
7. POST /emails (send welcome email)

What if step 4 fails? What if step 6 fails but step 7 succeeds?

Functional approach (single call):

POST /customers/onboard (everything happens atomically)

Problem 2: Business rule discovery

Technical API says: "Here's a database table, figure it out"
Functional API says: "Here's the business process, I'll enforce the rules"

Problem 3: Error semantics

Technical API: 400 Bad Request (what went wrong?)
Functional API: 400 Bad Request - reason: "failed_identity_check" (ah, identity verification failed)

This isn't just API design pedantry. This is the difference between agents that work and agents that cause production incidents.

GitOps Principles for MCP

Let's talk about what "GitOps" actually means in this context.

Single Source of Truth

Everything in Git:

OpenAPI specifications with x-mcp-enabled flags
APIM policy templates
Security configurations
Access control lists

Nothing in Azure Portal. If it's not in Git, it doesn't exist.

Declarative Configuration

What we want:

# This operation should be an MCP tool
x-mcp-enabled: true

Not:

# Imperative commands that modify state
az apim mcp create --name ...

The bridge automation reads declarative config and reconciles Azure state.

Review Before Merge

Feature Branch → Pull Request → Automated Validation → 
Human Review → Approval → Merge to Main → Automated Deployment

No cowboy deployments. Every change goes through review.

Rollback Capability

Git tags for deployments:

git tag deploy-20260112-103000

Rollback = checkout previous tag:

git checkout deploy-20260112-100000
./deploy.sh  # Re-applies previous state

Observability

Track what automation does:

What APIs were scanned?
Which operations had x-mcp-enabled?
What MCP servers were created/updated/deleted?
Any failures or errors?

Pipeline logs become your audit trail.

Our Exploration: What We're Testing

Full transparency: We're in the exploration phase. Here's what we're considering for Grand Central.

Option We're Leaning Toward

Maven plugin extension that generates MCP overlay configs during build.

Why this appeals:

Fits our existing OpenAPI → Maven → Helm → ArgoCD workflow
Zero operational overhead once deployed
Centralized logic (one plugin, all APIs benefit)
Easy removal when ASO adds MCP support

How it would work:

Plugin would:

Scan OpenAPI spec for x-mcp-enabled flags
Generate standard ASO API CRD (existing behavior)
Generate MCP overlay as Kubernetes Job (new behavior)
Job runs as ArgoCD PostSync hook
Job calls Azure REST API to convert API to MCP type

Why Not the Alternatives?

Centralized polling approach:

Requires cross-subscription service principal
Eventual consistency (polling lag)
Extra infrastructure to maintain

Per-customer workflows:

Deployment overhead (one repo per customer installation)
Configuration drift risk
Harder to update/remove

Our context: Multi-tenant platform with dozens of APIM instances, standardized bootstrap configuration across all of them. Maven plugin fits our existing patterns.

What We Haven't Solved Yet

Kubernetes RBAC:

How do Jobs get Azure credentials?
Managed Identity? Service account with federated identity?
Per-cluster or shared credentials?

Error handling:

Job fails to convert API to MCP. Now what?
Does ArgoCD deployment fail? Or continue?
How do we surface MCP conversion errors to developers?

Testing strategy:

How do we validate MCP overlays in dev before production?
Can we preview what tools would be exposed?
Dry-run mode for the conversion?

Removal path:

When ASO adds MCP support, how do we migrate?
Do we update the plugin to generate ASO MCP CRDs instead of Jobs?
Phased rollout or big-bang cutover?

These are open questions. We're working through them.

Decision Framework: When to Build vs Wait

Not every organization should build custom automation. Let's break down the decision.

Build Custom Bridging If:

You have scale (multiple APIM instances, lots of APIs)
You have GitOps maturity (already using IaC, review processes)
You have time (2-4 weeks for design + implementation + testing)
You have appetite (willing to maintain bridge until ASO catches up)
You need governance (AI agents accessing business-critical APIs)

Wait for ASO If:

Small scale (1-2 APIM instances, handful of APIs)
Portal management is fine (low change frequency)
Prototyping phase (not production-critical yet)
No GitOps (not using IaC for other Azure resources)
Resource constrained (can't invest dev time in tooling)

Our Context

Why we're building:

Dozens of APIM instances across customer installations
Hundreds of APIs, growing fast
Existing GitOps workflows (OpenAPI → Maven → ArgoCD)
Banking platform (governance non-negotiable)
Multi-tenant isolation requirements

Manual Portal management doesn't scale at our size.

What ASO Support Would Look Like

Microsoft hasn't announced a timeline, but here's what we expect:

CRD Structure (Hypothetical)

apiVersion: apimanagement.azure.com/v1api20260501
kind: API
metadata:
  name: customer-api
  namespace: default
spec:
  owner:
    name: apim-instance
  displayName: "Customer Management API"
  type: mcp  # MCP type support
  path: customer-mcp
  serviceUrl: https://backend.example.com
  protocols:
    - https
  apiVersion: v1
  mcpConfiguration:  # MCP-specific config
    enableToolDiscovery: true
    mcpTools:
      - operationId: getUserProfile
        enabled: true
      - operationId: updateUserProfile
        enabled: true

What we'd need:

type: mcp support (currently only http, soap, websocket)
mcpConfiguration section for tool control
Respect for x-mcp-enabled flags in OpenAPI specs
Policy application for MCP servers

Migration path:

ASO releases MCP CRDs
We update our plugin to generate MCP CRDs instead of overlay Jobs
Bump plugin version in parent POM
Redeploy APIs (ASO reconciles to MCP type)
Delete overlay Job charts
Done

If ASO doesn't support x-mcp-enabled flags: We'd need to maintain the plugin logic anyway, just targeting CRDs instead of REST API.

Advocacy: Push Microsoft

Here's the thing: Microsoft responds to feedback. If nobody asks for MCP IaC support, it stays low priority.

What You Can Do

File GitHub issues:

Azure/azure-service-operator: Request MCP CRD support
Azure/azure-rest-api-specs: Request stable MCP API version
Azure/bicep: Request MCP resource types

Engage on Azure forums:

Azure feedback portal: Vote for IaC support
Azure APIM team: Share your use case

Show demand: The more organizations ask, the higher priority it becomes.

We're doing our part. We've already escalated to Microsoft's APIM team. They're aware of the need. But they need to see community demand.

Conclusion: The Architect's Lens

Let's zoom out and look at this from an architecture perspective.

What This Series Covered

Part 1: MCP preview realities (what works, what's broken, when to use it)
Part 2: Security hardening (fixing /tools/list, subscription validation)
Part 3: Observability (audit logging without performance hits)
Part 4 (this post): Automation bridging (governance-first approach)

Key Takeaways

MCP on Azure APIM is powerful but immature. You can run it in production, but:

Governance is more critical than automation

AI agents reading descriptions = extra eyes on every change
API quality matters more than ever

Don't MCP-ify garbage APIs expecting good agent behavior
GitOps principles apply

Source control, review gates, rollback capability
Custom bridging is temporary

Build with removal in mind (ASO will eventually catch up)
Not every org should build

Weigh scale, maturity, and resources before committing

Where We Are

At Grand Central: Exploring Maven plugin approach for our multi-tenant scale. Governance framework designed. API quality assessment in progress. Not deployed yet.

Being honest: These are ideas we're testing, not battle-tested solutions. We're sharing our thinking because maybe it helps you avoid pitfalls.

What's Next

For us: Prototype the Maven plugin, test in dev environment, validate governance workflows, iterate based on learnings.

For you: Assess your context. Do you need custom bridging? Can you wait for ASO? What's your governance story?

For Microsoft: Keep pushing them. File issues. Share use cases. Show demand.

Resources

Azure Service Operator: https://github.com/Azure/azure-service-operator
APIM REST API: https://learn.microsoft.com/rest/api/apimanagement/
MCP Specification: https://modelcontextprotocol.io/
OpenAPI Extension: x-mcp-enabled pattern (community convention)

I'm a Product Architect at Backbase, where I design integration platforms for global banks. The patterns in this series come from real production implementations at enterprise scale, filtered through the lens of "what would I want to know if I were you?" Views are my own.

Building custom MCP automation? Running into governance challenges? Let's talk—drop a comment or connect on LinkedIn.

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.

Part 4: Azure APIM MCP Automation - The Bridging Problem

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, Part 4 covers how to bridge it with governance-first automation—because manual Portal clicks don't scale.

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 Automation: The Bridging Problem

Azure APIM MCP Automation: The Bridging Problem

Why This Is Different

It's Not Just About Automation

The Real Risks

The Governance-First Approach

What We Need

OpenAPI as Configuration

Conceptual Bridging Approaches

Pattern 1: Centralized Automation Repository

Pattern 2: Event-Driven Kubernetes Jobs

Pattern 3: Build-Time Generation

What These Patterns Have in Common

The Governance Framework

Review Workflow

Tool Quality Standards

CODEOWNERS for MCP

Audit Trail

API Quality Prerequisites

What Makes an API "MCP-Ready"?

The Functional vs Technical API Problem

Why This Matters for MCP

The Refactoring Question

Real-World Examples

Why Technical APIs Fail with AI Agents

GitOps Principles for MCP

Single Source of Truth

Declarative Configuration

Review Before Merge

Rollback Capability

Observability

Our Exploration: What We're Testing

Option We're Leaning Toward

Why Not the Alternatives?

What We Haven't Solved Yet

Decision Framework: When to Build vs Wait

Build Custom Bridging If:

Wait for ASO If:

Our Context

What ASO Support Would Look Like

CRD Structure (Hypothetical)

Advocacy: Push Microsoft

What You Can Do

Conclusion: The Architect's Lens

What This Series Covered

Key Takeaways

Where We Are

What's Next

Resources

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

The `/tools/list` Authentication Issue

1. The `/tools/list` Authentication Behavior

2. `context.Product` Not Yet Supported