MCP Azure APIM研讨会

研讨会利用公众设置列表.fm API 作为一个例子。它使用二头肌和Azure Developer CLI提供必要的Azure基础架构(azd). 设置列表.fm 是一个致力于记录setlists的协作在线平台，setlists是艺术家或乐队在音乐会期间表演的歌曲列表。与官方的setlists不同，Setlist.fm专注于现场活动中实际播放的内容。

文档

https://learn.microsoft.com/en-us/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

车间

![Open in Dev Containers](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/bmoussaud/mcp-azure-apim)

1.配置Azure资源

此项目正在使用 azd 配置Azure资源

azd auth login
azd up

系统将提示您在何处部署基础设施：

New environment 'dev' created and set as default
? Select an Azure Subscription to use: 25. xxxxx-qqqqqqq-xxxxx (111111111-1111-1111-1111-11111111)
? Pick a resource group to use: 1. Create a new resource group
? Select a location to create the resource group in: 50. (US) East US 2 (eastus2)
? Enter a name for the new resource group: rm-mcp-dev

此存储库是使用Azure二头肌配置的，它定义了以下资源：

API管理 管理应用程序的API，为API调用提供网关，用于MCP Feature公开API
应用洞察 监控应用程序性能和使用情况，提供对应用程序健康状况的洞察。
日志分析工作区 从各种资源收集和分析日志数据，以进行监控和故障排除。
AI铸造厂 部署人工智能模型，特别是用于推理的GPT-4.1迷你模型。
设置列表形式API 提供对SetlistFM API的访问，允许用户使用APIM检索集合列表数据。
API密钥的命名值 安全地存储API密钥以用于访问SetlistFM API。
应用注册 在EntraID中管理OAuth2权限范围。
API中心 管理MCP注册表。配置后，转到Azure门户以启用APIC中心门户。

*备注* 这 *API中心* 默认情况下未配置，以启用编辑 infra/main.parameters.json 并设置 configureAPICenter 与价值 True

2.公开API作为MCP服务器

转到Azure门户https://portal.azure.com，选择APIM实例和MCP服务器（预览）创建MCP服务器，将API公开为MCP服务器

API SetList FM
API操作： Search for Artists, Search for Setlists
显示名称： SetlistFM MCP
姓名： setlistfm-mcp

注意：此值必须与.vcode/mcp.json和src/python/.env中的值匹配

MCP Azure APIM

测试集列表FM API：

# the script displays the latest setlist performed by The Weeknd
./src/shell/test_api.sh

MCP服务器已准备就绪！

*备注* 要启用由二头肌文件管理的此配置，请编辑 infra/main.parameters.json 并设置 configureSetListfmMCP 与价值 True

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·历史（多伦多）\ 游览：The Clearing\ 链接：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

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

#searchForArtists coldplay

副驾驶应要求您验证MCP工具的使用情况：

mcp tool

演示：MCP和Github Copilot代理模式

Your browser does not support the video tag.

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

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

uv run azure_ai_agent_mcp.py

样本输出：

