Azure AI Gateway Labs
Documentation Open portal
MCP & tools ยท Lab 30Emerging

Govern MCP tool calls with agent hooks

Run your own allow-or-deny rules on every MCP tool call. An agent hooks policy asks an Azure function before the tool runs and again before the result reaches the agent, authenticated with the gateway's managed identity.

Advanced 40 min PortalCLIBicepTerraform Updated
Source Edit

What you'll do

  • Explain when the gateway calls an agent hook, what it sends, and how an allow or deny verdict changes a tool call
  • Deploy a Python decision service on Azure Functions that only the gateway's managed identity can call
  • Attach an agent hooks policy to an MCP server in the AI Gateway portal, with the Azure CLI, with Bicep and azd, or with Terraform
  • Prove allowed, blocked, and withheld tool calls over MCP, and read the decision log
  • Choose between agent hooks, tool allow and block lists, and tool threat protection, and between fail closed and fail open

Before you start

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

Allow and block lists decide which tools an agent can call, but not what it can do with them. Your rules are often about the call itself: no customer email addresses in a search, no refund above a limit, no secret in a result that goes back to the model. In this lab you write those rules in a small Azure function, and an agent hooks policy on your MCP server asks it for a verdict before each tool runs and again before each result reaches the agent.

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, the decision service, the agent hooks policy, and a key, so you can skip this section. You need only the one-time setup above and permission to register applications in Microsoft Entra ID.

  • Complete Federate MCP tools behind one endpoint. This lab governs the learn MCP server from that lab. Any MCP server in your gateway works.
  • Permission to manage policies on the gateway and to create resources, for example Contributor on a subscription or resource group.
  • Permission to register applications in Microsoft Entra ID. The decision service trusts only tokens issued for its own app registration.
  • A region with the Azure Functions Flex Consumption plan. The lab deploys the function app in the gateway's region; az functionapp list-flexconsumption-locations --query "[].name" -o tsv lists the regions that have it.
  • Your gateway's system-assigned managed identity, which every gateway has. The hook uses it to authenticate.
  • Run the scripts from the lab's folder, ~/aigateway/labs/30-agent-hooks.
Note

Agent hooks are an emerging capability of Azure AI Gateway. Labels and behavior can change; see the release note.

Set these variables once. The steps and the Verify section reuse them.

# Set your resource group and gateway, and the MCP server that you govern
export RG="<resource-group>"
export GATEWAY="<gateway>"
export MCP_SERVER="learn"                    # the MCP server you govern in this lab
echo "๐Ÿ“ Gateway $GATEWAY in $RG, MCP server $MCP_SERVER"

# Read the gateway's resource ID and its runtime URL
export GATEWAY_ID="$(az aigateway show -g "$RG" -n "$GATEWAY" --query id -o tsv)"
export AI_GATEWAY_URL="https://$(az aigateway show -g "$RG" -n "$GATEWAY" --query properties.frontend.defaultHostname -o tsv)"
echo "๐Ÿ†” Gateway ID: $GATEWAY_ID"
echo "๐ŸŒ Runtime URL: $AI_GATEWAY_URL"

# Paste a runtime key from Access โ€บ API keys without showing it: the test script calls tools with it
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 agent hooks policy on an MCP server sends each tools/call to a decision service that you run, and enforces its verdict. The gateway is the host of the Agent Hooks control contract: it posts an AgentContext JSON document to your HTTPS endpoint, and the service answers HTTP 200 with {"decision": "allow"} or {"decision": "deny", "reason": "โ€ฆ"}. Discovery and session traffic, such as initialize and tools/list, isn't sent.

The gateway authenticates to the service with its managed identity (a Microsoft Entra token for the audience that you set), with an API key header, or anonymously, and adds the literal headers that you configure. The mode decides what happens when the service fails or doesn't answer in time: failClosed, the default, blocks the call; failOpen lets it through. Settings at the policy level apply to both hooks, and each hook can override them.

Intervention pointPolicy keyinterception_pointThe service getsEffect of a deny
Before tool callpreToolCallpre_tool_callThe tool name and argumentsThe tool never runs
After tool callpostToolCallpost_tool_callThe tool name, arguments, and resultThe result is withheld, but the tool already ran

Verdicts can only allow or deny: transforms, warnings, and approvals aren't supported.

Review the decision service

