Homestead Foundry

Appearance

SPIKE-17: Governing Foundry Agent MCP tools with an Azure API Management AI gateway ​

Role: foundry-researcher (Opus). Status: research spike complete. No Azure resources created, no spend, no software installed, no model API called. First-party documentation review only. Date: 2026-07-24 Scope: independent, first-party assessment of the Microsoft Foundry "Govern MCP tools by using an AI gateway (preview)" feature: what it does, what it requires, what it costs and constrains, and whether it applies to this repo's current Foundry deployment or only to a future agent phase. Every factual claim is grounded in a first-party (Microsoft Learn) source, cited inline. Anything not published first-party is marked UNKNOWN with the test or doc that would resolve it. This spike feeds ADR-0012; it authorizes no deployment and no spend.

Grounding read first: this spike's brief (the tasking), the live deployment shape (the aif-<workload>-<env>-<region>-01 AIServices account with its model deployments and Foundry project), ADR-0005 (identity), ADR-0007 (content safety), ADR-0009 and ADR-0011 (the agent-adjacent reviewer and multi-target tracks). This spike verifies and deepens against Microsoft Learn; it does not restate the plans.

Question ​

Six questions from the tasking, answered against first-party sources:

  1. What is the "Govern MCP tools by using an AI gateway" feature, and what does it actually control?
  2. What are its prerequisites (the API Management dependency, roles, and the resource-level enablement)?
  3. What identity and authentication options does it support for the governed MCP servers, and how do they line up with this repo's managed-identity-first stance (ADR-0005)?
  4. What does it cost and how complex is it to stand up and operate?
  5. What are the preview limitations and the specific things it does NOT do?
  6. Does it apply to this repo's current model-deployment backbone, or only to a later agent phase? What is the recommendation to ADR-0012?

Findings ​

Q1. What the feature is, and the exact surface it governs ​

  • It routes the Model Context Protocol (MCP) traffic that Foundry AGENTS make to their tools through an AI gateway, giving "a single, governed entry point where you can enforce authentication, rate limits, IP restrictions, and audit logging without modifying your MCP servers or agent code." The AI gateway is Azure API Management (APIM). Source: Govern MCP tools by using an AI gateway (preview).
  • The unit being governed is an agent's MCP tool, not a model deployment. The workflow is: add an MCP tool in the Foundry portal (from the tool catalog or a custom Model Context Protocol tool), and after the AI gateway is connected the tool's remote MCP server endpoint is rewritten to the gateway URL (for example `https://<your-API-Management-instance>.azure-api.net/mcp/...`) rather than the direct MCP server URL. Governance policies are then applied in APIM. Source: governance.
  • Governance is enforced with APIM policy XML. The documented policies are rate limiting (rate-limit-by-key), IP filtering (ip-filter), a correlation-id header (set-header with @(context.RequestId)), removal of sensitive headers (delete Cookie / Referer, but not Authorization), and simple backend routing (choose / set-backend-service). Source: governance.
  • The broader APIM AI gateway is one runtime boundary for models, agents, and tools, of which MCP tool governance is one slice. The same APIM AI gateway that fronts a Foundry resource can also apply model-layer token quotas and rate limits, register agents for a central control-plane inventory, and publish approved MCP tools to a catalog. Sources: AI gateway in Azure API Management, Configure AI Gateway in your Foundry resources.

The precise thing to hold onto: this feature governs how an agent REACHES a tool (auth, throttle, IP allowlist, audit of gateway traffic). It is not a content-safety filter on what a model generates, and it does not apply to direct REST/SDK calls to model deployments unless the same APIM AI gateway is separately configured for the model layer.

Q2. Prerequisites: the APIM dependency, roles, and resource-level enablement ​

  • An APIM instance must be connected to the Foundry resource, and governance is activated at the Foundry-RESOURCE level. "All governance functionality depends on this connection." You enable the AI gateway from the Foundry portal Admin console (Operate > Admin console > AI Gateway tab), either creating a new APIM instance or reusing an existing one. Sources: governance, Configure AI Gateway.
  • A new gateway created from the Foundry portal provisions a Basic v2 APIM SKU, described as "designed for development and testing with SLA support." To reuse an existing APIM instance it must be in the SAME Microsoft Entra tenant and subscription as the Foundry resource, be in one of the APIM v2 tiers, and you must hold at least API Management Service Contributor (or Owner) on it. Sources: Configure AI Gateway, v2 service tiers overview.
  • The role to manage the policies is API Management Service Contributor or Owner on the connected APIM instance. To CREATE the APIM instance you need Contributor or Owner on the target resource group or subscription; to manage an existing one you need API Management Service Contributor. To enable the gateway in the Foundry portal you need a Foundry Account Owner or Foundry Owner role on the Foundry resource. Sources: governance, Configure AI Gateway, prerequisites, Use RBAC for API Management.
  • The MCP server must support one of four auth methods to be eligible for gateway routing: managed identity (Microsoft Entra), key-based (API key or token), custom OAuth identity passthrough, or unauthenticated. Managed-OAuth tools are explicitly NOT eligible. Source: governance.
  • Networking caveat for a locked-down Foundry resource. If the Foundry resource has public network access disabled, the APIM instance must also be privately reachable (Standard v2 or Premium v2 with a private endpoint, or Premium v2 injected into a virtual network). Source: Configure AI Gateway, existing-instance requirements.

