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

Federate MCP tools behind one endpoint

Register a remote MCP server in Azure AI Gateway, add a second backend under its own namespace, and connect curl, VS Code, and Python to one governed MCP endpoint.

Beginner 30 min PortalCLIBicepTerraformCodeNotebook Updated
Notebook Source Edit

What you'll do

  • Explain the four tool source types and how AI Gateway namespaces the tools of each backend
  • Register the public Microsoft Learn MCP server in the portal, with the Azure CLI, with Bicep and azd, or with Terraform
  • Federate a second backend into the same MCP server and mark it optional
  • Choose the MCP protocol versions the server supports and check what clients negotiate
  • Connect curl, VS Code, and a Python MCP client to the governed endpoint with a runtime key

Before you start

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

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.

Tip

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-call from lab 02. If you don't have one yet, create it in the portal under AccessAPI keys, or, after you set the variables below, run az aigateway api-key create -g "$RG" --gateway-name "$GATEWAY" -n app-first-call and read its value with az 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)"

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 typeWhat you provideWhat clients see
MCP server (remote)The Endpoint URL of a server that speaks Streamable HTTPThe server's tools
OpenAPI specificationA JSON or YAML OpenAPI document (upload, URL, or inline)Selected operations as tools. The operation summary or description becomes the tool description.
From AzureAn 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 SalesforceThe 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.

Note

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.

Choose your track
1

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.

2

Describe the server

On Basic info, set:

FieldValue
Namelearn (part of the endpoint URL; it can't be changed after creation)
Display nameMicrosoft Learn
DescriptionSearch and fetch official Microsoft documentation and code samples.
Supported MCP versions2025-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.

3

Add the Learn backend

On Backends, select Add backendMCP server. In Add MCP backend, set:

FieldValue
Endpoint URLhttps://learn.microsoft.com/api/mcp
AuthenticationNone
Namespace prefixlearn

Select Add. The backend appears in the table with its URL, Type, Authentication, Namespace, and Required columns. Leave Required on.

4

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.

5

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.

Checkpoint

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.

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.

Choose your track
1

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.

Tip

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.

Checkpoint

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 versionsWhat clients get
Not configuredThe 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 chooseVersion 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.

Choose your track
1

Pin the version

  1. On the learn details page, under MCP configuration, find Supported MCP versions. If you created the server in the portal with 2025-06-18, it's already pinned: go to Check the negotiated version. If it lists the legacy defaults, continue.
  2. Select Edit. Under Basic info, open Supported MCP versions and keep only 2025-06-18 selected.
  3. 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.
  4. 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.

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"}}}'

The 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"}'

The gateway rejects it with 🚦 HTTP 400 and Unsupported MCP-Protocol-Version before any backend is called.

Checkpoint

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.

Choose your track
1

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.

Verify

1

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

On 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):

Text
🔧 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 published

Each 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.

2

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?"

After the tool list, the script prints the start of the search results that Microsoft Learn returned through your gateway.

3

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.

Bash
# 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.

4

Prove that the gateway checks the caller

Send the same request without the key:

Bash
# 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.

Checkpoint

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

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.

Choose your track
1

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.

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

Finished the lab?

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