Azure APIM MCP Production Guide

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

Published November 19, 2025

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

graph LR A[AI Agent] -->|JSON-RPC 2.0| B[Azure APIM MCP] B -->|tools/list| C[Tool Discovery] B -->|tools/call| D[API Gateway] D -->|HTTP| E[Backend APIs] B -.->|Policies| F[Rate Limiting] B -.->|Policies| G[Auth/AuthZ] B -.->|Policies| H[Audit Logging] E -->|Customer API| I[Database] E -->|Payment API| J[Payment Gateway] E -->|Analytics API| K[Data Warehouse] style B fill:#0078D4,color:#fff style A fill:#10B981,color:#fff style E fill:#F59E0B,color:#fff

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.

← Back to Blog