星战科技xingzhan.cloud
返回市场
麦克佩SDK功能托管节点

麦克佩SDK功能托管节点

作者：Azure-Samples10 星标更新：2025-11-18
安装使用来源：spider==github.com

项目介绍

在Azure Functions（公开预览版）上托管远程MCP服务器，使用官方MCP SDK构建

此仓库包含在Azure Functions上运行使用Node MCP SDK构建的MCP服务器的说明和示例。该仓库使用天气样本服务器来演示如何实现这一点。您可以克隆并本地运行和测试服务器，然后通过azd up轻松部署到云端，几分钟内即可完成。

观看视频概述

<a href="https://www.youtube.com/watch?v=gLKP41efvo0" target="_blank"> <img src="./media/video-thumbnail.jpg" alt="观看视频" width="500" /> </a>

将MCP服务器作为自定义处理器运行在Azure Functions上

最近，Azure Functions发布了Functions MCP扩展，允许开发者使用Functions编程模型构建MCP服务器，这本质上是Function的事件驱动框架，并将其远程托管在无服务器平台上。

对于已经使用Anthropic的MCP SDKs构建了服务器的人，也可以通过运行它们作为轻量级Web服务器（接收来自Functions主机的事件）来将这些服务器托管在Azure Functions上。它们允许您无需更改代码即可托管已构建的MCP服务器，并从Function的突发扩展、无服务器定价模式和安全特性中受益。

本仓库专注于第二种托管场景：

<div align="center"> <img src="./media/function_hosting.png" alt="显示托管功能应用和自定义处理器应用的图表。" width="500"> </div>

先决条件

确保您拥有以下内容：

[!NOTE] 此示例要求您有权在使用的Azure订阅中创建Microsoft Entra应用程序。

如果您已经有现成的服务器...

[!IMPORTANT] 您的服务器必须是无状态的，并且使用streamable-http传输才能在今天的Azure Functions上远程托管。

以下说明将拉取本地服务器测试和部署所需的内容。最重要的是：host.json，local.settings.json，和infra。Azure Functions仅需要前两个JSON文件。infra目录不是必需的，但它有助于配置Azure资源。

您的项目不太可能有相同名称的文件和目录，但如果确实如此，您需要重命名它们以防止被覆盖。

一旦完成了必要的重命名，请按照以下步骤操作：

  1. 在MCP服务器项目内部，运行azd init --template self-hosted-mcp-scaffold-typescript。
  2. 回答提示
    • 继续在“/your/mcp/project/folder”初始化应用程序吗？选择“是”。
    • 本地和模板中都存在的文件：很可能只有README，您可以保留现有的。
    • 输入唯一的环境名称：这将成为服务器部署所在的资源组名称。
  3. 在host.json中，确保port值与MCP服务器使用的端口相同。
  4. 按照从本地测试服务器部分开始的说明进行操作。

有关模板的更多详细信息，请参阅模板。

如果您是从零开始...

克隆仓库并在Visual Studio Code中打开示例

git clone https://github.com/Azure-Samples/mcp-sdk-functions-hosting-node.git

本地测试服务器

  1. 在根目录下运行npm install以安装依赖项

  2. 运行npm run build以将TypeScript编译为JavaScript

  3. 运行func start以启动本地服务器

  4. 打开_mcp.json_（位于_.vscode_目录中）

  5. 通过选择local-mcp-server上方的_开始_按钮启动服务器

  6. 点击顶部的Copilot图标以打开聊天（或Ctrl+Command+I / Ctrl+Alt+I），然后在问题窗口中切换到_Agent_模式。

  7. 点击工具图标，确保选中local-mcp-server供Copilot在聊天中使用：

    <img src="./media/mcp-tools.png" width="200" alt="MCP工具列表截图">

  8. 当服务器显示可用工具数量时，询问“使用#local-mcp-server返回纽约市的天气。”Copilot应调用其中一个天气工具来帮助回答这个问题。