Q3. Identity and authentication, against this repo's managed-identity-first stance ​

  • MCP tool authentication supports key-based, Microsoft Entra (agent identity or project managed identity), OAuth identity passthrough (managed or custom), and unauthenticated. Microsoft's own guidance: "When in doubt, start with Microsoft Entra authentication if the MCP server supports it. Microsoft Entra authentication eliminates the need to manage secrets and provides built-in token rotation." Source: Set up authentication for Model Context Protocol (MCP) tools.
  • This lines up cleanly with ADR-0005 (managed identity over service principal, secrets by name only). The Entra options (agent identity and project managed identity) are the keyless, secret-free path and are the natural default for this repo. Where an MCP server only supports key-based auth, the key is stored in a Foundry project connection (not in git), consistent with this repo's no-secrets rule and ADR-0005's "names only in git, values only in the vault or the secret store" handling. Sources: MCP authentication, key-based, ADR-0005 (docs/adr/ADR-0005-identity-and-secrets.md).
  • A governance nuance for custom MCP servers: with managed OAuth on Microsoft Entra, Agent Service blocks a Microsoft-audience token from being sent to a custom or third-party MCP endpoint (Cannot pass Microsoft token to untrusted MCP endpoint), so a custom MCP server must use custom OAuth with its own app registration audience. This matters when this repo's own HCS Governance MCP is wired to an agent: it would use Entra managed identity or custom OAuth with its own audience, not managed OAuth passthrough of a Microsoft token, and managed-OAuth tools are in any case NOT gateway-eligible (Q5). Source: MCP authentication, OAuth identity passthrough.