The decision service is one Python function, tool-hook, in infra/hook/function_app.py. It answers both intervention points:

PointRuleReason in the verdict
Before tool callThe tool name matches a pattern in the BLOCKED_TOOLS app setting, *code_sample* by defaultblocked_tool:<pattern>
Before tool callThe arguments contain an email addresspersonal_data:email_address
Before tool callThe arguments contain a secret, such as a storage account key, a SAS signature, a private key, or a JWTsecret_in_arguments:<kind>
After tool callThe result contains a secretsecret_in_result:<kind>
EitherNothing matchespolicy_satisfied, with allow
infra/hook/function_app.pyGitHub
"""Agent hooks decision service for Azure AI Gateway (lab 30).

The gateway posts an Agent Hooks AgentContext to /api/tool-hook before a tool runs (interception_point
pre_tool_call) and after the tool returns (post_tool_call). The function answers HTTP 200 with
{"decision": "allow" | "deny", "reason": "..."}.

App Service Authentication (Easy Auth) in front of the app rejects every request that doesn't carry a Microsoft Entra
token for this app from the gateway's managed identity, so the function itself allows anonymous calls.

Rules:
- BLOCKED_TOOLS (app setting): comma-separated tool name patterns that never run, for example *code_sample*
- Tool arguments that contain an email address or a secret-looking string are denied before the call.
- Tool results that contain a secret-looking string are withheld after the call.

The decision log has the tool name, the decision, the reason, and the gateway's request ID. It never has tool
arguments, results, or tokens.
"""
import fnmatch
import json
import logging
import os
import re

import azure.functions as func

app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)

BLOCKED_TOOLS = [p.strip().lower() for p in os.environ.get("BLOCKED_TOOLS", "*code_sample*").split(",") if p.strip()]

EMAIL = re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}")
SECRETS = {
    "storage_account_key": re.compile(r"AccountKey=[A-Za-z0-9+/]{40,}={0,2}"),
    "sas_signature": re.compile(r"[?&]sig=[A-Za-z0-9%+/]{30,}"),
    "private_key": re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----"),
    "openai_style_key": re.compile(r"\bsk-[A-Za-z0-9_-]{20,}"),
    "jwt": re.compile(r"\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}"),
}


def find_secret(text: str) -> str | None:
    """Return the name of the first secret pattern that matches the text, or None."""
    return next((name for name, pattern in SECRETS.items() if pattern.search(text)), None)


def before_call(context: dict) -> tuple[str, str]:
    """Decide whether the tool may run, from its name and arguments."""
    tool_call = context["tool_call"]
    name = str(tool_call.get("name", "")).lower()
    for pattern in BLOCKED_TOOLS:
        if fnmatch.fnmatchcase(name, pattern):
            return "deny", f"blocked_tool:{pattern}"

    args = json.dumps(tool_call.get("args") or {})
    if EMAIL.search(args):
        return "deny", "personal_data:email_address"
    secret = find_secret(args)
    if secret:
        return "deny", f"secret_in_arguments:{secret}"
    return "allow", "policy_satisfied"


def after_call(context: dict) -> tuple[str, str]:
    """Decide whether the caller may see the tool result."""
    # The gateway sends the MCP tool result in target; the Agent Hooks spec also defines tool_result.
    result = json.dumps([context.get("target"), context.get("tool_result")])
    secret = find_secret(result)
    if secret:
        return "deny", f"secret_in_result:{secret}"
    return "allow", "policy_satisfied"


@app.route(route="tool-hook", methods=["POST"])
def tool_hook(req: func.HttpRequest) -> func.HttpResponse:
    try:
        context = req.get_json()
    except ValueError:
        context = None
    if not isinstance(context, dict) or not isinstance(context.get("tool_call"), dict):
        context = {}
        decision, reason = "deny", "invalid_context"
    elif context.get("interception_point") == "pre_tool_call":
        decision, reason = before_call(context)
    elif context.get("interception_point") == "post_tool_call":
        decision, reason = after_call(context)
    else:
        decision, reason = "deny", "unsupported_interception_point"

    logging.info(
        "agent-hook point=%s tool=%s decision=%s reason=%s request_id=%s caller=%s policy=%s",
        context.get("interception_point"), (context.get("tool_call") or {}).get("name"), decision, reason,
        context.get("request_id"), req.headers.get("x-ms-client-principal-id", "none"),
        req.headers.get("x-hook-policy", "none"),
    )
    return func.HttpResponse(json.dumps({"decision": decision, "reason": reason}),
                             status_code=200, mimetype="application/json")

