Azure AI gateway skill: API Management policies for models, MCP tools and agents

Source: microsoft/azure-skills · Maintainer: Microsoft · License: MIT · Checked: 27 October 2026

What is the Azure AI gateway skill?

The Azure AI gateway skill teaches a coding agent to put Azure API Management (APIM) in front of AI models, MCP tools and agents, then govern that traffic with policies. It covers adding an Azure OpenAI or Foundry backend, token limits, semantic caching, content safety, rate limits for tools, and a curl test through the gateway.

Its description opens: "Configure Azure API Management as an AI Gateway for AI models, MCP tools, and agents." Trigger phrases in the description include "semantic caching", "token limit", "jailbreak detection", "add Azure OpenAI backend" and "convert API to MCP".

The skill ships in microsoft/azure-skills, the Azure Skills Plugin. The README lists it under "Work across data, AI, identity, and platform services". The SKILL.md frontmatter lists version 3.2.1, author Microsoft, and this compatibility note: "Requires Azure CLI (az) for configuration and testing".

As of 27 October 2026, its skills.sh page listed about 566,700 installs (snapshot, 27 October 2026).

What does it do?

The SKILL.md is short, about 5 KB. It sorts requests into five groups, then hands off to reference files for the details.

Read the gateway. It starts with az apim show for the gateway URL, az apim backend list for configured backends, and az apim subscription keys list for a key to test with.

Add a model backend. references/patterns.md walks through finding Azure OpenAI or Foundry resources, turning on a system-assigned managed identity for APIM, granting it the "Cognitive Services User" role on the model resource, creating the backend, importing the Azure OpenAI OpenAPI spec, and adding an authentication-managed-identity policy. Later patterns cover load balancing across regions, exposing an API as an MCP tool, streaming responses and per-tenant limits.

Apply policies in order. The skill recommends this order in the <inbound> section: authentication, semantic cache lookup, token limits, content safety, backend selection, then token metrics. references/policies.md has XML for each:

• azure-openai-token-limit for tokens per minute per subscription or custom key.
• azure-openai-semantic-cache-lookup and -store for reusing answers to similar prompts.
• azure-openai-emit-token-metric for token counts in Azure Monitor, with a sample KQL query.
• llm-content-safety for blocking harmful prompts through Azure AI Content Safety.
• rate-limit-by-key for capping calls to MCP tools per agent or subscription.

Troubleshoot. references/troubleshooting.md covers backend 401s (missing identity or role), 429s from the token limit versus 429s from the model's own quota, caches with no hits, and content safety false positives.

SDK notes. A references/sdk/ folder holds short quick starts for the Content Safety SDK (Python, TypeScript) and the API Management management SDK (Python, .NET). references/auth-best-practices.md steers toward managed identity in production.

Microsoft's own overview of the feature set is the AI gateway capabilities page on Microsoft Learn, which the skill links as a reference.

How do you install the Azure AI gateway skill?

The repo README documents several routes. The full plugin installs every Azure skill plus the Azure MCP Server and Foundry MCP.

Claude Code: the Azure Skills Plugin. Run inside Claude Code:

/plugin install azure@claude-plugins-official

Or run /plugin and search for "azure". Update later with /plugin update azure@claude-plugins-official. See Claude Code plugins and Claude Code MCP.

GitHub Copilot CLI:

/plugin marketplace add microsoft/azure-skills
/plugin install azure@azure-skills

Codex, Cursor and Gemini CLI. For Codex, the README says to run codex plugin marketplace add microsoft/azure-skills, then install azure from /plugins. For Cursor, use the Cursor Marketplace or Settings, then Plugins. For Gemini CLI, run gemini extensions install https://github.com/microsoft/azure-skills. See Codex skills and Cursor skills.

Skill only. The command on skills.sh copies just this folder:

npx skills add https://github.com/microsoft/azure-skills --skill azure-aigateway

Prerequisites, per the README: an Azure account or subscription, Node.js 18 or later on your PATH, and the Azure CLI signed in with az login. You also need an existing APIM instance; the skill says to use azure-prepare to deploy one.

How do you use it?

Name the APIM instance, resource group and model resource, and say what you want governed. The skill is model-invoked, so the agent loads it when your request matches its triggers.

Example prompts (suggestions, not quotes from the repo):

• Add my Azure OpenAI resource aoai-prod as a backend on APIM instance apim-shared, using managed identity.
• Limit each subscription on apim-shared to 20,000 tokens per minute and return a clear error when they hit it.
• Turn on content safety for the chat API on apim-shared and check prompts for jailbreak attempts.
• Expose our orders REST API through APIM as an MCP tool and rate limit it to 10 calls a minute per agent.
• Test the AI gateway: send a hello request through apim-shared to the gpt deployment and show the response headers.

Expect az apim and az role assignment commands plus policy XML to paste into the APIM policy editor or your infrastructure code.

Tips and limits

From the repo, Microsoft Learn and skills.sh, not from testing:

• Turn on prompt shields explicitly. The skill's content safety example says jailbreak detection "is automatic when content safety is enabled". The llm-content-safety policy reference lists a shield-prompt attribute with a default of false, and its example sets it to true "to check for adversarial attacks".
• Thresholds differ. The skill gives content safety thresholds as 0 to 6. Microsoft Learn says the value "must be between 0 (most restrictive) and 7 (least restrictive)", and that a blocked request returns 403; the skill's custom error example returns 400.
• Semantic cache scores run the other way. The skill suggests 0.8 and says to lower it to 0.7 for more hits. The semantic cache lookup reference says "Lower values require higher semantic similarity for a match", suggests starting around 0.05, and warns that scores above 0.2 may cause mismatches.
• Cache backing store. The skill names Azure Cache for Redis Enterprise with RediSearch. Microsoft's AI gateway capabilities page names Azure Managed Redis or another RediSearch-compatible external cache.
• The 60 to 80% savings figure is the skill's. It appears in the quick reference with no source. That Microsoft Learn page says only that caching "can help reduce costs".
• Streaming. The skill's patterns file says semantic caching and token metrics don't work with streaming responses.
• Audits. On skills.sh, Gen Agent Trust Hub and Socket rated the skill Pass on 15 September 2026. Snyk rated it Warn (medium overall) the same day for one finding, W012, which it scores high risk (0.70): the raw.githubusercontent.com URL used to import the Azure OpenAI OpenAPI spec, which it calls an unverifiable external dependency. Pin a spec version you trust if that matters to you.
• Telemetry. The README says to set AZURE_MCP_COLLECT_TELEMETRY=false to turn off Azure MCP telemetry.

The MIT License lets you copy and change the skill as long as you keep Microsoft's copyright and license notices.

Save it in your Kipt library

An edited copy is a good place to fix the details above for your team, such as setting shield-prompt="true" and your own cache threshold. In Kipt, open Skills and paste the skill's GitHub folder link into the import box, or drop the folder or a .zip. The copy carries the skill files only, not the plugin's MCP setup. Skills in your private GitHub repo install into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Kipt is not affiliated with Microsoft.

Similar skills

• Azure AI skill: works with the model, search and speech services that sit behind the gateway.
• Azure prepare skill: plans and generates the infrastructure, including the APIM instance this skill needs.
• Azure diagnostics skill: troubleshooting once traffic is flowing.
• Entra app registration skill: sets up the app identities that call the gateway.
• Azure storage skill: another Microsoft reference skill from the same plugin.