Your agent teams want tools: documentation search, ticketing, internal APIs. If every agent connects to every tool server directly, you end up with credentials in many places and no single point of control. In this lab the platform team publishes one governed MCP endpoint on the gateway, starting with the public Microsoft Learn MCP server, so agents get tools through the same front door they already use for models.
Before you begin
One-time setupThe Setup guide tasks that this lab uses. Mark each one done once, and the labs stop listing it.
- Choose where to run commandsEvery track except the portal
- Sign in to AzureOn your own machine. Cloud Shell is already signed in.
- Install the
aigatewayextensionThe Azure CLI tracks and the Verify steps - Clone the labs repoThe Bicep + azd and Terraform tracks, the notebooks, and the code samples
You've done the one-time setup that this lab uses.
On the Bicep + azd and Terraform tracks, azd up or terraform apply creates its own gateway, the learn
MCP server, and a key, so you can skip this section. You need only the one-time setup above.
- Complete Provision your AI Gateway.
- A runtime API key, for example
app-first-callfrom lab 02. If you don't have one yet, create it in the portal under AccessAPI keys, or, after you set the variables below, runaz aigateway api-key create -g "$RG" --gateway-name "$GATEWAY" -n app-first-calland read its value withaz aigateway api-key list-secrets -g "$RG" --gateway-name "$GATEWAY" -n app-first-call --query primaryKey -o tsv. - For the Code track: Python 3.10 or later and, optionally, VS Code.
- Permission to change the gateway, for example Contributor on the resource group.
- Run the scripts and samples from the lab's folder,
~/aigateway/labs/04-federate-mcp-tools.
Set these variables once. Every track and the Verify section reuse them.
# Name your gateway and its resource group
export RG="<resource-group>"
export GATEWAY="<gateway>"
echo "📝 Gateway $GATEWAY in $RG"
# Read the gateway's runtime URL, which MCP clients call
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 you created in Access › API keys. Don't commit it 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)"# Name your gateway and its resource group
$RG = "<resource-group>"
$GATEWAY = "<gateway>"
Write-Host "📝 Gateway $GATEWAY in $RG"
# Read the gateway's runtime URL, which MCP clients call
$env:AI_GATEWAY_URL = "https://$(az aigateway show -g $RG -n $GATEWAY --query properties.frontend.defaultHostname -o tsv)"
Write-Host "🌐 Runtime URL: $env:AI_GATEWAY_URL"
# Paste the runtime key you created in Access › API keys. Don't commit it or write it to a file.
$env:AI_GATEWAY_API_KEY = Read-Host "AI Gateway API key" -MaskInput
Write-Host "🔑 Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"How it works
An MCP server in AI Gateway is a federation point. You give it one or more backends, and the gateway
publishes all their tools at one Streamable HTTP endpoint:
<gateway-url>/default/toolservers/<server-name>/mcp.
| Backend type | What you provide | What clients see |
|---|---|---|
| MCP server (remote) | The Endpoint URL of a server that speaks Streamable HTTP | The server's tools |
| OpenAPI specification | A JSON or YAML OpenAPI document (upload, URL, or inline) | Selected operations as tools. The operation summary or description becomes the tool description. |
| From Azure | An existing API or MCP server in Azure: an API Management API, an Azure Functions MCP tool trigger, a Logic Apps or API Center MCP server, a Container Apps session pool, or an MCP server hosted in a Connector Namespace that wraps SaaS connectors like Microsoft 365, SharePoint, GitHub, or Salesforce | The source's tools |
Connector tools come from an Azure Connector Namespace. Create the MCP server there and authorize its connections in Azure, then choose Import from Azure on MCP servers, or Add backendFrom Azure in an MCP server, and select it, as in the product's Discover and import Azure-hosted MCP servers walkthrough. The gateway references the source without owning it, so removing the backend or the gateway leaves the namespace and its connections in place.
Each backend can have a namespace. The gateway prefixes that backend's tools with it, as in
learn_microsoft_docs_search, so two backends can expose tools with the same name without conflict.
The gateway authenticates clients. In this lab they send a runtime key as Authorization: Bearer <key>.
It authenticates to each backend separately, with None, API Key (one or more header names and
values), OAuth 2.0 (a Single shared application, or On behalf of each caller with their Microsoft
Entra permissions), or Managed identity. Backend credentials are stored securely, are never exposed to
clients, and appear under Connections.
Registering a backend doesn't mean that AI Gateway translates every backend protocol into MCP. Pick the backend type that matches what the backend actually serves.
Register the Learn MCP server
Pick one track. Each track creates the same MCP server: learn, with one backend, the public Microsoft
Learn MCP server at https://learn.microsoft.com/api/mcp, under the namespace learn. That server needs no
credentials, so the backend authentication is None.
Start the workflow
Open the AI Gateway portal and select your gateway from the gateway switcher. Select MCP serversAdd MCP server. The full-page Create MCP server workflow has three steps: Basic info, Backends, and Tools.
Describe the server
On Basic info, set:
| Field | Value |
|---|---|
| Name | learn (part of the endpoint URL; it can't be changed after creation) |
| Display name | Microsoft Learn |
| Description | Search and fetch official Microsoft documentation and code samples. |
| Supported MCP versions | 2025-06-18 only. The wizard preselects 2026-07-28, 2025-11-25, 2025-06-18, and 2025-03-26, so clear the others. You must keep at least one version that every backend supports. |
Agents and people read the description to decide when to use the server, so keep it specific. The display name must be unique among the MCP servers of the gateway. You learn more about the versions in Choose supported MCP versions. Select Next.
Add the Learn backend
On Backends, select Add backendMCP server. In Add MCP backend, set:
| Field | Value |
|---|---|
| Endpoint URL | https://learn.microsoft.com/api/mcp |
| Authentication | None |
| Namespace prefix | learn |
Select Add. The backend appears in the table with its URL, Type, Authentication, Namespace, and Required columns. Leave Required on.
Publish all tools
Select Next. The portal saves the server with Allow all tools, which publishes every current and future tool from its backends. You narrow this down in Control which tools agents can call. If the Tools step opens, keep Allow all tools and select Create.
Copy the endpoint
Open Microsoft Learn from MCP servers. Under Basics, check the Description: if it reads
"Federated MCP server providing tools from: learn", select Edit, enter the description again, and select
Save. Under Endpoints, copy the Endpoint URL. It ends in /default/toolservers/learn/mcp.
MCP servers lists Microsoft Learn with the namespace learn, and its details page shows an
Endpoint URL, Supported MCP versions 2025-06-18, and one backend with the namespace learn.
Create the registration
az aigateway mcp create registers the MCP server. --endpoints takes the backends as a JSON array.
# Register the learn MCP server, with the public Learn MCP server as its one backend, under the namespace learn
az aigateway mcp create -g "$RG" --gateway-name "$GATEWAY" -n learn \
--display-name "Microsoft Learn" \
--description "Search and fetch official Microsoft documentation and code samples." \
--endpoints '[{"kind": "mcp", "namespace": "learn", "required": true,
"mcp": {"url": "https://learn.microsoft.com/api/mcp", "transport": "streamableHttp"}}]' \
--query "{name:name,mcpEndpoint:properties.gatewayEndpoints[0].url}" &&
echo "🔌 MCP server learn is ready"# Write the backends to a file, so that PowerShell passes the JSON to az unchanged
ConvertTo-Json -Depth 10 -Compress -InputObject @(
@{ kind = 'mcp'; namespace = 'learn'; required = $true
mcp = @{ transport = 'streamableHttp'; url = 'https://learn.microsoft.com/api/mcp' } }
) | Set-Content -Path endpoints.json
# Register the learn MCP server, with the public Learn MCP server as its one backend, under the namespace learn
az aigateway mcp create -g $RG --gateway-name $GATEWAY -n learn `
--display-name "Microsoft Learn" `
--description "Search and fetch official Microsoft documentation and code samples." `
--endpoints "@endpoints.json" `
--query "{name:name,mcpEndpoint:properties.gatewayEndpoints[0].url}"
if ($?) { Write-Host "🔌 MCP server learn is ready" }
Remove-Item endpoints.json-n learn is the MCP server name. mcp create fails with This MCP registration already exists; use mcp update.
if the name is taken, so change an existing registration with az aigateway mcp update or the mcp source
commands, as in the next section.
Confirm the registration
The commands are the same in Bash and PowerShell.
# List the MCP servers on your gateway
echo "🔌 MCP servers on your gateway:"
az aigateway mcp list -g "$RG" --gateway-name "$GATEWAY" -o table
# Show the backends and the endpoint URL of learn
echo "🔌 Backends and endpoint of learn:"
az aigateway mcp show -g "$RG" --gateway-name "$GATEWAY" -n learn --query "properties.{endpoints:endpoints,url:gatewayEndpoints[0].url}"The table shows learn with Microsoft Learn in the DisplayName column, failClosed in the
FailureMode column, and 1 in the Sources column. The second command returns one endpoint with
"namespace": "learn", "kind": "mcp", and "mode": "failClosed", and a url that ends in
/default/toolservers/learn/mcp.
The CLI takes a backend's settings as required and mcp.url, and stores them with the property names of the
generally available management API (2026-11-01), which the Bicep and Terraform tracks also use:
"required": true becomes "mode": "failClosed" ("failOpen" for an optional backend), and mcp.url
becomes mcp.endpoint.url. mcp show prints the stored names.
What you need: only the one-time setup from Before you begin. This track doesn't use your gateway from lab 01:
azd up creates a new one, so it works on its own.
Review the templates
infra/main.bicep creates the resource group rg-<environment name> and calls lab 01's
gateway.bicep for a gateway with no model. Then it calls
infra/tool-server.bicep for the learn MCP server and the app-first-call key. azd fills the secondNamespace
and supportedVersions parameters from the environment values MCP_SECOND_NAMESPACE and MCP_SUPPORTED_VERSIONS,
which the next sections set. Empty, they register one backend and keep the legacy MCP versions.
// Lab 04 with azd: "azd up" creates the resource group rg-<environment name>, a gateway with lab 01's template, then
// the learn MCP server that federates the public Microsoft Learn MCP server, and the runtime API key app-first-call.
// The runtime API key is never an output.
targetScope = 'subscription'
@description('azd environment name. The resource group is rg-<environmentName>.')
@minLength(1)
@maxLength(60)
param environmentName string
@description('Region for every resource. Pick one where AI Gateway is available. List them with az provider show --namespace Microsoft.ApiManagement (Setup guide, Find the available regions).')
@metadata({ azd: { type: 'location' } })
param location string
@description('Namespace for a second, optional Learn backend, such as docs. Empty registers one backend. azd reads it from MCP_SECOND_NAMESPACE.')
param secondNamespace string = ''
@description('Comma-separated MCP protocol versions, such as 2025-06-18. Empty keeps the current list, or the legacy defaults on a new server. azd reads it from MCP_SUPPORTED_VERSIONS.')
param supportedVersions string = ''
var suffix = take(uniqueString(subscription().id, environmentName, location), 6)
var tags = { 'azd-env-name': environmentName }
resource rg 'Microsoft.Resources/resourceGroups@2024-03-01' = {
name: 'rg-${environmentName}'
location: location
tags: tags
}
// Lab 01's template: the gateway, with no model.
module gateway '../../01-provision-gateway/infra/gateway.bicep' = {
name: 'aigw-gateway'
scope: rg
params: {
gatewayName: 'aigw-${suffix}'
location: location
tags: tags
}
}
module toolServer 'tool-server.bicep' = {
name: 'aigw-tool-server'
scope: rg
params: {
gatewayName: gateway.outputs.gatewayName
serverName: 'learn'
namespace: 'learn'
secondNamespace: secondNamespace
supportedVersions: supportedVersions
apiKeyName: 'app-first-call'
}
}
output AZURE_RESOURCE_GROUP string = rg.name
output AI_GATEWAY_NAME string = gateway.outputs.gatewayName
output AI_GATEWAY_ID string = gateway.outputs.gatewayId
output AI_GATEWAY_URL string = gateway.outputs.gatewayUrl
output MCP_ENDPOINT string = toolServer.outputs.mcpEndpointinfra/tool-server.bicep references the gateway and its default workspace, then declares one toolServers
resource and, when apiKeyName is set, the runtime key. The key's value is never an output. You can also deploy
the module on its own to a gateway you already have, with az deployment group create, as lab 24 does.
// Registers the public Microsoft Learn MCP server as a federated MCP server in an existing AI Gateway. main.bicep calls
// it after lab 01's gateway template, and you can also deploy it on its own to a gateway you already have.
// Clients call one governed endpoint, <gateway-url>/default/toolservers/<serverName>/mcp,
// and the gateway publishes each backend's tools with a namespace prefix (<namespace>_<tool>).
// Set secondNamespace to add the same public server as a second, optional backend and see namespacing at work.
// A required backend has mode failClosed: tool discovery fails if it fails. An optional one has mode failOpen: the
// gateway skips it. displayName must be unique among the MCP servers of the gateway.
// Set supportedVersions to pin the MCP protocol versions that clients can negotiate.
// Set apiKeyName to also create a runtime API key for your clients. Its value is never an output.
@description('Name of the existing AI Gateway (Microsoft.ApiManagement/aigateways).')
param gatewayName string
@description('MCP server name. It becomes part of the endpoint URL and cannot be changed after creation.')
param serverName string = 'learn'
@description('Display name shown in the portal catalog and details page.')
param displayName string = 'Microsoft Learn'
@description('Description that helps people and agents understand what the tools do.')
param serverDescription string = 'Search and fetch official Microsoft documentation and code samples.'
@description('Namespace for the first backend. Its tools are published as <namespace>_<tool>.')
param namespace string = 'learn'
@description('URL of the first backend MCP server (Streamable HTTP).')
param mcpUrl string = 'https://learn.microsoft.com/api/mcp'
@description('Optional namespace for a second backend. Leave empty to register one backend only.')
param secondNamespace string = ''
@description('URL of the optional second backend MCP server (Streamable HTTP).')
param secondMcpUrl string = 'https://learn.microsoft.com/api/mcp'
@description('Comma-separated MCP protocol versions the server supports, for example 2025-06-18 or 2026-07-28,2025-06-18. Every MCP backend must support every version you list. Leave empty to keep the server\'s current list, or the legacy defaults on a new server: 2025-06-18, 2025-03-26, and 2024-11-05.')
param supportedVersions string = ''
@description('Optional runtime API key to create for the MCP clients, for example app-first-call. Leave empty to create none.')
param apiKeyName string = ''
var versions = empty(supportedVersions) ? {} : { versions: split(replace(supportedVersions, ' ', ''), ',') }
var primaryEndpoint = {
namespace: namespace
kind: 'mcp'
mode: 'failClosed'
mcp: {
endpoint: {
url: mcpUrl
}
transport: 'streamableHttp'
}
}
var secondEndpoint = {
namespace: secondNamespace
kind: 'mcp'
mode: 'failOpen'
mcp: {
endpoint: {
url: secondMcpUrl
}
transport: 'streamableHttp'
}
}
#disable-next-line BCP081
resource gateway 'Microsoft.ApiManagement/aigateways@2026-11-01' existing = {
name: gatewayName
}
#disable-next-line BCP081
resource workspace 'Microsoft.ApiManagement/aigateways/workspaces@2026-11-01' existing = {
parent: gateway
name: 'default'
}
#disable-next-line BCP081
resource toolServer 'Microsoft.ApiManagement/aigateways/workspaces/toolServers@2026-11-01' = {
parent: workspace
name: serverName
properties: union({
displayName: displayName
description: serverDescription
toolServerType: 'mcp'
endpoints: empty(secondNamespace) ? [ primaryEndpoint ] : [ primaryEndpoint, secondEndpoint ]
}, versions)
}
#disable-next-line BCP081
resource apiKey 'Microsoft.ApiManagement/aigateways/apiKeys@2026-11-01' = if (!empty(apiKeyName)) {
parent: gateway
name: apiKeyName
properties: {
displayName: apiKeyName
}
}
output toolServerId string = toolServer.id
output supportedVersions array = toolServer.properties.?versions ?? []
output mcpEndpoint string = 'https://${gateway.properties.frontend.defaultHostname}/default/toolservers/${serverName}/mcp'A Bicep deployment sends a PUT, which replaces the whole MCP server, including backends and tool rules
that you added in the portal. Keep the template as the only source of truth for this server, and change it with
azd provision.
Deploy with azd up
Move into the lab's folder, create an azd environment named aigw-lab04 in your current subscription, then provision
everything. It takes about two minutes.
# Move into the lab's folder, which holds the azd project
cd ~/aigateway/labs/04-federate-mcp-tools &&
echo "📂 Lab folder: $(pwd)"
# Create an azd environment in your current subscription, so that azd doesn't prompt you
azd env new aigw-lab04 --location eastus2 --subscription "$(az account show --query id --output tsv)" &&
echo "📝 azd environment aigw-lab04 deploys to eastus2"
# Provision the gateway, the learn MCP server, and the app-first-call key
azd up &&
echo "🚀 Gateway deployed: $(azd env get-value AI_GATEWAY_URL)"# Move into the lab's folder, which holds the azd project
Set-Location ~/aigateway/labs/04-federate-mcp-tools
if ($?) { Write-Host "📂 Lab folder: $(Get-Location)" }
# Create an azd environment in your current subscription, so that azd doesn't prompt you
azd env new aigw-lab04 --location eastus2 --subscription (az account show --query id --output tsv)
if ($?) { Write-Host "📝 azd environment aigw-lab04 deploys to eastus2" }
# Provision the gateway, the learn MCP server, and the app-first-call key
azd up
if ($?) { Write-Host "🚀 Gateway deployed: $(azd env get-value AI_GATEWAY_URL)" }For another region, use its name from Find the available regions.
Read the outputs and the key
Set the variables that the next sections and Verify use from azd's environment values, and read the key from the gateway, so that it never shows on screen.
# Read the template's outputs: the resource group, the gateway, and its runtime URL
export RG="$(azd env get-value AZURE_RESOURCE_GROUP)"
export GATEWAY="$(azd env get-value AI_GATEWAY_NAME)"
export AI_GATEWAY_URL="$(azd env get-value AI_GATEWAY_URL)"
echo "📝 Gateway $GATEWAY in $RG"
echo "🌐 Runtime URL: $AI_GATEWAY_URL"
# Read the gateway's runtime key from the gateway, so that it never lands in a file or a deployment log
export AI_GATEWAY_API_KEY="$(az aigateway api-key list-secrets --ids "$(azd env get-value AI_GATEWAY_ID)/apiKeys/app-first-call" \
--query primaryKey --output tsv)"
echo "🔑 Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"
# Print the endpoint of the learn MCP server, which MCP clients call
echo "🌐 MCP endpoint: $(azd env get-value MCP_ENDPOINT)"# Read the template's outputs: the resource group, the gateway, its runtime URL, and its resource ID
$RG = azd env get-value AZURE_RESOURCE_GROUP
$GATEWAY = azd env get-value AI_GATEWAY_NAME
$env:AI_GATEWAY_URL = azd env get-value AI_GATEWAY_URL
$GATEWAY_ID = azd env get-value AI_GATEWAY_ID
Write-Host "📝 Gateway $GATEWAY in $RG"
Write-Host "🌐 Runtime URL: $env:AI_GATEWAY_URL"
# Read the gateway's runtime key from the gateway, so that it never lands in a file or a deployment log
$env:AI_GATEWAY_API_KEY = az aigateway api-key list-secrets --ids "$GATEWAY_ID/apiKeys/app-first-call" `
--query primaryKey --output tsv
Write-Host "🔑 Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"
# Print the endpoint of the learn MCP server, which MCP clients call
Write-Host "🌐 MCP endpoint: $(azd env get-value MCP_ENDPOINT)"azd up ended with SUCCESS, and the last line is 🌐 MCP endpoint: with a URL that ends in
/default/toolservers/learn/mcp. In the portal, MCP servers lists learn with one backend, learn.
What you need: only the one-time setup from Before you begin, plus Terraform 1.9 or later, as in
Deploy a lab with Terraform. This track doesn't use your gateway from
lab 01: terraform apply creates a new one, so it works on its own.
Review the configuration
terraform/main.tf creates the resource group rg-<environment_name> and calls lab 01's
gateway module for a gateway with no model:
# Lab 04 with Terraform: creates the resource group rg-<environment_name>, a gateway with lab 01's module, then the
# learn MCP server that federates the public Microsoft Learn MCP server, and the runtime API key app-first-call
# (tool-server.tf). The runtime API key is never an output.
data "azapi_client_config" "current" {}
locals {
suffix = substr(sha1("${data.azapi_client_config.current.subscription_id}/${var.environment_name}/${var.location}"), 0, 6)
tags = { "environment-name" = var.environment_name }
}
resource "azurerm_resource_group" "rg" {
name = "rg-${var.environment_name}"
location = var.location
tags = local.tags
}
# Lab 01's module: the gateway, with no model.
module "gateway" {
source = "../../01-provision-gateway/terraform/gateway"
gateway_name = "aigw-${local.suffix}"
resource_group_id = azurerm_resource_group.rg.id
location = var.location
tags = local.tags
}terraform/tool-server.tf registers the learn MCP server and creates the app-first-call key with the azapi
provider, which sends the AI Gateway API version, 2026-11-01, as is. The second_namespace and
supported_versions variables in terraform/variables.tf, which the next sections set, are empty by default: one
backend, and the legacy MCP versions.
# Registers the public Microsoft Learn MCP server as the federated MCP server learn. Clients call one governed
# endpoint, <gateway-url>/default/toolservers/learn/mcp, and the gateway publishes each backend's tools with a
# namespace prefix (<namespace>_<tool>). A required backend has mode failClosed: tool discovery fails if it fails.
# An optional one, such as the second_namespace backend, has mode failOpen: the gateway skips it.
locals {
learn_url = "https://learn.microsoft.com/api/mcp"
primary_endpoint = {
namespace = "learn"
kind = "mcp"
mode = "failClosed"
mcp = {
endpoint = { url = local.learn_url }
transport = "streamableHttp"
}
}
second_endpoint = {
namespace = var.second_namespace
kind = "mcp"
mode = "failOpen"
mcp = {
endpoint = { url = local.learn_url }
transport = "streamableHttp"
}
}
# An empty list keeps the server's current versions, or the legacy defaults on a new server.
versions = length(var.supported_versions) == 0 ? {} : { versions = var.supported_versions }
}
resource "azapi_resource" "tool_server" {
type = "Microsoft.ApiManagement/aigateways/workspaces/toolServers@2026-11-01"
name = "learn"
parent_id = "${module.gateway.gateway_id}/workspaces/default"
body = {
properties = merge({
displayName = "Microsoft Learn"
description = "Search and fetch official Microsoft documentation and code samples."
toolServerType = "mcp"
endpoints = var.second_namespace == "" ? [local.primary_endpoint] : [local.primary_endpoint, local.second_endpoint]
}, local.versions)
}
schema_validation_enabled = false
}
# A runtime API key for the MCP clients. Read its value with az aigateway api-key list-secrets.
resource "azapi_resource" "api_key" {
type = "Microsoft.ApiManagement/aigateways/apiKeys@2026-11-01"
name = "app-first-call"
parent_id = module.gateway.gateway_id
body = {
properties = {
displayName = "app-first-call"
}
}
schema_validation_enabled = false
}terraform apply sends a PUT, which replaces the whole MCP server, including backends and tool rules that you
added in the portal. Keep the configuration as the only source of truth for this server, and change it with
terraform apply.
Deploy with terraform apply
Move into the lab's Terraform folder, select your current subscription, then plan and apply the configuration. It takes about two minutes, most of it while the new gateway activates.
# Move into the lab's Terraform folder
cd ~/aigateway/labs/04-federate-mcp-tools/terraform &&
echo "📂 Terraform folder: $(pwd)"
# Deploy to the Azure CLI's current subscription
export ARM_SUBSCRIPTION_ID="$(az account show --query id --output tsv)" &&
echo "📍 Subscription: $ARM_SUBSCRIPTION_ID"
# Download the providers, then plan and apply the gateway, the learn MCP server, and the app-first-call key
terraform init &&
terraform plan -out tfplan &&
terraform apply tfplan &&
echo "🚀 Gateway $(terraform output -raw ai_gateway_name) is deployed"# Move into the lab's Terraform folder
Set-Location ~/aigateway/labs/04-federate-mcp-tools/terraform
if ($?) { Write-Host "📂 Terraform folder: $(Get-Location)" }
# Deploy to the Azure CLI's current subscription
$env:ARM_SUBSCRIPTION_ID = az account show --query id --output tsv
if ($?) { Write-Host "📍 Subscription: $env:ARM_SUBSCRIPTION_ID" }
# Download the providers, then plan and apply the gateway, the learn MCP server, and the app-first-call key
terraform init
if ($?) { terraform plan -out tfplan }
if ($?) { terraform apply tfplan }
if ($?) { Write-Host "🚀 Gateway $(terraform output -raw ai_gateway_name) is deployed" }The configuration deploys to eastus2. For another region, use its name from Find the available
regions: run export TF_VAR_location=<region> (PowerShell:
$env:TF_VAR_location = "<region>") before terraform plan.
Read the outputs and the key
Set the variables that the next sections and Verify use from the Terraform outputs. The outputs never contain the key value, so read it from the gateway straight into a variable, where it never shows on screen or lands in the Terraform state.
# Read the outputs: the resource group, the gateway, its runtime URL, and its resource ID
export RG="$(terraform output -raw azure_resource_group)"
export GATEWAY="$(terraform output -raw ai_gateway_name)"
export AI_GATEWAY_URL="$(terraform output -raw ai_gateway_url)"
export GATEWAY_ID="$(terraform output -raw ai_gateway_id)"
echo "📝 Gateway $GATEWAY in $RG"
echo "🌐 Runtime URL: $AI_GATEWAY_URL"
# Read the gateway's runtime key from the gateway, so that it never lands in a file or the Terraform state
export AI_GATEWAY_API_KEY="$(az aigateway api-key list-secrets --ids "$GATEWAY_ID/apiKeys/app-first-call" \
--query primaryKey --output tsv)"
echo "🔑 Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"
# Print the endpoint of the learn MCP server, which MCP clients call
echo "🌐 MCP endpoint: $(terraform output -raw mcp_endpoint)"
# Move back to the lab's folder, which holds the scripts and samples
cd .. && echo "📂 Lab folder: $(pwd)"# Read the outputs: the resource group, the gateway, its runtime URL, and its resource ID
$RG = terraform output -raw azure_resource_group
$GATEWAY = terraform output -raw ai_gateway_name
$env:AI_GATEWAY_URL = terraform output -raw ai_gateway_url
$GATEWAY_ID = terraform output -raw ai_gateway_id
Write-Host "📝 Gateway $GATEWAY in $RG"
Write-Host "🌐 Runtime URL: $env:AI_GATEWAY_URL"
# Read the gateway's runtime key from the gateway, so that it never lands in a file or the Terraform state
$env:AI_GATEWAY_API_KEY = az aigateway api-key list-secrets --ids "$GATEWAY_ID/apiKeys/app-first-call" `
--query primaryKey --output tsv
Write-Host "🔑 Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"
# Print the endpoint of the learn MCP server, which MCP clients call
Write-Host "🌐 MCP endpoint: $(terraform output -raw mcp_endpoint)"
# Move back to the lab's folder, which holds the scripts and samples
Set-Location ..
if ($?) { Write-Host "📂 Lab folder: $(Get-Location)" }terraform apply ended with Apply complete! Resources: 4 added, 0 changed, 0 destroyed., and the last line is
🌐 MCP endpoint: with a URL that ends in /default/toolservers/learn/mcp. In the portal, select the new gateway
in the gateway switcher: MCP servers lists learn with one backend, learn.
The next sections run from the lab's folder, with -chdir=terraform for the terraform commands.
Federate a second backend
Federation pays off when one endpoint combines several backends. To see it without extra credentials, add the
same public Learn server again under a second namespace, docs. Both backends expose a tool called
microsoft_docs_search, and the namespaces keep them apart. Mark the new backend as not required: if an
optional backend is unavailable, the gateway skips it instead of failing the whole MCP server.
Add the backend
On the learn details page, select Edit. Under Backends, select Add backendMCP server. In
Add MCP backend, set Endpoint URL to https://learn.microsoft.com/api/mcp, Authentication to None,
and Namespace prefix to docs, then select Add. In the backends table, turn Required off for the new row.
Select Save.
Add the source
az aigateway mcp source add appends one backend and changes only the list of backends. Other settings, such as
the description and policies, stay as they are.
# Add the Learn MCP server again as an optional backend, under the namespace docs, and list the backends
az aigateway mcp source add -g "$RG" --gateway-name "$GATEWAY" -n learn \
--namespace docs --kind mcp --required false \
--mcp '{"transport": "streamableHttp", "url": "https://learn.microsoft.com/api/mcp"}' \
--query "[].{namespace:namespace,mode:mode,url:mcp.endpoint.url}" -o table &&
echo "🔌 Backend docs is added to learn, as optional"# Write the backend's settings to a file, so that PowerShell passes the JSON to az unchanged
@{ transport = 'streamableHttp'; url = 'https://learn.microsoft.com/api/mcp' } |
ConvertTo-Json -Compress | Set-Content -Path mcp.json
# Add the Learn MCP server again as an optional backend, under the namespace docs, and list the backends
az aigateway mcp source add -g $RG --gateway-name $GATEWAY -n learn `
--namespace docs --kind mcp --required false --mcp "@mcp.json" `
--query "[].{namespace:namespace,mode:mode,url:mcp.endpoint.url}" -o table
if ($?) { Write-Host "🔌 Backend docs is added to learn, as optional" }
Remove-Item mcp.jsonThe table lists every backend of the server: learn with the Mode failClosed, and docs with failOpen,
which is how the server stores --required false. The command fails with "A source with namespace 'docs' already
exists on this MCP server registration." if you run it twice. For a backend that needs a key, pass the key with
--credentials.
Add the second namespace
When secondNamespace isn't empty, the template adds a second endpoint with mode: 'failOpen', the optional
backend. Set it in the azd
environment and provision again. Only the MCP server changes.
# Add the second namespace in the azd environment
azd env set MCP_SECOND_NAMESPACE docs &&
echo "📝 MCP_SECOND_NAMESPACE is docs"
# Deploy the template again: it adds the optional docs backend to the learn MCP server
azd provision &&
echo "🔌 MCP server learn now has the optional docs backend"# Add the second namespace in the azd environment
azd env set MCP_SECOND_NAMESPACE docs
if ($?) { Write-Host "📝 MCP_SECOND_NAMESPACE is docs" }
# Deploy the template again: it adds the optional docs backend to the learn MCP server
azd provision
if ($?) { Write-Host "🔌 MCP server learn now has the optional docs backend" }Add the second namespace
When second_namespace isn't empty, the configuration adds a second endpoint with mode = "failOpen", the
optional backend. Pass it to terraform plan and apply the plan. Only the MCP server changes.
# Plan the second namespace, docs
terraform -chdir=terraform plan -var second_namespace=docs -out tfplan &&
echo "📝 The plan updates only the learn MCP server"
# Apply the plan: it adds the optional docs backend to the learn MCP server
terraform -chdir=terraform apply tfplan &&
echo "🔌 MCP server learn now has the optional docs backend"# Plan the second namespace, docs
terraform -chdir=terraform plan -var second_namespace=docs -out tfplan
if ($?) { Write-Host "📝 The plan updates only the learn MCP server" }
# Apply the plan: it adds the optional docs backend to the learn MCP server
terraform -chdir=terraform apply tfplan
if ($?) { Write-Host "🔌 MCP server learn now has the optional docs backend" }The plan ends with Plan: 0 to add, 1 to change, 0 to destroy., for azapi_resource.tool_server. Keep passing
-var second_namespace=docs to every later terraform plan: without it, the plan removes the docs backend.
In production, the second backend is a different service. For an internal REST API, choose OpenAPI specification and point it at its OpenAPI document. For an API that needs a key, set Authentication to API Key with the Header name and Value the backend expects. Clients never see that key.
The learn server has two backends: learn (required) and docs (optional).
Choose supported MCP versions
MCP is versioned by date. A client opens a connection by naming the protocol version it speaks, and the server answers with the version both sides will use. AI Gateway negotiates one version for the whole MCP server, so that version must work with every backend behind it.
| Supported MCP versions | What clients get |
|---|---|
| Not configured | The legacy defaults: 2025-06-18, 2025-03-26, and 2024-11-05. The details page lists them, and Edit shows Not configured. Servers that you create with the CLI, Bicep, or Terraform without a list get them. |
| A list that you choose | Version restrictions. Clients negotiate only a version in the list, and a request whose MCP-Protocol-Version header names any other version is rejected with 400. |
You can choose 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, and 2024-11-05. Version
2026-07-28 is the stateless revision of the specification: it replaces the initialize handshake and
sessions with a server/discover request, and every request carries MCP-Protocol-Version, Mcp-Method, and
Mcp-Name headers plus metadata in params._meta. Select it only when every backend supports it, and use an
MCP SDK that implements it rather than hand-written requests.
In this lab, pin the server to 2025-06-18. At the time of writing, that's the version the Microsoft Learn MCP
server negotiates, so both backends, learn and docs, support it.
Pin the version
- On the
learndetails page, under MCP configuration, find Supported MCP versions. If you created the server in the portal with2025-06-18, it's already pinned: go to Check the negotiated version. If it lists the legacy defaults, continue. - Select Edit. Under Basic info, open Supported MCP versions and keep only
2025-06-18selected. - Under Backends, the portal asks you to recheck the backends: "Backend compatibility must be rechecked. Supported MCP versions changed. Edit and save each external MCP backend before saving this server." For each backend row, open its actions menu, select Edit, then Save in Edit MCP backend. The portal checks which versions the backend supports before it saves the row, and the message goes away after the last row.
- Select Save.
If a backend doesn't support a selected version, Edit MCP backend shows "Backend isn't compatible with all configured MCP versions." and lists the versions the backend reports. Return to Basic info and change the list, or update the backend.
Set the versions
az aigateway mcp update --versions takes a space-separated list and replaces the server's list. The backends,
tool rules, and policies stay as they are.
# Pin learn to MCP version 2025-06-18, and print the list that the server keeps
az aigateway mcp update -g "$RG" --gateway-name "$GATEWAY" -n learn --versions 2025-06-18 \
--query properties.versions &&
echo "📝 MCP server learn supports only MCP version 2025-06-18"# Pin learn to MCP version 2025-06-18, and print the list that the server keeps
az aigateway mcp update -g $RG --gateway-name $GATEWAY -n learn --versions 2025-06-18 `
--query properties.versions
if ($?) { Write-Host "📝 MCP server learn supports only MCP version 2025-06-18" }Unlike the portal, the CLI doesn't ask the backends which versions they support. If you list a version that a
backend can't speak, the update succeeds and clients that negotiate that version fail. A version that the gateway
doesn't know fails with Unsupported MCP protocol version. See
Troubleshooting.
Pin the versions
The supportedVersions parameter takes a comma-separated list, such as 2025-06-18 or 2026-07-28,2025-06-18,
and azd fills it from MCP_SUPPORTED_VERSIONS. Set it and provision again. The azd environment keeps
MCP_SECOND_NAMESPACE, so both backends stay.
# Pin learn to MCP version 2025-06-18 in the azd environment
azd env set MCP_SUPPORTED_VERSIONS 2025-06-18 &&
echo "📝 MCP_SUPPORTED_VERSIONS is 2025-06-18"
# Deploy the template again: it sets the supported versions of the learn MCP server
azd provision &&
echo "🚀 MCP server learn is deployed with MCP version 2025-06-18"
# Show the versions that learn supports now
echo "📝 Supported MCP versions of learn:"
az aigateway mcp show -g "$RG" --gateway-name "$GATEWAY" -n learn --query properties.versions# Pin learn to MCP version 2025-06-18 in the azd environment
azd env set MCP_SUPPORTED_VERSIONS 2025-06-18
if ($?) { Write-Host "📝 MCP_SUPPORTED_VERSIONS is 2025-06-18" }
# Deploy the template again: it sets the supported versions of the learn MCP server
azd provision
if ($?) { Write-Host "🚀 MCP server learn is deployed with MCP version 2025-06-18" }
# Show the versions that learn supports now
Write-Host "📝 Supported MCP versions of learn:"
az aigateway mcp show -g $RG --gateway-name $GATEWAY -n learn --query properties.versionsThe last command prints a list that holds only 2025-06-18. An empty value doesn't clear a list that the server already has, so
to change the versions later, set another list.
Pin the versions
The supported_versions variable takes a list, such as ["2025-06-18"] or ["2026-07-28", "2025-06-18"]. Pass it
to terraform plan together with second_namespace, so that both backends stay, and apply the plan.
# Plan MCP version 2025-06-18 for learn, and keep the docs backend
terraform -chdir=terraform plan -var second_namespace=docs -var 'supported_versions=["2025-06-18"]' -out tfplan &&
echo "📝 The plan updates only the learn MCP server"
# Apply the plan: it sets the supported versions of the learn MCP server
terraform -chdir=terraform apply tfplan &&
echo "🚀 MCP server learn is deployed with MCP version 2025-06-18"
# Show the versions that learn supports now
echo "📝 Supported MCP versions of learn:"
az aigateway mcp show -g "$RG" --gateway-name "$GATEWAY" -n learn --query properties.versions# Plan MCP version 2025-06-18 for learn, and keep the docs backend
terraform -chdir=terraform plan -var second_namespace=docs -var 'supported_versions=["2025-06-18"]' -out tfplan
if ($?) { Write-Host "📝 The plan updates only the learn MCP server" }
# Apply the plan: it sets the supported versions of the learn MCP server
terraform -chdir=terraform apply tfplan
if ($?) { Write-Host "🚀 MCP server learn is deployed with MCP version 2025-06-18" }
# Show the versions that learn supports now
Write-Host "📝 Supported MCP versions of learn:"
az aigateway mcp show -g $RG --gateway-name $GATEWAY -n learn --query properties.versionsThe last command prints a list that holds only 2025-06-18. To change the versions later, pass another list.
Check the negotiated version
A new list takes about 15 seconds to reach the runtime. Until then, the gateway still answers with the previous list. Ask for an older version. The gateway answers with the version it will use:
# Send an initialize request that asks for 2025-03-26, with your runtime key as a bearer token
echo "🔌 initialize response from learn:"
curl -sS "${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":"initialize","params":{"protocolVersion":"2025-03-26",
"capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'# Build an initialize request that asks for 2025-03-26, with your runtime key as a bearer token
$mcp = "$($env:AI_GATEWAY_URL.TrimEnd('/'))/default/toolservers/learn/mcp"
$headers = @{ Authorization = "Bearer $env:AI_GATEWAY_API_KEY"; Accept = 'application/json, text/event-stream' }
$body = '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26",
"capabilities":{},"clientInfo":{"name":"pwsh","version":"1.0"}}}'
# Send it, and print the response, with the version that the gateway chose
Write-Host "🔌 initialize response from learn:"
(Invoke-WebRequest -Method Post -Uri $mcp -Headers $headers -ContentType 'application/json' -Body $body).ContentThe result includes "protocolVersion":"2025-06-18". Now send a request that names a version outside the list:
# Send tools/list with MCP version 2026-07-28, which isn't in the list
echo "🚦 Expect 400 Bad Request for MCP version 2026-07-28:"
curl -sS -w "\n🚦 HTTP %{http_code}\n" "${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" -H "MCP-Protocol-Version: 2026-07-28" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'# Send tools/list with MCP version 2026-07-28, which isn't in the list
Write-Host "🚦 Expect 400 Bad Request for MCP version 2026-07-28:"
$r = Invoke-WebRequest -Method Post -Uri $mcp -SkipHttpErrorCheck -ContentType 'application/json' `
-Headers ($headers + @{ 'MCP-Protocol-Version' = '2026-07-28' }) -Body '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
if ($?) { Write-Host "🚦 HTTP $($r.StatusCode) $($r.Content)" }The gateway rejects it with 🚦 HTTP 400 and Unsupported MCP-Protocol-Version before any backend is called.
Supported MCP versions shows 2025-06-18 on the details page and in Catalog, an initialize request
for 2025-03-26 returns 2025-06-18, and a 2026-07-28 request is rejected with 400.
Connect a client
Any MCP-compatible client or agent framework can use the endpoint. Store the runtime key in the client's secret store, never in a file that you commit.
Continue in code
On the learn details page, select Test in catalog, then Continue in code. The panel shows the
Endpoint URL and offers Quick install for VS Code and Cursor (install through a deep link), and
Manual configuration for mcp.json (any MCP-aware client), Claude Desktop, Microsoft Foundry, and
Microsoft 365 Agents. The mcp.json sample sends Authorization: Bearer <your-api-key>. Replace the
placeholder with your runtime key in the client's secret prompt, not in a committed file.
Add the server to VS Code
Create .vscode/mcp.json in a project, paste this configuration, and replace <gateway> with your gateway
name. The inputs entry makes VS Code prompt for the key instead of storing it in the file.
{
"inputs": [
{
"type": "promptString",
"id": "aigw-key",
"description": "AI Gateway runtime key (Access > API keys)",
"password": true
}
],
"servers": {
"ai-gateway-learn": {
"type": "http",
"url": "<gateway-url>/default/toolservers/learn/mcp",
"headers": {
"Authorization": "Bearer ${input:aigw-key}"
}
}
}
}On GitHub, open infra/mcp.json.
Start the ai-gateway-learn server from the mcp.json editor and paste your runtime key when prompted. In
Copilot Chat agent mode, the gateway's namespaced tools are now available, for example
learn_microsoft_docs_search.
Call the tools from Python
This client uses the official MCP Python SDK and sends the runtime key as a bearer token.
"""List, and optionally call, the tools that an AI Gateway MCP server publishes.
Usage:
export AI_GATEWAY_URL="<gateway-url>"
export AI_GATEWAY_API_KEY="..." # never commit this value
python list_tools.py [server-name] [tool-name] [query]
Examples:
python list_tools.py learn
python list_tools.py learn learn_microsoft_docs_search "What is AI Gateway?"
Set AI_GATEWAY_MCP_ENDPOINT to use a full MCP endpoint URL instead of building it from AI_GATEWAY_URL.
"""
import asyncio
import os
import sys
import httpx
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client
from mcp.shared.exceptions import McpError
def endpoint(server: str) -> str:
if os.environ.get("AI_GATEWAY_MCP_ENDPOINT"):
return os.environ["AI_GATEWAY_MCP_ENDPOINT"]
base = os.environ.get("AI_GATEWAY_URL")
if not base:
sys.exit("Set AI_GATEWAY_URL to the gateway runtime URL, for example https://aigw-labs-k3v7qz2m9xw4p.eastus2-01.ai.gateway.azure.com")
return f"{base.rstrip('/')}/default/toolservers/{server}/mcp"
async def main() -> None:
server = sys.argv[1] if len(sys.argv) > 1 else "learn"
tool = sys.argv[2] if len(sys.argv) > 2 else None
query = sys.argv[3] if len(sys.argv) > 3 else "What is Azure AI Gateway?"
api_key = os.environ.get("AI_GATEWAY_API_KEY")
if not api_key:
sys.exit("Set AI_GATEWAY_API_KEY to a runtime key from Access > API keys")
url = endpoint(server)
print(f"MCP endpoint: {url}")
# The gateway authenticates the client with the runtime key, sent as a bearer token.
async with httpx.AsyncClient(headers={"Authorization": f"Bearer {api_key}"}, timeout=60) as http_client:
async with streamable_http_client(url, http_client=http_client) as (read, write, _):
async with ClientSession(read, write) as session:
init = await session.initialize()
print(f"Server: {init.serverInfo.name} protocol: {init.protocolVersion}\n")
result = await session.list_tools()
for t in result.tools:
description = " ".join((t.description or "").split())[:70]
print(f"{t.name:<45} {description}")
print(f"\n{len(result.tools)} tools published")
if tool:
print(f"\nCalling {tool} with query: {query}")
try:
call = await session.call_tool(tool, {"query": query})
except McpError as error:
print(f"The tool call failed: {error}")
return
text = "\n".join(c.text for c in call.content if c.type == "text")
if call.isError:
print(f"The tool call failed: {text}")
return
print(text[:600] + "\n...")
if __name__ == "__main__":
asyncio.run(main())On GitHub, open infra/list_tools.py.
# Create a virtual environment in .venv and activate it, so that the packages stay out of your global Python
python -m venv .venv && source .venv/bin/activate &&
echo "📦 Virtual environment .venv is active"
# Install the MCP Python SDK and httpx, which the script uses
pip install -r infra/requirements.txt &&
echo "📦 The packages in infra/requirements.txt are installed"
# List the tools on learn through your gateway, then call learn_microsoft_docs_search
echo "🔧 Tools on learn, and a call to learn_microsoft_docs_search:"
python infra/list_tools.py learn learn_microsoft_docs_search "How do I add a token limit in AI Gateway?"# Create a virtual environment in .venv and activate it, so that the packages stay out of your global Python
python -m venv .venv; .venv/Scripts/Activate.ps1
if ($?) { Write-Host "📦 Virtual environment .venv is active" }
# Install the MCP Python SDK and httpx, which the script uses
pip install -r infra/requirements.txt
if ($?) { Write-Host "📦 The packages in infra/requirements.txt are installed" }
# List the tools on learn through your gateway, then call learn_microsoft_docs_search
Write-Host "🔧 Tools on learn, and a call to learn_microsoft_docs_search:"
python infra/list_tools.py learn learn_microsoft_docs_search "How do I add a token limit in AI Gateway?"Verify
List the published tools
MCP clients start with a handshake: initialize, then notifications/initialized, then tools/list. The
script runs that handshake through your gateway, reads JSON or server-sent event (SSE) responses, and prints
every published tool. Run it from the lab folder.
# Run the MCP handshake through your gateway, and list every tool that learn publishes
echo "🔧 Tools on learn:"
./infra/list-tools.sh learn# Run the MCP handshake through your gateway, and list every tool that learn publishes
Write-Host "🔧 Tools on learn:"
./infra/list-tools.ps1 -Server learnOn GitHub, open list-tools.sh or list-tools.ps1.
Expected output (descriptions are shortened, and the tool list can change as the Learn server evolves):
🔧 Tools on learn:
MCP endpoint: <gateway-url>/default/toolservers/learn/mcp
Server: <server-name-reported-by-the-gateway> protocol: <negotiated-version>
Tool Description
docs_microsoft_code_sample_search Search for code snippets and examples in official Microsoft Learn docu
docs_microsoft_docs_fetch Fetch and convert a Microsoft Learn documentation webpage to markdown
docs_microsoft_docs_search Search official Microsoft/Azure documentation to find the most relevan
learn_microsoft_code_sample_search Search for code snippets and examples in official Microsoft Learn docu
learn_microsoft_docs_fetch Fetch and convert a Microsoft Learn documentation webpage to markdown
learn_microsoft_docs_search Search official Microsoft/Azure documentation to find the most relevan
6 tools publishedEach tool carries its backend's namespace. With MCP version 2025-06-18 pinned, the gateway sorts the tools by
name. With the legacy defaults, it lists them backend by backend, learn first. Use the exact names that your output
shows in the next steps.
Call a tool through the gateway
# List the tools again, then call learn_microsoft_docs_search with a question
echo "🔧 Tools on learn, and a call to learn_microsoft_docs_search:"
./infra/list-tools.sh learn learn_microsoft_docs_search "How do I add a token limit in AI Gateway?"# List the tools again, then call learn_microsoft_docs_search with a question
Write-Host "🔧 Tools on learn, and a call to learn_microsoft_docs_search:"
./infra/list-tools.ps1 -Server learn -Tool learn_microsoft_docs_search -Query "How do I add a token limit in AI Gateway?"After the tool list, the script prints the start of the search results that Microsoft Learn returned through your gateway.
Send a raw JSON-RPC request
The docs show the smallest possible request: a single JSON-RPC tools/list call. Streamable HTTP clients
should also accept both JSON and SSE responses.
# Send a single tools/list request, with your runtime key as a bearer token
echo "🔧 tools/list response from learn:"
curl -sS "${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 answer is JSON or an SSE data: line with a result.tools array. If the server answers with a JSON-RPC
error instead, it requires the full handshake. Use the script, which runs it for you.
Prove that the gateway checks the caller
Send the same request without the key:
# Send the same request without the Authorization header
echo "🚦 Expect 401 Unauthorized without a key:"
curl -sS -o /dev/null -w "🚦 HTTP %{http_code}\n" "${AI_GATEWAY_URL%/}/default/toolservers/learn/mcp" \
-H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'The gateway rejects the request, typically with 🚦 HTTP 401, and no backend is called. Microsoft Learn is public,
but your MCP endpoint isn't.
The script lists namespaced tools from both backends, a tool call returns Microsoft Learn content, and a request without a key is rejected.
Go further
- Control the catalog. Publish only approved tools, block risky ones, and rate-limit the server in Control which tools agents can call.
- Screen tool traffic. Content safety also screens tool inputs and responses on MCP servers. See Screen prompts and responses with content safety.
- Go keyless. Grant callers the AI Gateway User role and send a Microsoft Entra token instead of a runtime key. See Go keyless with Microsoft Entra ID and RBAC.
- Watch tool traffic. When Application Insights is configured, tool executions appear in MonitoringTools. See Monitor usage, cost, and traces.
- Onboard GitHub. Add the GitHub MCP server,
https://api.githubcopilot.com/mcp/, as an MCP server backend with API Key authentication: Header nameAuthorizationand ValueBearer <your-github-token>. The gateway stores the token, and clients never see it. - Use OAuth backends. Sign in once for a shared backend account with Connect shared OAuth backends, or call the backend with each caller's own Microsoft Entra permissions with Access MCP server backends with user credentials.
- Import from Azure. Add API Management APIs, Azure Functions MCP tools, and Connector Namespace servers with Discover and import Azure-hosted MCP servers.
- Give tools to an agent. Point an agent framework at the endpoint in Connect agent frameworks to models and tools.
Clean up
MCP servers don't add charges beyond the gateway itself. Keep learn if you continue with
Control which tools agents can call, which builds on it.
Remove the second backend or the server
To remove only the docs backend, open the actions menu of its row under Backends on the learn details page
and select Delete. To remove the whole server, select More actionsDelete on the details page.
Remove the second source or the server
# Remove only the optional backend
az aigateway mcp source remove -g "$RG" --gateway-name "$GATEWAY" -n learn --namespace docs --query "[].namespace" &&
echo "🚮 Backend docs is removed from learn"
# Or remove the whole MCP server
az aigateway mcp delete -g "$RG" --gateway-name "$GATEWAY" -n learn --yes &&
echo "🚮 MCP server learn is deleted"# Remove only the optional backend
az aigateway mcp source remove -g $RG --gateway-name $GATEWAY -n learn --namespace docs --query "[].namespace"
if ($?) { Write-Host "🚮 Backend docs is removed from learn" }
# Or remove the whole MCP server
az aigateway mcp delete -g $RG --gateway-name $GATEWAY -n learn --yes
if ($?) { Write-Host "🚮 MCP server learn is deleted" }mcp source remove prints the backends that remain. An MCP server needs at least one backend, so the command
refuses to remove the last one with "Cannot remove the last source." Delete the server instead.
Delete everything azd created
In the aigateway/labs/04-federate-mcp-tools folder, delete the resource group with the gateway, the learn MCP
server, and the key. --purge also purges soft-deleted resources. It takes
about three minutes.
# Delete the resource group with everything that azd up created, and purge soft-deleted resources
azd down --purge --force &&
echo "🚮 Everything that azd up created is deleted"To keep this gateway instead, skip azd down. To go back to one backend, run
azd env set MCP_SECOND_NAMESPACE "", then azd provision.
Delete everything Terraform created
In the aigateway/labs/04-federate-mcp-tools folder, delete the resource group with the gateway, the learn MCP
server, and the key. It takes about a minute.
# Delete the resource group with everything that terraform apply created
terraform -chdir=terraform destroy -auto-approve &&
echo "🚮 Everything that terraform apply created is deleted"To keep this gateway instead, skip terraform destroy. To go back to one backend, run
terraform -chdir=terraform apply without -var second_namespace=docs.
Remove the client configuration
Delete the ai-gateway-learn entry from .vscode/mcp.json and the .venv folder you created.
Keep your gateway from lab 01: the next labs reuse it. azd down and terraform destroy don't touch it, because the
Bicep + azd and Terraform tracks created their own gateway.
Next steps
- Control which tools agents can call: allow and block tools by name, and rate-limit the server.
- Connect agent frameworks to models and tools: give an agent your governed tools and models.
- Set gateway-wide policy baselines: apply defaults to every MCP server and model.
- Docs: Federate MCP servers and tools, Create a federated MCP server, and Required and optional backends.
- Releases: October 16 release: MCP 2026-07-28 protocol versions and November 6 release: on-behalf-of authentication for MCP backends.