Azure AI Gateway Labs
Documentation Open portal
MCP & tools · Lab 05

Control which tools agents can call

Publish only approved MCP tools with name patterns, block risky tools, take a whole MCP server offline, and cap tool traffic per caller with a request rate limit.

Intermediate 20 min PortalCLIBicepTerraform Updated
Source Edit

What you'll do

  • Choose between allowing all tools and matching tools by exact name or wildcard pattern, in the portal, with the Azure CLI, with Bicep and azd, or with Terraform
  • Block specific tools with patterns that take precedence over the allow list
  • Take a whole MCP server offline without deleting it
  • Add a request rate limit to an MCP server in the portal, with the Azure CLI, with Bicep and azd, or with Terraform, and trigger a 429

Before you start

Tracks: Portal, Azure CLI, Bicep + azd, Terraform

The learn MCP server that you federated now publishes every tool from two backends. Your security team has two requests: agents should search documentation but not fetch arbitrary pages, and the code sample tool stays off until its review is done. Operations adds a third: a looping agent must not flood the backends. In this lab you publish only the approved tools, block one explicitly, and give each caller a request budget.

Before you begin

One-time setupThe Setup guide tasks that this lab uses. Mark each one done once, and the labs stop listing it.

Tip

On the Bicep + azd and Terraform tracks, azd up or terraform apply creates its own gateway, the learn MCP server with its tool controls and request rate limit, and a key, so you can skip this section. You need only the one-time setup above.

  • Complete Federate MCP tools behind one endpoint. You need the learn MCP server with its learn and docs backends, and a runtime API key from AccessAPI keys.
  • Permission to change the gateway, for example Contributor on the resource group.
  • Run the scripts and samples from the lab's folder, ~/aigateway/labs/05-mcp-tool-controls.

Set these variables once. Every track and the Verify section reuse them.

# Name the resource group and the gateway that hold the learn MCP server from lab 04
export RG="<resource-group>"
export GATEWAY="<gateway>"
echo "📝 Gateway $GATEWAY in $RG"

# Read the gateway's runtime URL, which every MCP endpoint starts with
export AI_GATEWAY_URL="https://$(az aigateway show -g "$RG" -n "$GATEWAY" --query properties.frontend.defaultHostname -o tsv)"
echo "🌐 Runtime URL: $AI_GATEWAY_URL"

# Paste the runtime key that you created in Access › API keys, without showing it
# Don't commit the key or write it to a file
printf "AI Gateway API key: " && read -rs AI_GATEWAY_API_KEY && export AI_GATEWAY_API_KEY && echo
echo "🔑 Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"

How it works

An MCP server has three layers of tool control. The gateway applies all of them before it calls a backend.

ControlWhereEffect
Tool availabilityEditToolsAllow all tools publishes every tool, including tools that backends add later. Match tools by name pattern publishes only the tools that match an entry under Allowed tool name patterns. Tools that don't match aren't listed and can't be called.
Blocked toolsEditToolsNames or patterns that the gateway refuses to run. Blocked entries take precedence over the allow list. Blocked tools remain visible to clients, but a call returns isError: true and tells the agent not to retry.
MCP server accessEditBasic infoActive or Blocked. Blocked MCP servers can't be reached by clients, whatever their tool rules say, and keep their tool settings.
Request rate limit policyThe server's Policies tabA number of Calls per Renewal period for each counter. Over the limit, the gateway answers 429 with Retry-After.

Patterns use * for any number of characters and ? for exactly one. They match the final tool names that the gateway publishes, including the namespace prefix of each backend, such as learn_. This lab uses *_search to allow both search tools and *code_sample* to block the code sample tool. Both patterns start with *, so they cover every backend of the server. For one backend only, start the pattern with its namespace, as in learn_*.

Note

The tool controls are the MCP server's allowList, blockList, and accessState properties. The aigateway extension sets the first two with --allow-list and --block-list, but has no option for server access yet, so the Azure CLI track in Take the whole server offline sets accessState with az rest. In a template, the preview name blocked is ignored without an error, so check the server after you deploy.

Publish only approved tools