部署前注册资源提供程序

在部署之前，您需要注册Microsoft.App资源提供程序：

az provider register --namespace 'Microsoft.App'

等待几秒钟以完成注册。您可以通过使用以下命令检查状态：

az provider show -n Microsoft.App

部署

  1. 此示例使用Visual Studio Code作为主要客户端。将其配置为允许的客户端应用程序：

    azd env set PRE_AUTHORIZED_CLIENT_IDS aebc6443-996d-45c2-90f0-388ff96faa56

  2. 如果您的组织需要，指定服务管理引用。如果您不是微软员工且不确定是否需要设置此选项，可以跳过此步骤。但是，如果由于缺少服务管理引用而导致配置失败，则可能需要重新访问此步骤。使用微软租户的微软员工必须提供服务管理引用（您的服务树ID）。没有这个，您将无法创建Entra应用程序注册，配置也会失败。

    azd env set SERVICE_MANAGEMENT_REFERENCE <service-management-reference>

  3. 在根目录下运行azd up。然后选择要部署资源的Azure订阅，并从可用区域中选择。

    部署完成后，您的终端将显示类似以下的输出：

      (✓) 完成: 资源组: rg-resource-group-name (12.061秒)
  (✓) 完成: 应用服务计划: plan-random-guid (6.748秒)
  (✓) 完成: 虚拟网络: vnet-random-guid (8.566秒)
  (✓) 完成: 日志分析工作区: log-random-guid (29.422秒)
  (✓) 完成: 存储帐户: strandomguid (34.527秒)
  (✓) 完成: Application Insights: appi-random-guid (8.625秒)
  (✓) 完成: 函数应用: func-mcp-random-guid (36.096秒)
  (✓) 完成: 私有端点: blob-private-endpoint (30.67秒)

  部署服务 (azd deploy)
  (✓) 完成: 部署服务 api
  - 端点: https://functionapp-name.azurewebsites.net/

在Visual Studio Code中连接到服务器

  1. 在编辑器中打开_mcp.json_。
  2. 通过选择local-mcp-server上方的_停止_按钮停止本地服务器。
  3. 通过选择remote-mcp-server上方的_开始_按钮启动远程服务器。
  4. Visual Studio Code会提示您输入函数应用名称。从终端输出或门户中复制它。
  5. 在_Agent_模式下打开Copilot，并确保在工具列表中选中remote-mcp-server。
  6. VS Code会提示您进行Microsoft身份验证。点击_允许_，然后登录到您的Microsoft帐户（用于访问Azure门户的那个）。
  7. 向Copilot询问“使用#remote-mcp-server返回西雅图的天气。”它应该调用其中一个天气工具来帮助回答。

[!TIP] 除了在_mcp.json_中启动MCP服务器外，您还可以通过点击_更多..._ -> _显示输出_查看服务器的输出。输出提供了有用的信息，例如为什么连接可能会失败。

您还可以点击齿轮图标将日志级别更改为“跟踪”，以获取客户端（Visual Studio Code）和服务器之间交互的更多详细信息。

<img src="./media/log-level.png" width="200" alt="日志级别截图">

展示代为处理（OBO）流程

get-current-user工具展示了如何实现代为处理（OBO）流程，以代表经过身份验证的用户调用Microsoft Graph API。当您的MCP工具需要访问下游服务时，这种模式非常有用。

要测试此工具，向Copilot询问类似于“使用#remote-mcp-server提供登录用户的详细信息”的问题。Copilot会要求您提供链接以访问用户信息的权限。导航到同意URL并授予权限。然后再次向Copilot询问问题。

