MCP Azure APIM Workshop

本工作坊演示了如何使用Azure API管理（APIM）将现有的REST API作为模型-上下文-协议（MCP）服务器公开。然后，该MCP服务器可以被各种客户端（包括使用Azure AI服务构建的AI代理）用作工具。

在本工作坊中，您将学习：

• 使用Azure Developer CLI (azd) 部署Azure基础设施
• 在APIM上将一个REST API公开为MCP服务器
• 从不同客户端调用MCP服务器：
  • 使用fastmcp库的Python脚本
  • 使用azure-ai-agents库的Python脚本
• 通过GitHub Copilot MCP工具调用MCP服务器
• 通过APIM策略在MCP服务器上添加安全层

本工作坊利用公共Setlist.fm API作为示例。它使用Bicep和Azure Developer CLI (azd) 配置所需的Azure基础设施。 Setlist.fm是一个协作在线平台，专注于记录演出列表——艺术家或乐队在演唱会期间演奏的歌曲列表。与官方演出列表不同，Setlist.fm关注的是实际在活动中播放的内容。

文档

• https://learn.microsoft.com/zh-cn/azure/api-management/mcp-server-overview
• https://devblogs.microsoft.com/foundry/announcing-model-context-protocol-support-preview-in-azure-ai-foundry-agent-service/
• https://devblogs.microsoft.com/blog/connect-once-integrate-anywhere-with-mcps

工作坊

1. 配置Azure资源

此项目使用azd来配置Azure资源

azd auth login
azd up

系统会提示您选择部署基础设施的位置：

新建环境'dev'已创建并设置为默认值
? 选择要使用的Azure订阅：25. xxxxx-qqqqqqq-xxxxx (111111111-1111-1111-1111-11111111)
? 选择要使用的资源组：1. 创建新的资源组
? 选择用于创建资源组的位置：50. (美国)东部2 (eastus2)
? 输入新资源组的名称：rm-mcp-dev

此存储库使用Azure Bicep进行配置，定义了以下资源：

1. API管理 管理应用程序的API，提供API调用的网关，用于MCP功能以公开API
2. 应用洞察 监控应用程序性能和使用情况，提供有关应用程序健康状况的见解。
3. 日志分析工作区 收集并分析来自各种资源的日志数据，用于监控和故障排除。
4. AI铸造 部署AI模型，具体来说是用于推理的GPT-4.1小型模型。
5. SetlistFM API 提供对SetlistFM API的访问，允许用户使用APIM检索演出列表数据。
6. API密钥的命名值 安全地存储API密钥，以便访问SetlistFM API。
7. EntraID中的应用注册 管理OAuth2权限范围。

2. 将API公开为MCP服务器

前往Azure门户 https://portal.azure.com，选择APIM实例和MCP服务器（预览） 创建一个MCP服务器，公开API作为MCP服务器

• API: SetList FM
• API操作: 搜索艺术家, 搜索演出列表
• 显示名称: SetlistFM MCP
• 名称: setlistfm-mcp 注意: 此值必须与.vscode/mcp.json和src/python/.env中的值匹配

测试SetList FM API：

# 脚本显示The Weeknd最近的演出列表
./src/shell/test_api.sh

MCP服务器已准备好！

3. 设置Python环境

cd src/python
uv venv --clear
source .venv/bin/activate
uv sync

4. Fastapi MCP客户端（Python）

mcp_client.py使用一个库充当MCP客户端。它列出公开的工具，并调用它们：searchForArtists(coldplay) 和 searchForSetlists(Blondshell)

uv run mcp_client.py

示例输出

🔗 测试连接到 https://mcp-azure-apim-api-management-dev.azure-api.net/setlistfm-mcp/mcp... ✅ 成功认证！ 🔧 可用工具（2）： [...] 🔗 搜索名称中包含"Coldplay"的艺术家

名称	URL
[...]

---

🔗 获取Blondshell的演出列表 🎤 23-09-2025 · 历史（多伦多） 巡演: 清除 链接: https://www.setlist.fm/setlist/wolf-alice/2025/history-toronto-on-canada-2b47f072.html [...] 👋 关闭客户端...

5. GitHub Copilot MCP工具（vscode）

GitHub Copilot在代理模式下可以包含在mcp.json文件中定义的外部工具。

在此工作坊中，此文件由azd up命令自动生成。您可以查看文件内容mcp.json。

注意: 生成可以通过以下命令手动触发 azd hooks run preprovision

要从copilot调用MCP工具，请在copilot聊天中键入以下文本：