Pick one track. Each publishes the same catalog on the learn server: the tools that match *_search, with *code_sample* blocked. Make sure the patterns cover every tool that your agents legitimately need before you save. Tools that don't match are no longer listed or callable.

Choose your track
1

Open the Tools section

Open the AI Gateway portal and select your gateway. Select MCP servers, open Microsoft Learn (the learn server), and select Edit. The editor is one page: scroll past Basic info and Backends to Tools.

2

Allow the search tools by pattern

Under Tool availability, select Match tools by name pattern. Under Allowed tool name patterns, enter *_search in the Tool name pattern row. To allow more patterns, select Add pattern for each one.

3

Block the code sample tool

Under Blocked tools, select Add blocked tool and enter *code_sample* in the new Tool name pattern row.

Edit MCP server › Tools: allowed name patterns publish the matching tools, and blocked patterns stop the matching tools from running.
4

Save the server

Select Save. Under Tools, the details page shows Allowed tools (1) with *_search and Blocked tools (1) with *code_sample*.

1

Check the catalog

Run the script from Federate MCP tools behind one endpoint. This lab includes a copy, so run it from this lab's folder. It lists the tools and calls an allowed one.

# List the tools that the learn MCP server publishes, then call the allowed search tool
echo "🔧 Tools on the learn MCP server, and a call to learn_microsoft_docs_search:"
./infra/list-tools.sh learn learn_microsoft_docs_search "What is AI Gateway?"

On GitHub, open list-tools.sh or list-tools.ps1.

The list has four tools, the search tools and the code sample tools of both backends. The *_fetch tools are gone because they don't match *_search. The code sample tools are still listed, because blocked tools stay visible. The call to learn_microsoft_docs_search returns Microsoft Learn results.

Checkpoint

tools/list returns four tools and no *_fetch tool, and an allowed search tool still works.

Take the whole server offline

Sometimes you need to stop all tool traffic at once, for example while you investigate a misbehaving backend. Blocking the server keeps its backends, tool rules, and policies, so you can turn it back on in one step.

Choose your track
1

Block the server

On the learn details page, select Edit. Under Basic info, set MCP server access to Blocked, leave Backends and Tools unchanged, and select Save. Under MCP configuration, the details page shows MCP status Blocked.

2

Confirm that clients can't connect

# Try to connect to the blocked server: the MCP handshake fails before any backend is called
echo "🚦 Expect initialize to fail with AccessBlockedByGateway:"
./infra/list-tools.sh learn

The script stops at initialize. The gateway answers with HTTP 200 and a JSON-RPC error, Access to MCP server 'learn' is blocked., with the code AccessBlockedByGateway. No backend is called.

3

Turn the server back on

Select Edit again, set MCP server access to Active, and select Save. Run the script again to confirm that the four tools are back.

Rate-limit the MCP server

A request rate limit counts calls instead of tokens. That suits tools, where one agent in a loop can send hundreds of calls a minute. Pick one track. Each produces the same policy on the learn server: 5 calls per 30 seconds for each caller identity. The limit is deliberately low so you can trigger it quickly.

Choose your track
1

Start the policy wizard

Select PoliciesAdd policy. On the Type step, under Cost and rate limits, select Request rate limit, then Next.

2

Choose the MCP server

On the Scope step, select Individual assets ("Apply only to selected models, aliases, or MCP servers"). Search the assets for Microsoft Learn, select the row of the learn MCP server, then select Next.

3

Configure the limit

On the Details step, under Policy details, set:

FieldValue
Calls5, in place of the default 100
Renewal period30 seconds, in place of the default 60 seconds
Counter dimensionsIdentity, which is selected by default

The other renewal periods are 60 seconds, 2 minutes, and 5 minutes. Identity gives each API key, and each Entra caller, its own counter, and IP address gives each client address one. If you clear both, all callers share one counter. Select Create.

Checkpoint

Open the learn server and select its Policies tab. It lists a Request rate limit with the scope This MCP server and the configuration 5 requests / 30 seconds per caller identity. The gateway's Policies page can still show No policies configured, because it doesn't list the policies of single assets.

Verify

The rate limit counts the calls you make while you verify, too. Every MCP request counts, including the two handshake messages that each script run starts with. Wait 30 seconds between steps so each one starts with a fresh window.