On GitHub, open infra/hook/function_app.py.

Before a call, the gateway posts the tool call. This is a real request for the docs search tool, with the IDs shortened:

JSON
{
  "spec": "agent-hooks/0.1",
  "interception_point": "pre_tool_call",
  "timestamp": "2026-11-16T02:47:51.711Z",
  "sequence": 0,
  "agent": { "framework": "microsoft.azure.aigateway" },
  "tool_call": {
    "id": "2",
    "name": "learn_microsoft_docs_search",
    "args": { "query": "What is Azure Functions?" }
  },
  "target": { "query": "What is Azure Functions?" },
  "request_id": "7c73b7ce-โ€ฆ",
  "trace": { "trace_id": "524b7585โ€ฆ", "span_id": "ea417be7โ€ฆ" }
}

After the call, the request has "interception_point": "post_tool_call", the same tool_call and request_id, and the MCP tool result in target:

JSON
"target": {
  "isError": false,
  "content": [ { "type": "text", "text": "{\"results\":[{\"title\":\"Azure Functions overview\", โ€ฆ}]}" } ]
}

The policy reference also shows a tool_result object, which the gateway doesn't send yet, so the function reads both. It treats any request it can't parse as a deny.

The function allows anonymous calls because App Service Authentication stands in front of it: the platform rejects every request with HTTP 401 unless it carries a Microsoft Entra token issued for the hook's app registration to the gateway's managed identity. Each request also carries the policy's custom headers, here x-hook-policy: lab30, which the decision log records with the caller's object ID.

Important

Keep the decision service fast and available. The gateway waits about 30 seconds for a verdict, and every tool call waits for it. Don't log tool arguments, results, or tokens: this function logs only the tool name, the decision, the reason, and the request ID.

Deploy the decision service

The AI Gateway portal doesn't create function apps or app registrations, so on the Portal track, follow the Azure CLI steps here, then attach the hook in the portal.

Choose your track
1

Register an app for the hook

The gateway asks Microsoft Entra ID for a token whose audience is the hook's application ID URI. Register an app with that URI and create its service principal, so that the gateway's managed identity can get tokens for it. The function app name is func- plus the first part of your gateway's host name, which is unique.

# Name the decision service's resource group and function app, in the gateway's region
export HOOK_RG="rg-aigw-lab30-hook"
export HOOK_APP="func-$(echo "$AI_GATEWAY_URL" | cut -d/ -f3 | cut -d. -f1)"
export LOCATION="$(az aigateway show -g "$RG" -n "$GATEWAY" --query location -o tsv)"
echo "๐Ÿ“ Function app $HOOK_APP in $HOOK_RG, in $LOCATION"

# Register an app for the decision service: the gateway asks Microsoft Entra ID for tokens issued to it
export HOOK_CLIENT_ID="$(az ad app create --display-name "$HOOK_APP" --sign-in-audience AzureADMyOrg --query appId -o tsv)"
echo "๐Ÿ†” App registration $HOOK_APP: $HOOK_CLIENT_ID"

# Give it an application ID URI: the token audience that the policy asks for
export HOOK_AUDIENCE="api://$HOOK_CLIENT_ID"
az ad app update --id "$HOOK_CLIENT_ID" --identifier-uris "$HOOK_AUDIENCE" &&
  echo "๐Ÿ‘ค Token audience: $HOOK_AUDIENCE"

# Create its service principal, so that managed identities in your tenant can get tokens for it
az ad sp create --id "$HOOK_CLIENT_ID" -o none &&
  echo "๐Ÿ‘ค Service principal for $HOOK_APP is ready"
2

Deploy the function app

infra/hook.bicep creates a Python function app on the Flex Consumption plan, with App Service Authentication that lets in only the gateway's identity, a private storage account that the app reaches with its managed identity, and Application Insights for the decision log. It takes three to five minutes.

# Read the object ID of the gateway's managed identity: the only caller that the decision service lets in
export GATEWAY_PRINCIPAL_ID="$(az aigateway show -g "$RG" -n "$GATEWAY" --query identity.principalId -o tsv)"
echo "๐Ÿ‘ค Gateway identity: $GATEWAY_PRINCIPAL_ID"