#searchForArtists coldplay

Copilot应请求您验证MCP工具的使用：

示例：MCP和GitHub Copilot代理模式

<video src="https://github.com/user-attachments/assets/fa736a42-af49-4124-8d43-7abde7525d77" width="600" autoplay loop muted> 您的浏览器不支持视频标签。 </video>

6. Azure Ai Foundry上的自定义代理（Python）

MCP旨在为任何代理提供工具。这是一个示例，其中azure_ai_agent_mcp.py使用Azure Agent Service库创建一个配置为使用SetlistFM MCP服务器作为工具的Azure AI Foundry代理。

uv run azure_ai_agent_mcp.py

示例输出：

设置Setlist FM插件 https://mcp-azure-apim-api-management-dev.azure-api.net/setlistfm-mcp/mcp [...] 对话： 用户：你能提供关于Wolf Alice在2025年表演的音乐会和演出列表的详细信息吗？提供平均演出列表长度和最常演奏的歌曲。 助手：在2025年，Wolf Alice进行了多次演出，大多数是从他们的巡演"The Clearing"和一些亲密的现场演出。以下是关键细节： [...]

对话结束后，可以在AI Foundry门户中查看执行的线程：

7. APIM中的MCP策略（EntraID）

由于MCP服务器有自己的策略层，因此可以实现多种场景。

• 在MCP端设置速率限制以保护API部分
• 管理入站身份验证、授权（EntraID / OAuth2）
• 管理出站身份验证、授权到后端API（Header）
• 更新请求文档或响应文档

定义MCP策略的步骤如下：

1. 打开Azure门户并选择APIM实例
2. 选择左侧的MCP服务器并打开mcp-setlist-fm服务器
3. 打开策略菜单

在此示例中，定义了一个EntraID应用程序来表示MCP服务器。客户端将执行EntraId身份验证过程，策略验证提供的令牌，然后添加一个头以注入Ocp-Apim-Subscription-Key值。

它实现了这个APIM模式：使用APIM策略和Entra ID及App Roles进行API身份验证

文档：使用API管理（APIM）的安全MCP服务器访问 / 基于令牌的身份验证（OAuth 2.1与Microsoft Entra ID）

1. 复制以下内容 src/apim/setlistfm/mcp-policy-setlistfm-entra-id.xml（在执行azd up命令时生成的文件，您可以再次运行生成命令azd hooks run postprovision）

   .....
   <inbound>
        <validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="未经授权由于Benoit APIM策略" require-expiration-time="true" require-scheme="Bearer" require-signed-tokens="true">
            <openid-config url="https://login.microsoftonline.com/OAUTH_TENANT_ID/v2.0/.well-known/openid-configuration" />
            <audiences>
                <audience>api://OAUTH_APP_ID</audience>
            </audiences>
            <issuers>
                <issuer>https://sts.windows.net/OAUTH_TENANT_ID/</issuer>
            </issuers>
        </validate-jwt>
		<!-- 为后端服务设置订阅密钥头 -->
		<set-header name="Ocp-Apim-Subscription-Key" exists-action="override">
			<value>SETLISTAPI_SUBSCRIPTION_KEY</value>
		</set-header>
		<base />
	</inbound>
   .....

如果您运行之前的Python代码，将会收到一个401错误：

uv run mcp_client.py

🔗 测试连接到 https://mcp-azure-apim-api-management-dev.azure-api.net/setlistfm-mcp/mcp... ❌ 失败 : 客户端错误 '401 未授权' 对于url 'https://mcp-azure-apim-api-management-dev.azure-api.net/setlistfm-mcp/mcp' 有关更多信息，请参阅：https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Status/401 👋 关闭客户端...

运行以下测试：

uv run mcp_client_entra_id.py  default_credential|client_secret|msal

无论选择哪个选项，当使用简单的基本身份验证时，输出应该相同。 选项包括：

• default_credential 使用神奇的DefaultAzureCredential，支持多种Azure身份验证功能。它重用了az login或azd auth login
• client_secret 使用client_id、client_secret和tenant_id属性
• client_secret 使用client_id、client_secret和tenant_id属性以及MSAL（Microsoft身份验证库）库。这是一组客户端SDK家族（针对Python、.NET、Java、JavaScript等），隐藏了标准身份协议的底层细节。在幕后，MSAL使用OAuth 2.0和OpenID Connect端点与Microsoft Entra ID（以前称为Azure AD）通信。

8. 清理

azd down --force --purge