1

Call a blocked tool

The code sample tool is still listed, but the gateway refuses to run it:

# List the tools, then try to call the code sample tool, which is listed but blocked
echo "🚦 Expect the call to learn_microsoft_code_sample_search to fail:"
./infra/list-tools.sh learn learn_microsoft_code_sample_search "Python MCP client"

The tool list prints as before, and then the script prints The tool call failed: and the gateway's answer: a 200 response with "isError": true, the text Tool 'learn_microsoft_code_sample_search' is blocked by the gateway. Do not retry this tool., and the denial code ToolNotAvailable. The Learn backend never receives the call.

2

Run the burst

Wait 30 seconds, then send a handshake followed by eight tools/list requests:

# Send the MCP handshake and eight tools/list requests, and print the status and Retry-After of each one
echo "🚦 Expect 429 Too Many Requests after the limit of 5 calls per 30 seconds:"
./infra/trigger-request-rate.sh learn 8

On GitHub, open trigger-request-rate.sh or trigger-request-rate.ps1.

Expected output (your Retry-After values will differ):

Text
🚦 Expect 429 Too Many Requests after the limit of 5 calls per 30 seconds:
Request  Method                      Status  Retry-After
1        initialize                  200     -
2        notifications/initialized   202     -
3        tools/list                  200     -
4        tools/list                  200     -
5        tools/list                  200     -
6        tools/list                  200     -
7        tools/list                  200     -
8        tools/list                  429     4
9        tools/list                  429     3
10       tools/list                  429     2

Last response body:
{ "statusCode": 429, "message": "Rate limit is exceeded. Try again in 2 seconds." }

The counter is approximate, so the gateway can let a call or two beyond the limit through before the first 429. Retry-After counts down to the end of the current 30-second window, so it can be anything from 1 to 30 seconds. If the burst returns 502 in place of 429 right after you change the server or its policy, the change is still rolling out. Wait a minute and run the burst again.

3

Inspect one throttled response

Right after the burst, while you're still throttled, send one raw request and look at the status line and headers. If it returns 200, the window has already renewed. Run the burst again, then this command.

Bash
# Send one raw tools/list request, and show its status line, headers, and body
echo "🚦 Expect HTTP 429 with a retry-after header:"
curl -i "${AI_GATEWAY_URL%/}/default/toolservers/learn/mcp" \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The status line is HTTP/2 429, the headers include retry-after, and the body is the same JSON error. The Retry-After value tells the client how many seconds to wait. Agent frameworks should back off for that long instead of retrying in a tight loop.

Checkpoint

The *_fetch tools are no longer listed, a call to the blocked code sample tool fails, an allowed search tool works, and calls over the limit in a 30-second window get 429 with Retry-After.

Go further

  • Prefer exact names for sensitive servers. Patterns also publish tools that a backend adds later. For servers whose new tools need a review first, list each tool by its full name, such as learn_microsoft_docs_search, with no * or ?.
  • Block destructive operations everywhere. For a server built from an OpenAPI spec, keep Allow all tools and add blocked patterns such as *_delete_* so new read operations appear automatically but deletions never run.
  • Set a default for every MCP server. Add a Request rate limit with Gateway scope in Set gateway-wide policy baselines.
  • Inspect tool calls for attacks. Add Agent 365 tool threat protection in Protect tool calls with Agent 365 threat protection.

Clean up

A 5-call limit will throttle real agents. Remove it, and open the tool catalog again, before you continue.

Choose your track
1

Remove the policy and restore the catalog

  1. Select MCP servers, open Microsoft Learn (the learn server), and select its Policies tab. In the row 5 requests / 30 seconds per caller identity, select More actionsDelete, then Delete in Delete this policy?.
  2. Select Edit and scroll to Tools. Select Allow all tools, remove the *code_sample* blocked pattern, and select Save.

Keep the gateway, the learn MCP server, and your key from lab 04. The next labs reuse them. azd down and terraform destroy don't touch them, because the Bicep + azd and Terraform tracks created their own gateways.

Next steps

Finished the lab?

Mark it complete to track your progress across paths. It's saved only in this browser.