# Create a resource group for the decision service
az group create -n "$HOOK_RG" -l "$LOCATION" -o none &&
  echo "๐Ÿ“ฆ Resource group $HOOK_RG is ready in $LOCATION"

# Deploy the function app, its network, storage, and logs, without code yet
az deployment group create -g "$HOOK_RG" -n lab30-hook -f infra/hook.bicep -o none \
  -p appName="$HOOK_APP" hookClientId="$HOOK_CLIENT_ID" hookAudience="$HOOK_AUDIENCE" \
  gatewayPrincipalId="$GATEWAY_PRINCIPAL_ID" &&
  echo "๐Ÿš€ Function app $HOOK_APP is deployed"

# Read the hook's URL and the Log Analytics workspace ID from the deployment's outputs
export HOOK_URL="$(az deployment group show -g "$HOOK_RG" -n lab30-hook --query properties.outputs.hookUrl.value -o tsv)"
export HOOK_LOG_WORKSPACE_ID="$(az deployment group show -g "$HOOK_RG" -n lab30-hook --query properties.outputs.logWorkspaceId.value -o tsv)"
echo "๐ŸŒ Hook URL: $HOOK_URL"
echo "๐Ÿ†” Log Analytics workspace ID: $HOOK_LOG_WORKSPACE_ID"
3

Deploy the code

Restart the new app once, so that it reaches its private storage, then zip the function's three files in infra/hook and upload them. Zip only those files, so that local files such as local.settings.json stay on your machine. Flex Consumption builds the app from requirements.txt.

# Restart the new app once: its first upload can fail until it reaches its private storage
az functionapp restart -g "$HOOK_RG" -n "$HOOK_APP" &&
  echo "โณ $HOOK_APP restarted"

# Zip the function's three files from inside its folder
(cd infra/hook && zip -q ../../hook.zip function_app.py host.json requirements.txt) &&
  echo "๐Ÿ“„ hook.zip is ready"

# Upload the code and build it remotely, then delete the zip file
az functionapp deployment source config-zip -g "$HOOK_RG" -n "$HOOK_APP" --src hook.zip --build-remote true -o none &&
  echo "๐Ÿš€ The decision service is deployed to $HOOK_APP"
rm hook.zip

# Call the hook without a token: App Service Authentication answers 401 before the function runs
echo "๐Ÿ” Anonymous call to the hook: HTTP $(curl -s -o /dev/null -w '%{http_code}' -X POST "$HOOK_URL" -H 'Content-Type: application/json' -d '{}')"
Checkpoint

The upload ends with ๐Ÿš€ The decision service is deployed, and the anonymous call prints ๐Ÿ” Anonymous call to the hook: HTTP 401. Keep the values of HOOK_URL and HOOK_AUDIENCE: the portal asks for them.

Attach the hook to the MCP server

Add an agent hooks policy to the learn MCP server that calls your decision service as the gateway's managed identity, and blocks the call when the service fails. The portal configures one intervention point per policy; the Azure CLI, Bicep + azd, and Terraform tracks configure both.

Choose your track
1

Choose the policy type

Open the AI Gateway portal and select your gateway from the gateway switcher. Select PoliciesAdd policy. On the Type step, under Security, select Agent hooks. Its card carries the Preview and MCP server badges and reads "Invoke governance controls at MCP tool-call intervention points, with hooks hosted in any service." Select Next.

Agent hooks sits in the Security group, after Agent 365 tool threat protection. It applies to MCP servers only.
2

Select the MCP server

On the Scope step, the wizard notes that this policy applies to individual MCP servers. Check the learn server, Microsoft Learn in lab 04, then select Next.

Each agent hooks policy belongs to one MCP server. Repeat the wizard for other servers.
3

Configure the hook

On the Details step, set:

FieldValue
Intervention pointBefore tool call
EndpointThe value of HOOK_URL, such as https://func-<name>.azurewebsites.net/api/tool-hook
Failure modeFail closed
AuthenticationManaged identity
Managed identitySystem-assigned managed identity
Token audienceThe value of HOOK_AUDIENCE, such as api://<client-id>
HeadersSelect Add header, then enter x-hook-policy as Header name and lab30 as Value

Then select Create. The hint under Intervention point reads "Only one intervention point is supported in this preview."