代为处理（OBO）流程的工作原理

  1. 服务器认证：内置认证功能验证用户并将承载令牌转发到Authorization标头
  2. 令牌提取：MCP工具从请求标头中提取承载令牌
  3. 托管标识断言：托管标识凭据获得用于令牌交换的断言令牌
  4. 令牌交换：OnBehalfOfCredential将承载令牌交换为Microsoft Graph访问令牌
  5. API调用：工具使用交换的令牌调用Microsoft Graph的/me端点
  6. 响应：返回用户信息

注意：此工具需要基础设施部署到Azure。在本地开发中，如果没有额外配置，它将无法工作。

重新部署

如果您想在更改后重新部署服务器，请运行azd deploy。（参见azd命令参考。）

内置服务器认证和授权

服务器应用程序配置了内置服务器认证和授权功能，实现了MCP授权规范的要求，如发出401挑战和暴露受保护资源元数据（PRM）。

在Visual Studio Code的调试输出中，您可以看到MCP客户端和服务器交互的一系列请求和响应。当使用内置MCP服务器授权时，您应该看到以下事件序列：

  1. 编辑器向MCP服务器发送初始化请求。
  2. MCP服务器响应错误，指示需要授权。响应包括指向应用程序受保护资源元数据（PRM）的指针。内置授权功能为服务器应用程序生成PRM。
  3. 编辑器获取PRM并使用它来识别授权服务器。
  4. 编辑器尝试从授权服务器上的知名端点获取授权服务器元数据（ASM）。
  5. Microsoft Entra ID不支持知名端点上的ASM，因此编辑器回退到使用OpenID Connect元数据端点来获取ASM。它试图通过在任何其他路径信息之前插入知名端点来发现这一点。
  6. 实际上，OpenID Connect规范定义了知名端点应在路径信息之后，而Microsoft Entra ID正是在那里托管它的。所以编辑器再次尝试使用那种格式。
  7. 编辑器成功检索ASM。然后它使用此信息及其自己的客户端ID执行登录。此时，编辑器提示您登录并同意应用程序。
  8. 假设您成功登录并同意，编辑器完成登录。它重复对MCP服务器的初始化请求，这次在请求中包含授权令牌。这个重新尝试在调试输出级别不可见，但可以在跟踪输出级别看到。
  9. MCP服务器验证令牌并对初始化请求作出成功的响应。标准MCP流程从此处继续，最终导致发现在此示例中定义的MCP工具。

对其他客户端的支持

除了Visual Studio Code之外，Azure AI Foundry中的代理也可以连接到配置了Easy Auth的Function托管MCP服务器。文档即将推出。

清理资源

当您完成服务器的工作后，可以使用以下命令删除在Azure上创建的资源，避免产生进一步的成本：

azd down

下一步

在其他语言中找到此示例

语言（堆栈）仓库位置
C# (.NET)mcp-sdk-functions-hosting-dotnet
Pythonmcp-sdk-functions-hosting-python

故障排除

以下是出现的一些常见问题。

  1. InternalServerError: 出现了一个意外的InternalServerError。请稍后再试。

    检查是否已注册Microsoft.App资源提供程序：

    az provider show -n Microsoft.App

    如果显示为未注册，请注册它：

    az provider register --namespace 'Microsoft.App'

    成功注册应显示：

    Namespace      RegistrationPolicy    RegistrationState
-------------  --------------------  -------------------
Microsoft.App  RegistrationRequired  Registered

    然后再次运行azd up。

  2. 错误：执行步骤命令'deploy --all'时出错：获取目标资源：找不到资源：无法找到标记为'azd-server-name: api'的资源。请确保服务资源在您的基础架构配置中正确标记，并重新运行配置

    这是一个已知的瞬态错误。尝试重新运行azd up。

  3. 确保您安装了最新版本的Azure Functions核心工具。

    您需要版本>=4.5.0。通过运行func --version检查。

  4. .vscode/mcp.json必须位于根目录，以便VS Code检测MCP服务器注册

    如果您看不到服务器注册上方的_开始_按钮，可能是因为.vscode/mcp.json不在您的工作区文件夹根目录中。