How to use Bicep to expose MCP Server via APIM

Sutton, Will 0 Reputation points
2026-09-03T12:19:36.54+00:00

I am attempting to create an MCP server passthrough in APIM using a Bicep template. I am referencing this documentation: https://learn.microsoft.com/en-us/azure/api-management/manage-mcp-servers-rest-api?tabs=bash%2Cbicep#passthrough-mcp-server

My Bicep is as follows (truncated and redacted):



resource apim 'Microsoft.ApiManagement/service@2023-03-01-preview' existing = {
  name: "dev-apim"
}


resource product 'Microsoft.ApiManagement/service/products@2022-08-01' existing = {
  name: "dev-api"
  parent: apim
}

resource mcpServer 'Microsoft.ApiManagement/service/apis@2025-09-01-preview' = {
  name: "my-mcp-server"
  parent: apim
  properties: {
    type: 'mcp'
    displayName: "my-mcp-server"
    path: path
    protocols: [
      'https'
    ]
    serviceUrl: "https://myserver.com/api/mcp"
    subscriptionRequired: true
    mcpProperties: {
      transportType: 'streamable'
      endpoints: {
        mcp: {
          uriTemplate: "/api/mcp"
        }
      }
    }
  }
}

resource mcpPolicy 'Microsoft.ApiManagement/service/apis/policies@2025-09-01-preview' = {
 name: 'policy'
 parent: mcpServer
 properties: {
   format: 'rawxml'
   value: loadFileContent("../policies/my-mcp.xml")
 }
}


resource productBinding 'Microsoft.ApiManagement/service/products/apis@2025-09-01-preview' = {
  name: mcpServer.name
  parent: product
}

I have noted the mcpProperties structure is different from the documentation, however the Bicep did not work as documented, and a different blog post used this structure which deployed: https://cloudadministrator.net/2025/09/23/deploying-azure-apim-mcp-servers-with-bicep/

When I deployed this Bicep, the MCP serverwas of an 'API' source rather than an 'MCP Server' source that is shown when a passthrough MCP Server is created through the Azure portal and what I expect here.

Actual:

User's image

Expected: User's image

I should note I have also tried creating and linking a backend:


resource mcpBackend 'Microsoft.ApiManagement/service/backends@2022-08-01' = {
  name: 'my-mcp-server-backend'
  parent: apim
  properties: {
    description: 'Backend for passthrough MCP server'
    url: 'https://myserver.com/api/mcp'
    protocol: 'http'
  }
}


resource mcpServer 'Microsoft.ApiManagement/service/apis@2025-09-01-preview' = {
  name: "my-mcp-server"
  parent: apim
  properties: {
    type: 'mcp'
    displayName: "my-mcp-server"
    path: path
    protocols: [
      'https'
    ]
    backendId: mcpBackend.id
    subscriptionRequired: true
    mcpProperties: {
      transportType: 'streamable'
      endpoints: {
        mcp: {
          uriTemplate: "/api/mcp"
        }
      }
    }
  }
}

This produced the following validation error, which displayed the correct backend ID and occured after running the same deployment multiple times.

"Backend Entity [REDACTED] not found."

Have I done something wrong here? At the least, I would say the documentation needs to be updated.

Azure API Management
Azure API Management

An Azure service that provides a hybrid, multi-cloud management platform for APIs.

0 comments

1 answer

Sort by: Most helpful
Most helpful Newest Oldest
  1. Allan Solomon Mejia 7,915 Reputation points
    2026-09-03T20:22:06.5633333+00:00

    Hello @Sutton, Will

    Yes, this is now supported directly in Bicep. The important part is to use API Management API version 2025-09-01-preview or later, because that is where the MCP resource model is exposed for ARM/Bicep.

    If you already have an MCP-compatible backend and simply want APIM to proxy/govern it, define it as an APIM API with type: 'mcp', point serviceUrl to the backend, and configure the MCP transport. For Streamable HTTP, the shape is essentially:

    resource apim 'Microsoft.ApiManagement/service@2025-09-01-preview' existing = {
  name: apimName
}
resource mcpServer 'Microsoft.ApiManagement/service/apis@2025-09-01-preview' = {
  parent: apim
  name: 'my-mcp'
  properties: {
    type: 'mcp'
    displayName: 'My MCP Server'
    path: 'my-mcp'
    protocols: [
      'https'
    ]
    serviceUrl: 'https://my-backend.example.com'
    subscriptionRequired: true
    mcpProperties: {
      transportType: 'streamable'
      endpoints: [
        {
          name: 'message'
          uriTemplate: '/mcp'
        }
      ]
    }
  }
}

    There are two Bicep scenarios: exposing an existing MCP server as a passthrough server, and turning an existing REST API in APIM into an MCP server whose operations become tools.

    If your backend is already MCP-native, use the passthrough pattern above. If it is a normal REST API, use the REST API-backed MCP pattern instead and create tool resources mapped to the APIM operations.

    You can then attach normal APIM policies such as JWT validation, rate limits, IP filtering, and bind the MCP API to a product just like other APIM APIs.

    The best current reference: Manage MCP servers programmatically in API Management

    That page now includes complete Bicep templates for both REST-backed and passthrough MCP servers, so use those rather than trying to reproduce the portal-generated configuration manually.

    Help make this community better for everyone: if this answer resolved your issue, please accept it or upvote it. If not, share more details in a comment so we can continue the discussion and find the right solution.

    Was this answer helpful?

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.