Setting up AI Project Client
PROJECT_ENDPOINT: https://foundry-7ephb7ltz2uu2.services.ai.azure.com/api/projects/mcp-dev
Setting up Setlist FM plugin https://apim-7ephb7ltz2uu2.azure-api.net/setlistfm-mcp/mcp
Created agent: SetlistFM-MCP-Agent
Agent ID: SetlistFM-MCP-Agent:1
Agent created (id: SetlistFM-MCP-Agent:1, name: SetlistFM-MCP-Agent, version: 1)
Sending request to agent...
TASK: Can you provide details about recent concerts and setlists in 2025 performed by the band Wolf Alice? Provide the average setlist length and the most frequently played songs.
Response Item Type: mcp_list_tools
Response Item Type: mcp_approval_request
Approving MCP request for server: existing-mcp-tool, request ID: mcpr_0827a8c84ce4fb44006924615f281081949e5f81c37fd308cc
Approving the call of 'searchForSetlists' with the following arguments: {"year":"2025","artistName":"Wolf Alice","p":"1"}
Processed 1 MCP approval requests.
Response Item Type: mcp_call
Response Item Type: message
No MCP approval requests to process.
STOP:  [McpCall(id='mcp_0827a8c84ce4fb44006924615ff9488194a6b2146b967fbab1', arguments='{"year":"2025","artistName":"Wolf Alice","p":"1"}', name='searchForSetlists', ......
Response Item Type: mcp_call
Response Item Content: {
   "type" : "setlists",

对话结束后，可以在 AI铸造门户:

MCP Azure AI Foundry Conversation

MCP Azure AI Foundry Thread Info

7.APIM（EntraID）中的MCP政策

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

在MCP侧设置速率限制，以保护API部件
管理入站身份验证、授权（EntraID/OAuth2）
为了管理基金外的身份验证，对后端api（Header）进行授权
更新请求文档或响应文档

定义MCP策略的步骤是：

打开azure门户并选择APIM实例
选择左侧 MCP Servers 并打开 mcp-setlist-fm 服务器
打开策略菜单

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

它正在实现此APIM模式：使用带入口ID和应用程序角色的APIM策略的API管理（APIM）的API身份验证

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

粘贴以下内容 src/apim/setlistfm/mcp-policy-setlistfm-entra-id.xml （在执行过程中生成的文件 azd up 命令，您可以使用 azd hooks run postprovision 命令）

   .....
   
        
            
            
                api://OAUTH_APP_ID
            
            
                https://sts.windows.net/OAUTH_TENANT_ID/
            
        
		
		
			SETLISTAPI_SUBSCRIPTION_KEY
		
		
	
   .....

如果你运行前面的python代码，你会得到一个 401 错误：

uv run mcp_client.py

🔗 测试连接到https://mcp-azure-apim-api-management-dev.azure-api.net/setlistfm-mcp/mcp...\ ❌ 失败：url的客户端错误“401 Unauthorized”https://mcp-azure-apim-api-management-dev.azure-api.net/setlistfm-mcp/mcp'\ 有关更多信息，请查看：https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401\ 👋 关闭客户端。..

运行以下测试：

uv run mcp_client_entra_id.py  default_credential|client_secret|msal

无论选择什么，当使用Header进行简单的基本身份验证时，输出都应该是相同的。选项包括：

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属性以及SAX（Microsoft身份验证库）库。它是一个客户端SDK系列（用于Python、.NET、Java、JavaScript等），隐藏了标准身份协议的连接细节。在幕后，SSO使用OAuth 2.0和OpenID Connect端点与Microsoft Entra ID（以前的Azure AD）进行通信。

8.使用EntraID和APIM保护MCP MS学习

微软了解MCP服务器使GitHub Copilot和其他人工智能代理等客户端能够直接从微软的官方文档中获取可信和最新的信息。它是一个使用流式http的远程MCP服务器。它允许搜索文档、获取完整文章和搜索代码示例。此示例的目的是代理MCP服务器并保护其访问。

此配置已使用GitHub Copilot进行了测试。执行 azd provision 命令配置Azure APIM和Azure EntraID并更新 mcp.json 文件。

Your browser does not support the video tag.

在EntraID方面，Entra ID（Azure AD）应用程序注册为Microsoft Learn MCP代理提供OAuth2/OIDC身份验证。在APIM方面，在Azure API管理中部署MCP（模型上下文协议）代理API，作为Microsoft Learn文档和代码示例API的网关。

两个二头肌模块管理此配置： mslearn模块 mcp-proxy.bicep

在具有可流化传输的APIM中创建MCP类型的API
配置指向的后端https://learn.microsoft.com/api/mcp
应用从src/apim/mslearn/mcpolicy-mslearn.xml加载的自定义策略配置
根据RFC 9728实现受保护资源元数据（PRM）端点：

- 服务器特定的PRM端点，位于MCP API内的/.oknowledge/oauth-protected-resources - MCP资源元数据的全局动态发现端点

为MCP代理配置OAuth2身份验证设置

模块mcpMSLearnApp App-regulat.beep

应用程序名称：mcp代理mslearn（带资源令牌后缀）
权限范围：公开user_impersonate OAuth2权限范围
预先授权的应用程序：VS代码（aebc6443-996d-45c2-90f0-388ff96faa56）已预先授权访问此范围，无需用户同意

身份验证流程：此应用程序注册启用：

客户端应用程序（如VS Code）通过OAuth2对用户进行身份验证
用户通过MCP代理委托访问Microsoft Learn资源
根据此Entra ID应用程序验证承载令牌的APIM策略

基于这些痕迹，这是一个Mermaid序列图，显示了使用OAuth2发现的MCP服务器初始化流程：

此图说明：

生命周期：启动顺序
OAuth2/OIDC发现（RFC 9728）：具有多次回退尝试的身份验证发现流
资源元数据发现：查找受APIM保护的资源元数据
授权服务器发现：定位Entra ID OpenID配置
MCP协议握手：初始化请求/响应和能力交换
工具发现：列出可用的MCP工具（3个Microsoft Learn文档工具）
所示的关键安全模式是受保护资源元数据（PRM）发现机制，其中MCP客户端通过遵循WWW-Authenticate挑战和众所周知的发现URL自动发现OAuth2端点。

sequenceDiagram
    participant VSCode as VS Code Editor
    participant MCP as MCP Server
(secured-mslearn)
    participant APIM as Azure APIM Gateway
(mslearn-mcp)
    participant EntraID as Microsoft Entra ID
(login.microsoftonline.com)
    
    VSCode->>MCP: Start server
    activate MCP
    Note over MCP: Connection State: Starting
    Note over MCP: Connection State: Running
    MCP-->>VSCode: Server ready
    
    Note over VSCode,EntraID: MCP Initialization & OAuth Discovery (RFC 9728)
    
    VSCode->>MCP: initialize (protocolVersion: 2025-11-25)
    Note over MCP: Detecting authentication requirements...
    
    MCP->>APIM: HTTP Request (attempt connection)
    APIM-->>MCP: 401 Unauthorized
WWW-Authenticate: resource_metadata=
    Note over MCP: Found resource_metadata challenge
    
    MCP->>APIM: GET /.well-known/oauth-protected-resource
(server-specific endpoint)
    APIM-->>MCP: 401 Unauthorized
    Note over MCP: Warning: Failed to fetch from server-specific endpoint
    
    MCP->>APIM: GET /.well-known/oauth-protected-resource/mslearn-mcp
(global discovery endpoint)
    APIM-->>MCP: 200 OK + Resource Metadata
(auth_server: tenant URL)
    Note over MCP: Discovered resource metadata
Auth server: .../be38c437.../v2.0
    
    MCP->>EntraID: GET /.well-known/oauth-authorization-server//v2.0
    EntraID-->>MCP: 404 Not Found
    Note over MCP: Warning: OAuth authorization server endpoint failed
    
    MCP->>EntraID: GET /.well-known/openid-configuration//v2.0
    EntraID-->>MCP: 404 Not Found
    Note over MCP: Warning: Direct OpenID config path failed
    
    MCP->>EntraID: GET //v2.0/.well-known/openid-configuration
    EntraID-->>MCP: 200 OK + OpenID Configuration
(token_endpoint, authorization_endpoint, etc.)
    Note over MCP: Discovered authorization server metadata
    
    Note over VSCode,MCP: MCP Protocol Exchange
    
    VSCode->>VSCode: Waiting for initialize response (5s)...
    
    MCP-->>VSCode: initialize result
(capabilities, serverInfo, instructions)
    Note over VSCode: Server: Microsoft Learn MCP Server v1.0.0
3 tools available
    
    VSCode->>MCP: logging/setLevel (level: debug)
    VSCode->>MCP: notifications/initialized
    VSCode->>MCP: prompts/list
    VSCode->>MCP: tools/list
    
    MCP-->>VSCode: prompts/list result (empty)
    MCP-->>VSCode: logging/setLevel result (success)
    MCP-->>VSCode: tools/list result
(microsoft_docs_search,
microsoft_code_sample_search,
microsoft_docs_fetch)
    
    Note over VSCode: Discovered 3 tools
Server ready for use
    deactivate MCP

9.GitHub Copilot和VSCode的MCP注册表。

参考：和https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-mcp-usage/configure-mcp-registry#option-2-使用-酸性磷酸酶-as-an-mcp调节

API_CENTER_RUNTIME_ENDPOINT=$(azd env get-value API_CENTER_RUNTIME_ENDPOINT)
echo "MCP Registry: ${API_CENTER_RUNTIME_ENDPOINT}/workspaces/default/v0.1/servers"
curl  ${API_CENTER_RUNTIME_ENDPOINT}/workspaces/default/v0.1/servers | jq

MCP Registry: https://mcp-demo-iq6gqqdm2wnp6.data.swedencentral.azure-apicenter.ms/workspaces/default/v0.1/servers
{
  "servers": [
    {
      "server": {
        "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
        "name": "2049090721144127476",
        "description": "Setlist.fm MCP for concert details",
        "version": "Original",
        "remotes": [
          {
            "type": "sse",
            "url": "apim-iq6gqqdm2wnp6.azure-api.net/setlistfm-mcp"
          }
        ]
      },
      "_meta": {
        "io.modelcontextprotocol.registry/official": {
          "status": "active",
          "createdAt": "2025-12-05T10:48:11.8074044+00:00",
          "updatedAt": "2025-12-05T10:48:15.2662824+00:00",
          "isLatest": true
        },
        "x-ms-id": "c33a8142-4905-40c7-bbdc-fc6632ab3f3d"
      }
    },
    {
      "server": {
        "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
        "name": "13043750526061366627",
        "description": "Proxy to Microsoft Learn API",
        "version": "Original",
        "remotes": [....

8.清理

azd down --force --purge

MCP Azure Apim

快速接入

详细介绍