Header values are literal and returned by reads, so never put a secret in them. API key authentication keeps its key separately.
4

Check the policy list

The Policies list shows Before tool calls under Configuration, Agent hooks under Type, and MCP server: Microsoft Learn under Scope.

Select the policy to see its settings, edit it, or delete it.

To add After tool call to the same policy, run the Azure CLI track's steps instead: they replace the portal's policy with one that has both intervention points.

Warning

Don't edit a policy with both intervention points in the portal. Its Edit policy panel reads "This policy has both intervention points. Choose one to continue.", and saving keeps only the point that you choose. Change such a policy with the Azure CLI, Bicep, or Terraform.

The portal shows both hooks on the policy's page, but its editor keeps only one.

Call tools through the hook

infra/call-tool.sh runs the MCP handshake and calls one tool with your runtime key. It prints isError: false with the start of the result, or isError: true with the gateway's message.

infra/call-tool.shGitHub
#!/usr/bin/env bash
# Calls one tool on an AI Gateway MCP server with the MCP Streamable HTTP handshake
# (initialize -> notifications/initialized -> tools/call), and prints whether the result came back or the gateway's
# denial: the JSON-RPC error, or isError with the denial details in _meta.
#
# Usage:
#   export AI_GATEWAY_URL="<gateway-url>"
#   export AI_GATEWAY_API_KEY="<runtime key>"            # Access > API keys; never paste it into a file
#   ./call-tool.sh <tool-name> '<arguments as JSON>' [server-name]
#
# Example:
#   ./call-tool.sh learn_microsoft_docs_search '{"query": "What is Azure Functions?"}'
# Requires curl and jq.
set -euo pipefail

TOOL="${1:?Pass the tool name, for example learn_microsoft_docs_search}"
ARGS="${2:-}"
[ -n "$ARGS" ] || ARGS='{}'
SERVER="${3:-learn}"
: "${AI_GATEWAY_URL:?Set AI_GATEWAY_URL to the gateway runtime URL}"
: "${AI_GATEWAY_API_KEY:?Set AI_GATEWAY_API_KEY to a runtime key from Access > API keys}"
command -v jq >/dev/null || { echo "This script needs jq." >&2; exit 1; }
printf '%s' "$ARGS" | jq -e 'type == "object"' >/dev/null || { echo "The arguments must be a JSON object." >&2; exit 1; }
ENDPOINT="${AI_GATEWAY_URL%/}/default/toolservers/${SERVER}/mcp"
HEADERS=(-H "Authorization: Bearer $AI_GATEWAY_API_KEY" -H "Content-Type: application/json"
  -H "Accept: application/json, text/event-stream")
STATUS="" BODY="" SESSION_ID=""

# post <json>: sends one JSON-RPC message and sets STATUS and BODY (and SESSION_ID when the server returns one).
post() {
  local raw head sid
  raw="$(curl -sS --max-time 120 -D - "$ENDPOINT" "${HEADERS[@]}" --data "$1" | tr -d '\r')"
  if [[ "$raw" == *$'\n\n'* ]]; then head="${raw%%$'\n\n'*}"; BODY="${raw#*$'\n\n'}"; else head="$raw"; BODY=""; fi
  STATUS="$(printf '%s\n' "$head" | awk 'toupper($1) ~ /^HTTP/ {code=$2} END {print code}')"
  sid="$(printf '%s\n' "$head" | awk -F': ' 'tolower($1)=="mcp-session-id" {print $2}')"
  if [ -n "$sid" ]; then SESSION_ID="$sid"; fi
}

# response <id>: prints the JSON-RPC response with that id. The body can be JSON or server-sent events.
response() {
  if printf '%s\n' "$BODY" | grep -q '^data:'; then
    printf '%s\n' "$BODY" | sed -n 's/^data:[[:space:]]*//p'
  else
    printf '%s\n' "$BODY"
  fi | jq -c --argjson id "$1" 'select(type == "object" and .id == $id)' 2>/dev/null || true
}

# require_success <step>: stops with the gateway's answer when the HTTP status isn't 2xx.
require_success() {
  case "$STATUS" in
    2??) ;;
    *) echo "$1 failed with HTTP ${STATUS:-no response}:" >&2; printf '%s\n' "$BODY" >&2; exit 1 ;;
  esac
}

