apim-mcp

Read-only MCP server for exploring Azure API Management from an MCP-compatible client. It exposes API inventory and configuration, OpenAPI definitions, search, and service health without exposing APIM secrets.

Why a purpose-built APIM MCP server

Azure MCP Server provides broad Azure coverage but does not expose a dedicated API Management (apim) namespace. APIM requests therefore rely on generic Azure Resource Graph, Azure CLI, and ARM REST operations. This server exposes focused, read-only APIM tools directly, reducing discovery and response interpretation while returning bounded, redacted results.

In an observed four-prompt comparison using the same model, the purpose-built server completed the workload in roughly one-third of the session time while using about 72% fewer tokens and 74% fewer AI credits. Both approaches answered the core questions accurately, but the focused server needed substantially fewer tool calls and returned APIM-specific results directly. Azure MCP produced broader infrastructure detail in some responses, but did so through additional discovery, CLI, and REST operations.

Related MCP server: Microsoft Sentinel Data Exploration

Connect to a deployed server

VS Code and GitHub Copilot

Add the server URL supplied by the operator to .vscode/mcp.json:

{
  "servers": {
    "apim": {
      "type": "http",
      "url": "https://<app>.<region>.azurecontainerapps.io/mcp"
    }
  }
}

Run MCP: List Servers and start apim. VS Code discovers the Entra OAuth configuration, prompts you to sign in, and refreshes tokens automatically. You do not add an Authorization header or mint tokens manually.

Your account must be assigned the Apim.Read app role on the server's Entra enterprise application. All authorized users see the APIM instances configured by the server operator.

Connect to a local server

Start the server with make run, then use http://localhost:8000/mcp in .vscode/mcp.json. The local endpoint uses the same VS Code OAuth discovery and sign-in flow as the deployed endpoint. The only difference is outbound Azure authentication: local development uses your az login session, while the deployed server uses its managed identity.

Foundry

azd ai connection create apim-mcp-conn \
  --kind remote-tool \
  --target "https://<app>.<region>.azurecontainerapps.io/mcp" \
  --auth-type user-entra-token \
  --audience "https://<app>.<region>.azurecontainerapps.io/mcp"

Set require_approval: "never" because every exposed tool is read-only.

Available tools

Every tool accepts response_format: "markdown" | "json". List tools support pagination, and tools that accept a service parameter use the friendly alias configured by the server operator, such as prod.

Service discovery

API configuration

Search

Telemetry

Telemetry requires each existing APIM service to already route AllMetrics to the configured Log Analytics workspace. Gateway logs can use either the resource-specific ApiManagementGatewayLogs table or legacy GatewayLogs records in AzureDiagnostics. This repository does not modify APIM diagnostic settings. Metric dimensions are not available through the diagnostic export; use the gateway-log tools for API, operation, response-code, and error breakdowns.

The implemented tool list evolves with docs/development/TASKS.md; clients discover the currently registered set directly from the server.

Example requests

• “List the APIs on prod that do not require a subscription.”

• “Find operations related to inventory or stock levels.”

• “Show the effective policy for the orders API.”

• “Which hostname certificate expires first?”

• “Show aggregate request volume and capacity for prod over the last hour.”

• “Summarize the most common gateway errors on prod in the last 24 hours.”

• “List the named values marked secret.” The server returns names and flags, never the secret contents.

Access and safety

• The server is read-only.

• It never retrieves subscription keys, named-value secrets, gateway keys, user tokens, certificate contents, or backend credentials.

• The server operator controls which APIM instances are available.

• In v1, every authorized caller sees the same configured instances because downstream Azure access uses the server's managed identity.

• Every tool invocation is audited with caller identity and arguments, not response bodies.

User troubleshooting

Documentation

Feature guides

• Authentication and access control

• API and operation search

• Metrics and gateway-log telemetry

Development

• Principles — non-negotiable security and design rules

• Technical specification

• Implementation tasks

• Log Analytics query catalog

• Local testing and fixtures

Operations

• Deployment guide

• Runbook