Task 7 — Publish and govern an HR MCP server through APIM

Part of the Govern AI models and agents through an API gateway lab. New here? Start with Getting started.

Starting here on its own? You need the Citadel hub and a sample spoke deployed, plus Azure CLI signed in and able to acquire a delegated token for the MCP scope. This task also has a setup step: you must deploy and publish the HR MCP server (scripts below) before running its notebook. From the Labfiles/G-govern-ai-through-a-gateway folder, run python setup/check_env.py --task 7 to confirm the hub and spoke are deployed and see the setup reminder.

Continuing from a previous task? Nothing from earlier tasks is required here — the MCP server, its APIM access contract, and its policies are all created by the scripts in this task. Reuse the same deployed hub, spoke, and Python environment.

Model Context Protocol (MCP) is how agents discover and call tools. This task governs an MCP server the same way you’ve governed everything else: put it behind API Management, wrap it in an access contract with a rate limit, and let agents reach its tools only through the gateway.

Why publish an MCP server through APIM?

An MCP server exposes tools — functions an agent can call. Letting agents hit the MCP server directly means no central control over who calls which tool, how often, or with what auth. Publishing it through APIM gives the MCP endpoint the same access contract every other Citadel workload has: a subscription key, delegated authorization, and policy. In this task the policy adds a 5 tool calls per 30 seconds rate limit, so a runaway agent can’t hammer your tools.

Set up: deploy and publish the HR MCP server

Everything for this task lives under workshop/mcp-hr/. Run these from the workshop folder with Azure CLI signed in. On macOS or Linux, use the matching .sh scripts.

  1. Deploy the MCP server — provisions the Container Apps host, container registry, telemetry, and Entra auth settings:

     pwsh -File ./mcp-hr/scripts/deploy-hr-mcp.ps1

  2. Publish it to APIM — creates the APIM MCP API, backend, Citadel product, subscription, and policies:

     pwsh -File ./mcp-hr/scripts/publish-hr-mcp-apim.ps1

  3. Validate direct and APIM-mediated access:

     uv run python ./mcp-hr/scripts/test-hr-mcp-direct.py
 uv run python ./mcp-hr/scripts/test-hr-mcp-apim.py

    Both scripts should complete successfully before you open the notebook.

Exercise the governed MCP endpoint

  1. In VS Code, open 9. publish-and-use-hr-mcp-via-apim.ipynb from the workshop folder and select the workshop/.venv kernel.

  2. Run Steps 0–2 to initialize variables from your azd environment, verify your Azure CLI sign-in, and resolve the APIM MCP endpoint and access-contract settings. Note that the notebook only ever talks to the MCP server through APIM — it never resolves the Container Apps endpoint directly.

  3. Run the remaining cells to:

    • validate the Citadel-style APIM access contract for the MCP endpoint;
    • exercise the MCP protocol and tool calls through the gateway;
    • trigger the 5 tools/call per 30 seconds rate-limit policy and observe the throttled responses;
    • inspect the APIM logs for the MCP traffic;
    • configure a Microsoft Agent Framework agent whose tools come from the APIM-published MCP endpoint, using delegated authorization plus the APIM subscription-key header.
How does the agent authenticate to an APIM-published MCP server?

Two layers, both enforced at the gateway. The caller presents a delegated Entra token (proving who is calling) and the APIM subscription key for the MCP access contract (proving the call is part of a governed contract). APIM validates both before forwarding to the MCP backend, then applies the tool-call rate limit. The agent framework just adds those two headers — the governance lives in APIM.

Clean up the MCP resources

The MCP deployment creates resources inside the shared hub network, so tear them down before you run azd down for the hub:

pwsh -File ./mcp-hr/scripts/teardown-hr-mcp.ps1

The teardown is best-effort and idempotent — resources that are already gone are skipped.

✅ Checkpoint: The HR MCP server is reachable only through APIM, its tool calls are rate-limited by policy, and a Microsoft Agent Framework agent consumes those tools through the governed endpoint. You’ve now governed models, access, data, agents, and tools through one gateway.

Next: You’ve completed the optional tasks. Head back to the lab overview for a summary and clean-up steps.