post '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"aigateway-labs","version":"1.0"}}}'
require_success "initialize"
PROTOCOL="$(response 1 | jq -r '.result.protocolVersion // empty')"
if [ -z "$PROTOCOL" ]; then echo "initialize returned no result:" >&2; printf '%s\n' "$BODY" >&2; exit 1; fi
HEADERS+=(-H "MCP-Protocol-Version: $PROTOCOL")
if [ -n "$SESSION_ID" ]; then HEADERS+=(-H "Mcp-Session-Id: $SESSION_ID"); fi

post '{"jsonrpc":"2.0","method":"notifications/initialized"}'
require_success "notifications/initialized"

echo "tools/call $TOOL $(printf '%s' "$ARGS" | jq -c .)"
post "$(jq -cn --arg name "$TOOL" --argjson args "$ARGS" \
  '{jsonrpc:"2.0",id:2,method:"tools/call",params:{name:$name,arguments:$args}}')"
require_success "tools/call"
CALL="$(response 2)"
if [ -z "$CALL" ]; then echo "tools/call returned no JSON-RPC response:" >&2; printf '%s\n' "$BODY" >&2; exit 1; fi

echo "HTTP status: $STATUS"
if [ "$(printf '%s' "$CALL" | jq 'has("error")')" = "true" ]; then
  echo "JSON-RPC error:"; printf '%s' "$CALL" | jq '.error'
elif [ "$(printf '%s' "$CALL" | jq '.result.isError == true')" = "true" ]; then
  echo "isError: true"
  printf '%s' "$CALL" | jq -r '[.result.content[]? | select(.type == "text") | .text] | join("\n")'
  printf '%s' "$CALL" | jq '.result._meta // empty'
else
  echo "isError: false (the result was returned)"
  printf '%s' "$CALL" | jq -r '[.result.content[]? | select(.type == "text") | .text] | join("\n") | .[0:300]'
  echo "..."
fi

On GitHub, open infra/call-tool.sh or infra/call-tool.ps1.

1

Call an allowed tool

# Make the test script executable, once
chmod +x infra/call-tool.sh &&
  echo "๐Ÿ“„ infra/call-tool.sh is executable"

# Ask the docs search tool a harmless question: the hook allows the call and the result
echo "๐Ÿ”ง Allowed tool call:"
./infra/call-tool.sh learn_microsoft_docs_search '{"query":"What is Azure Functions Flex Consumption?"}' "$MCP_SERVER"
2

Call a blocked tool

# Call the code sample tool, which matches the BLOCKED_TOOLS pattern *code_sample*: the hook denies it before it runs
echo "๐Ÿ”ง Blocked tool call:"
./infra/call-tool.sh learn_microsoft_code_sample_search '{"query":"azure functions python http trigger"}' "$MCP_SERVER"
3

Send an email address to a tool

# Put an email address in the arguments of an allowed tool: the hook denies the call before it runs
echo "๐Ÿ”ง Tool call with an email address:"
./infra/call-tool.sh learn_microsoft_docs_search '{"query":"Send the report to megan.bowen@contoso.com"}' "$MCP_SERVER"
4

Get a result that contains a secret

The Azurite storage emulator documents a well-known development account key, so a search for its connection string returns text that looks like a storage account key. The tool runs, and the hook withholds its result. On the Portal track, the policy has only Before tool call, so the result comes back.

# Search for a connection string with an account key: the hook allows the call, then withholds the result
echo "๐Ÿ”ง Tool call whose result contains a key:"
./infra/call-tool.sh learn_microsoft_docs_search '{"query":"Azurite default connection string AccountKey"}' "$MCP_SERVER"
Checkpoint

The harmless search returns results, the code sample tool and the email address are blocked before execution, and the connection string search is blocked after execution. Search results can change; if the last call returns results, they don't contain a key.

Understand verdicts and failures

The gateway answers a denied call the way MCP reports a failed tool: HTTP 200, with isError: true in the JSON-RPC result. Agents read it as a tool error, not a transport error.

What happensBefore tool callAfter tool call
The service answers allowThe tool runsThe caller gets the result
The service answers deny"Tool call blocked by a policy before execution". The tool doesn't run"Tool result blocked by a policy after execution". The tool already ran
The service fails: it's stopped, answers 401 or another error, or takes more than about 30 secondsfailClosed: the same as a deny. failOpen: the tool runsfailClosed: the same as a deny. failOpen: the caller gets the result