Q4. Cost and operational complexity ​

  • The gateway is a standing APIM instance, which is a real, ongoing cost. The default Foundry-portal path provisions a Basic v2 APIM SKU; production or higher-throughput use is steered to Standard v2 or Premium v2. APIM v2 tiers are billed on an hourly gateway-unit basis, so the instance costs money whenever it exists, independent of how much MCP traffic flows. Sources: Configure AI Gateway, API Management pricing.
  • A free tier for the AI gateway is mentioned but is not a production answer. The Foundry docs note "AI Gateway includes a free tier for Azure API Management," pointing to the APIM pricing page for eligibility. The exact free-tier limits, and whether they cover a sustained agent workload, are not enumerated in the Foundry doc and are recorded as UNKNOWN (#2) pending the live pricing page. Source: Configure AI Gateway.
  • Deleting the gateway does not stop the charge by itself. Removing the AI gateway from the Foundry resource is a separate step from deleting the underlying APIM instance; "disabling a project alone doesn't delete the gateway or stop API Management charges." So the cost is a genuine standing commitment that has to be deliberately torn down. Source: Configure AI Gateway, disable or delete.
  • Operational complexity: policies live in the Azure portal, not the Foundry portal. The APIM policy XML that does the actual governing (rate limits, IP filters, header handling, routing) is authored and applied only through Azure API Management in the Azure portal. That is a second control surface and a second skill set (APIM policy authoring) on top of the Foundry portal. Source: governance, limitations.

Q5. Preview limitations and what it does NOT do ​

Straight from the first-party limitations and troubleshooting sections. Source: governance.

  • Preview, no GA date. The feature is in preview. This repo's already-accepted preview-no-SLA posture (the MAI models, the Arc and Azure Local tracks) carries forward rather than being re-litigated.
  • MCP tools only. AI gateways support only MCP tools. Foundry-based tools such as SharePoint, code-first MCP tools, tools that use managed OAuth, and OpenAPI tools are NOT supported.
  • Routing applied only at tool CREATION time. Existing tools are not automatically mediated; a tool created before the gateway was connected keeps calling its MCP server directly and must be re-created to be governed.
  • Policies only in the Azure portal, not the Foundry portal. As in Q4.
  • The gateway does NOT log tool traces. It logs gateway traffic (APIM metrics and logs, GatewayLogs, response codes like 429 for rate limits and 403 for IP filters); tool-level detail must come from the MCP server's own logs. So this is an access-and-transport audit control, not a tool-call-content audit.
  • It is not a content-safety control for generated media. Nothing on the MCP-tool governance page filters model output; for the children's-content and sensitive-audience safety posture, the model-layer guardrails in ADR-0007 remain the controlling decision. The APIM AI gateway CAN apply a content-safety policy at the MODEL layer as a separate capability, but that is a different configuration from MCP tool routing and is not what this feature provides. Sources: governance, AI gateway in Azure API Management, ADR-0007 (docs/adr/ADR-0007-content-safety-and-responsible-ai.md).

Q6. Applicability to THIS repo's deployment (the crux) ​

  • The live build is a model-deployment backbone, not an agent platform. The proven deployment is the aif-<workload>-<env>-<region>-01 AIServices (Foundry) account hosting the model deployments (image, voice, and reasoning) and a Foundry project, reached DIRECTLY over REST/SDK by the publish pipeline (tools/publish.mjs, tools/tts.mjs, and the image tool), per ADR-0005 and ADR-0008. There are currently NO Foundry Agents and NO MCP tools wired into any agent.
  • Therefore there is nothing for this gateway to route today. The feature governs the MCP traffic that AGENTS make to TOOLS. With no agents and no agent-attached MCP tools, the feature has an empty workload. Adopting it now would provision a standing, paid APIM instance to govern zero tool calls.
  • It becomes relevant in a future AGENT PHASE. The natural trigger is when this repo's planned reasoning and reviewer LLMs (for example gpt-5.6-terra and grok-4-1-fast-reasoning per the roster, or the code and document reviewers surveyed in SPIKE-15 such as Kimi-K2.7-Code and DeepSeek-V4-Pro) are orchestrated as Foundry Agents that call MCP tools, including this repo's own HCS Governance MCP (.mcp.json). At that point the gateway's value (one governed entry point, Entra or key auth enforcement, rate limits, IP allowlist, and gateway-traffic audit) becomes a real WAF Security and Operational Excellence gain, and the standing APIM cost is finally paying for something.
  • It composes with the on-prem tracks but does not replace their governance. ADR-0009 and ADR-0011's Arc-managed on-prem reviewer tracks carry their own Arc/RBAC governance; this gateway is a cloud-Foundry-agent control and does not front on-prem Kubernetes model endpoints. The two are complementary, not overlapping.

What is still UNKNOWN ​

#UnknownWhy it is not in the docsWhat resolves it
1The preview-to-GA timeline and SLA for MCP tool governance via AI gateway.The feature page states "preview" with no GA date.Watch the governance page and the APIM AI gateway release notes for a GA announcement before any production reliance.
2The exact APIM AI gateway free-tier limits, and the Basic v2 / Standard v2 monthly cost for a sustained agent MCP workload.The Foundry doc names a free tier and a Basic v2 default but does not enumerate limits or price; pricing lives on the live APIM pricing page.Read API Management pricing and price the target v2 SKU in the Azure pricing calculator at agent-phase design time; confirm credit coverage in Cost Management on the target subscription.
3Whether the future agents will use portal-created MCP tools at all (a code-first / SDK-created MCP tool is explicitly out of scope for gateway routing).The limitation says "code-first MCP tools" are not supported; the repo's agent-authoring approach is not yet decided.Decide the agent-authoring path in the agent-phase design; if tools are created code-first or via managed OAuth, the gateway does not apply and an alternative control is needed.
4Whether the HCS Governance MCP server supports Entra managed-identity or key auth in the shape the gateway requires.This repo's MCP server auth surface is not documented against the four gateway-eligible methods.Confirm the HCS Governance MCP server's supported auth (managed identity, key, custom OAuth, or unauthenticated) before wiring it to an agent behind the gateway.

None of these blocks the recommendation, because the recommendation does not commit to a deployment now.

Recommendation ​

  1. Do not provision the APIM AI gateway now. The current deployment is a direct-REST model-deployment backbone with no Foundry Agents and no agent-attached MCP tools, so there is nothing for the gateway to govern and standing up a paid APIM instance would buy zero routed calls. This is the honest first-party verdict: the feature is not applicable to the current model backbone.
  2. Adopt it as the governance control for Foundry Agent MCP tools when, and only when, the platform enters an agent phase in which reasoning or reviewer LLMs are orchestrated as Foundry Agents that call MCP tools (including this repo's own HCS Governance MCP). At that point the gateway gives one governed entry point for auth, rate limiting, IP filtering, and gateway-traffic audit, which is a real WAF Security and Operational Excellence gain, and the standing APIM cost is justified by an actual workload.
  3. Default the MCP auth to Microsoft Entra (managed identity), per ADR-0005. Prefer the agent-identity or project-managed-identity Entra path for gateway-eligible MCP servers to keep the platform keyless; fall back to key-based auth stored in a Foundry project connection (never in git) only where an MCP server cannot do Entra. Managed-OAuth tools are not gateway-eligible, so they are excluded by design.
  4. Keep content safety where it belongs. This gateway governs tool ACCESS, not generated-content safety. For children's-content and sensitive-audience safety, ADR-0007's model-layer guardrails remain the controlling decision; the gateway complements it by constraining which tools an agent can reach and by auditing gateway traffic, but it does not filter model output.
  5. Follow the standard gate: spike -> ADR -> design -> gated deploy. This spike feeds ADR-0012, which should record the decision to adopt the gateway GATED to the agent phase, provision nothing now, and resolve UNKNOWN #2 (cost and free-tier limits) and UNKNOWN #3 and #4 (tool-authoring path and MCP server auth) at agent-phase design time.

Net: the Foundry Agent MCP tool AI gateway is a genuine, first-party governance control, but it governs agent-to-tool MCP traffic, of which this repo currently has none. It is not needed for the model-deployment backbone and should be adopted, on a managed-identity-first footing, only once the agent phase actually runs Foundry Agents that call MCP tools. Record the finding, provision nothing, and gate any adoption behind ADR-0012 and the agent-phase design.

Sources ​

All first-party (Microsoft Learn unless noted), reviewed 2026-07-24:

  • Govern MCP tools by using an AI gateway (preview): the feature, the APIM dependency, resource-level enablement, the four eligible MCP auth methods, the policy XML examples (rate-limit-by-key, ip-filter, correlation-id, sensitive-header removal, backend routing), the troubleshooting notes, and the limitations (MCP-only, tool-creation-time routing only, policies in the Azure portal only, no tool traces): https://learn.microsoft.com/azure/foundry/agents/how-to/tools/governance
  • Configure AI Gateway in your Foundry resources: resource-level AI gateway enablement from the Admin console, Basic v2 default SKU, existing-instance requirements (same tenant and subscription, v2 tier, API Management Service Contributor or Owner), RBAC to create versus manage, the free-tier note, private-networking caveat, and the disable-versus-delete cost behavior: https://learn.microsoft.com/azure/foundry/configuration/enable-ai-api-management-gateway-portal
  • Set up authentication for Model Context Protocol (MCP) tools: key-based, Microsoft Entra agent identity, Microsoft Entra project managed identity, OAuth identity passthrough (managed and custom), and unauthenticated methods; the "start with Microsoft Entra" guidance; the untrusted-audience block on managed-OAuth Microsoft tokens to custom MCP servers: https://learn.microsoft.com/azure/foundry/agents/how-to/mcp-authentication
  • AI gateway in Azure API Management: the APIM AI gateway as one boundary for models, agents, and tools; MCP server support; model-layer content-safety and token-limit capabilities distinct from MCP tool routing: https://learn.microsoft.com/azure/api-management/genai-gateway-capabilities
  • Bring your own AI gateway to Azure AI Agent Service (preview): the broader Foundry Agent Service tool-support context for gateways: https://learn.microsoft.com/azure/foundry/agents/how-to/ai-gateway
  • Use role-based access control in Azure API Management (API Management Service Contributor / Owner scope): https://learn.microsoft.com/azure/api-management/api-management-role-based-access-control
  • API Management v2 service tiers overview (Basic v2, Standard v2, Premium v2; eligibility for the AI gateway integration): https://learn.microsoft.com/azure/api-management/v2-service-tiers-overview
  • Azure API Management pricing (first-party azure.microsoft.com; the standing-cost basis and free-tier eligibility to confirm at design time): https://azure.microsoft.com/pricing/details/api-management/
  • Local, this repo: this spike's brief (tasking); the live aif-<workload>-<env>-<region>-01 deployment shape; docs/adr/ADR-0005-identity-and-secrets.md (managed-identity-first, secrets by name only); docs/adr/ADR-0007-content-safety-and-responsible-ai.md (model-layer safety posture for sensitive audiences); docs/adr/ADR-0008-publish-pipeline-integration.md (the direct-REST publish pipeline); docs/adr/ADR-0009-azure-local-reviewer-track.md and docs/adr/ADR-0011-multi-target-deployment-automation.md (the reviewer and multi-target tracks, and the preview-risk posture); the model roster (the planned reasoning and reviewer LLMs); docs/research/SPIKE-15-niche-reviewer-models.md (the reviewer-model candidates that would front an agent phase); .mcp.json (this repo's own HCS Governance MCP server).