The gateway doesn't pass the reason to the caller, and with failClosed a failure looks exactly like a deny. Read the reason in the decision log, by the gateway's request_id, which is the same for both hooks of one call.

Caution

A deny after the call withholds the result, but it can't undo what the tool did. For tools that write, send, or delete, decide before the call, and build agents that don't retry a call whose result was withheld.

Agent hooks complement the gateway's built-in tool controls:

You needUseLab
Hide or block tools by name, the same way for every callerTool allow and block listsLab 05
Microsoft Defender and Microsoft Purview verdicts on prompt injection and sensitive data, for delegated user callsAgent 365 tool threat protectionLab 19
Your own rules on tool arguments and results, such as business limits, data that must not leave, or a custom detectorAgent hooksThis lab

Verify

1

Read the decision log

The function writes one line for each verdict to Application Insights, which stores it in Log Analytics. Lines arrive two to five minutes after the calls.

# Read the decision service's verdicts of the last hour: tool, decision, reason, request ID, caller, and header
echo "๐Ÿ“Š Decisions of the last hour:"
az monitor log-analytics query -w "$HOOK_LOG_WORKSPACE_ID" -o tsv --analytics-query \
  "AppTraces | where TimeGenerated > ago(1h) and Message startswith 'agent-hook' | order by TimeGenerated asc | project Message"

caller is the object ID of the gateway's managed identity, which App Service Authentication validated, and policy is the header that the policy adds. The portal track has no post_tool_call lines.

2

See the policy fail closed

Stop the decision service and call the harmless search again. The gateway can't get a verdict, so failClosed blocks the call. Then start the service again.

# Stop the decision service, so that the gateway can't get a verdict, and give the stop half a minute to apply
az functionapp stop -g "$HOOK_RG" -n "$HOOK_APP" &&
  echo "โณ $HOOK_APP is stopping" && sleep 30

# Call the harmless search again: with failClosed, the gateway blocks it
echo "๐Ÿ”ง Allowed tool call while the hook is down:"
./infra/call-tool.sh learn_microsoft_docs_search '{"query":"What is Azure Functions Flex Consumption?"}' "$MCP_SERVER"

# Start the decision service again
az functionapp start -g "$HOOK_RG" -n "$HOOK_APP" &&
  echo "๐Ÿš€ $HOOK_APP is running again"
Checkpoint

The decision log has an allow or a deny with a reason for each call, and the harmless search is blocked while the decision service is stopped. The log has no line for that call, because the function never ran.

Go further

  • Fail open for low-risk servers. Set mode to failOpen so that tool calls continue when the service is down, or override it for one point, such as "postToolCall": {"mode": "failOpen"}. On the Bicep + azd track, run azd env set HOOK_MODE failOpen and azd provision. On the Terraform track, run terraform plan -var hook_mode=failOpen -out tfplan and terraform apply tfplan in the terraform folder. Then repeat the stop test: the search returns results, and so does the code sample search that the service blocks. Fail open lets every call through while the service is down.
  • Change the rules without a deployment. The blocked tool patterns are an app setting: az functionapp config appsettings set -g "$HOOK_RG" -n "$HOOK_APP" --settings "BLOCKED_TOOLS=*code_sample*,*fetch*".
  • Use a key instead of an identity. The product's pre-tool call hook guide uses a function key in an x-functions-key header, with API key authentication. The policy stores the key, and the portal asks for it again whenever the server's policies change. A managed identity keeps secrets out of the policy.
  • Use another identity. Set managedIdentity.clientId to the client ID of a user-assigned identity on the gateway, and allow that identity's object ID in App Service Authentication.
  • Call your own rules engine. The service can call anything that decides quickly: a ticket system that checks for an approved change, a data loss prevention API, or a model that classifies the arguments.

Clean up

Choose your track
1

Delete the policy

In the AI Gateway portal, select Policies. On the Before tool calls row of type Agent hooks, select More actions (โ‹ฏ) โ€บ Delete. In Delete this policy?, select Delete. Tool calls on the server no longer wait for the hook.

2

Delete the decision service

The Azure CLI steps of Deploy the decision service created a resource group and an app registration. Delete them with the Azure CLI track's last three commands below.

Keep the gateway and the learn MCP server 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.