使用说明

使用Azure容器应用开始远程MCP服务器之旅（Node.js/TypeScript）

:star: 为了获取最新更新并及时了解变更，请在GitHub上为本仓库点星！

这是一份快速入门指南，提供了使用Azure Container Apps设置远程模型上下文协议（MCP）服务器的基本构建模块。MCP服务器是使用Node.js和TypeScript构建的，可以在无服务器环境中运行各种工具和服务。本项目还实现了一种多层安全架构，结合了基于JWT的认证和基于角色的访问控制（RBAC），以确保MCP服务器端点和工具的安全性。

[!警告] 此处提供的代码仅供演示之用。您的具体场景（包括企业内部的规则、特定的安全控制措施或其他保护机制）可能与本仓库中概述的内容有所不同。对于任何需要身份验证和授权的生产环境和面向客户的资产，务必进行安全审计和威胁建模。

什么是MCP？

模型上下文协议（MCP）是一种开放协议，它允许大型语言模型（LLMs）以标准化的方式与外部工具和服务进行交互。MCP使大型语言模型能够访问和利用各种资源，如数据库、应用程序编程接口（API）和其他服务，从而增强其能力并提供更准确、更相关的响应。

以下是典型MCP服务器设置的架构图：

flowchart TD
    user(("fa:fa-users User"))
    host["VS Code, Copilot, LlamaIndex, Langchain..."]
    clientHttp[MCP HTTP Client]
    serverHttp([MCP HTTP Server])
    agent["Agents (not included in this demo)"]
    AzureOpenAI([Azure AI Foundry])
    GitHub([GitHub Models])
    OpenAI([OpenAI])
    
    tools["fa:fa-wrench Tools"]
    db[(sqlite DB)]

    user --> hostGroup 
    subgraph hostGroup["MCP Host"]
        host -.- agent
        host aaa@ -.- clientHttp
    end
    
    agent -.- AzureOpenAI & GitHub & OpenAI
    
    clientHttp aa@ ---> |"Streamable HTTP (authenticated)"| serverHttp

    subgraph container["ACA or localhost"]
      serverHttp a@ -.- tools
      tools b@ -.- add_todo 
      tools c@ -.- list_todos
      tools d@ -.- complete_todo
      tools e@ -.- delete_todo
    end

    add_todo bb@ --> db
    list_todos cc@--> db
    complete_todo dd@ --> db
    delete_todo ee@ --> db

    %% styles

    classDef animate stroke-dasharray: 9,5,stroke-dashoffset: 900,animation: dash 25s linear infinite;
    classDef highlight fill:#9B77E8,color:#fff,stroke:#5EB4D8,stroke-width:2px
    
    class a animate
    class aa animate
    class aaa animate
    class b animate
    class c animate
    class d animate
    class e animate
    class bb animate
    class cc animate
    class dd animate
    class ee animate

    class container highlight

为什么要使用Azure Container Apps？

Azure Container Apps 是一个完全托管的无服务器容器平台，能够简化容器化应用的部署和管理。此外，Azure Container Apps 还提供了无服务器GPU支持，使您能够自带容器并将其部署到基于GPU的环境中，这些环境能够根据需求自动扩展。

主要优势：

自动扩展——闲置时缩至零，使用时扩展
按秒计费——仅为您实际使用的计算资源付费
易用性——提升开发者的开发速度，并轻松将任何容器带到云端并在GPU上运行
无需基础设施管理——专注于您的模型和应用
企业级功能——开箱即用的支持，让您能够自带虚拟网络、管理身份、私有端点等，并实现全面的数据治理

先决条件

安装最新版本的 VS Code
安装 GitHub Copilot 并且 GitHub Copilot Chat（GitHub 代码补全聊天助手）扩展（或延伸）

在本地运行MCP服务器

如果您希望在本地运行MCP服务器，可以按照以下步骤操作。

您需要在本地机器上安装以下工具：

git（注：在中文语境中，"git"通常直接保留原样，不进行翻译，因为它是一个专有名词，指代一个分布式版本控制系统及其命令行工具。）需要克隆该仓库。
Node.js 以及 npm。

一旦安装了所有先决条件，您就可以按照以下步骤在本地运行MCP服务器：

克隆此存储库：

git clone https://github.com/Azure-Samples/mcp-container-ts
cd mcp-container-ts

安装项目依赖项

npm install

生成一个新的JWT配置：

npm run generate-token -- --admin

[!NOTE]（注：此标记通常用于表示以下内容为注意事项或提示）你也可以通过使用（相应的工具或方法）生成具有不同角色的令牌 --admin， --user 或者 --readonly 标志。生成的令牌将根据您选择的角色具有不同的权限（见 src/auth/authorization.ts （如需更多详情）。

这将追加（或创建）一个新的JWT配置到 .env 项目根目录下的文件。生成的令牌将用于对MCP服务器的请求进行身份验证。

[!重要] 在生产环境中，您应该使用更安全的方法来管理您的密钥和令牌。

启动开发服务器

npm run dev

你应该在终端看到以下输出：

  mcp:db 2025-07-23T16:48:05.381Z PRAGMA journal_mode = WAL +0ms
  mcp:db 2025-07-23T16:48:05.382Z CREATE TABLE IF NOT EXISTS todos (
  mcp:db      id INTEGER PRIMARY KEY AUTOINCREMENT,
  mcp:db      text TEXT NOT NULL,
  mcp:db      completed INTEGER NOT NULL DEFAULT 0
  mcp:db    ) +0ms
  mcp:db 2025-07-23T16:48:05.382Z Database "todos" initialized. +0ms
  mcp:index 2025-07-23T16:48:05.449Z MCP Stateless Streamable HTTP Server +0ms
  mcp:index 2025-07-23T16:48:05.449Z MCP endpoint: http://localhost:3000/mcp +0ms
  mcp:index 2025-07-23T16:48:05.449Z Press Ctrl+C to stop the server +0ms

要访问和使用MCP服务器，请阅读使用您的MCP服务器以下部分。

[!NOTE] （注：这通常用于标记一个注意事项或提示）当应用程序启动时，服务器将创建一个内存中的 SQLite 数据库。该数据库用于存储工具的状态及其与MCP服务器的交互信息。

将MCP服务器部署到Azure容器应用

要将MCP服务器部署到Azure容器应用中，您可以使用Azure开发者命令行界面（azd）。这将使您能够以最少的精力配置并将项目部署到Azure：

安装 Azure 开发者 CLI。

一旦安装了所有先决条件，您就可以按照以下步骤将MCP服务器部署到Azure容器应用中：

克隆此存储库

git clone https://github.com/azure-samples/mcp-container-ts.git
cd mcp-container-ts

登录到您的Azure账户

azd auth login

对于GitHub Codespaces用户，如果之前的命令失败，请尝试：

azd auth login --use-device-code

提供并部署项目（运行此命令时，请确保您处于克隆仓库的文件夹中）：

azd up

部署完成后，您可以使用输出中提供的URL访问MCP服务器。URL大致如下所示：

https://<env-name>.<container-id>.<region>.azurecontainerapps.io

要访问和使用MCP服务器，请阅读使用您的MCP服务器以下部分。

[!NOTE]（注：此标记通常用于指示以下内容为注意事项或提示）如果您只是测试部署过程，可以通过运行以下命令来移除并清理所有已部署的资源，以避免产生任何费用：
azd down --purge --force

其他安装选项

您有几种其他选项来开始使用这个模板。最快的方法是使用GitHub Codespaces，因为它会为您设置所有工具，您可以在浏览器中运行MCP服务器。

GitHub Codespaces（GitHub 代码空间）

你可以使用GitHub Codespaces来虚拟运行这个模板。点击按钮后，将在你的浏览器中打开一个基于Web的VS Code实例：

打开模板（这可能需要几分钟时间）：
打开一个终端窗口
继续执行下一步操作，以在本地运行MCP服务器或将它部署到Azure Container Apps。

[!NOTE]（注：此标记通常用于指示以下内容为重要提示或注意事项）如果你在 GitHub Codespaces 中运行 MCP 服务器，请确保将端口可见性更改为“公开” 点击“端口”选项卡 → 右键点击已打开的端口（默认为3000）→ 端口可见性 → 公开。

VS Code 开发容器

一个相关的选项是VS Code开发容器，它将使用（容器中的）环境在您的本地VS Code中打开项目 Dev Containers 扩展:

安装 Docker Desktop（桌面版）并且 VS Code 开发容器扩展如果尚未安装。
启动 Docker Desktop（如果尚未安装，请先进行安装）
打开项目：
打开一个终端窗口
继续执行下一步操作，以在本地运行MCP服务器或将它部署到Azure容器应用中。

使用您的MCP服务器

选项0 - 使用提供的客户端示例

这个仓库包含一个示例，展示了如何使用MCP服务器与OpenAI模型进行交互。该示例位于 [examples/](./examples/) 目录。

选项1 - 在VS Code中使用mcp.json文件

连接到MCP服务器的最快方式是使用提供的（工具/方法） .vscode/mcp.json 在您的VS Code环境中，使用配置文件来设置MCP服务器。此配置文件包含了MCP服务器所需的设置，包括URL和传输类型。

{
  "inputs": [
    {
      "password": true,
      "id": "mcp-server-token",
      "description": "Enter the token for the MCP server",
      "type": "promptString",
    }
  ],
  "servers": {
    "mcp-server": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer ${input:mcp-server-token}"
      }
    },
    "mcp-server-remote": {
      "type": "http",
      "url": "https://<env-name>.<container-id>.<region>.azurecontainerapps.io/mcp",
      "headers": {
        "Authorization": "Bearer ${input:mcp-server-token}"
      }
    }
  }
}

一旦打开这个文件，您可以点击内嵌的“开始”操作按钮，该按钮将连接到MCP服务器并获取可用的工具。

重要提示： 因为服务器使用JWT令牌进行保护，所以VS Code会提示您输入令牌。您需要复制令牌的值 "JWT_TOKEN" 来自 .env 由……创建的文件 npm run generate-token 命令。

[!NOTE]（注：此标记在中文中通常不直接翻译，但可理解为“注意”或“提示”的意思，具体翻译取决于上下文）在实际应用中，您应该验证令牌并使用更安全的身份验证方法。这只是用于测试目的的演示令牌。了解更多关于如何保护您的服务器的信息这里。

选项2 - 手动将MCP服务器添加到VS Code

从命令面板中添加MCP服务器，并将URL添加到正在运行的服务器的HTTP端点：

对于本地开发，URL 将是：

http://localhost:3000/mcp

对于 Azure 容器应用，URL 将为：

https://<env-name>.<container-id>.<region>.azurecontainerapps.io/mcp

选择 HTTP（HTTP 或服务器发送事件） 要添加的MCP服务器类型。
输入您正在运行的HTTP终端点的URL，包括 /mcp 最后的路径。
输入服务器ID。（可以是您想要的任何名称）
选择您是想在用户设置中运行此操作（对所有应用程序可用）还是在工作区设置中运行（仅对此应用程序可用）
在Copilot聊天代理模式下，输入提示以触发工具，例如，选择一些代码并输入此提示

I need to send an email to Dan, please add that to my todo list.

当提示运行该工具时，请点击“继续”以表示同意，
完成操作后，在终端窗口中按 Ctrl+C 停止 func.exe 主进程，并从命令面板中列出 MCP 服务器，然后停止本地服务器。

选项3 - MCP检查器

在一个新的终端窗口中，安装并运行 MCP 检测器（或：MCP 检查器）

npm run inspect

按住CTRL键点击以从终端中显示的URL加载MCP Inspector网络应用程序（例如：http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=xyz）
将传输类型设置为 Streamable HTTP。
添加认证头： Authorization 以及Bearer令牌，即其值为 "JWT_TOKEN" 来自……的 .env 由（某人/某程序）创建的文件 npm run generate-token 命令。
将URL设置为您的运行中服务器的HTTP端点并连接：

# for local development, use:
http://localhost:3000/mcp

# or use the Azure Container Apps URL:
https://<env-name>.<container-id>.<region>.azurecontainerapps.io/mcp

列出工具。点击一个工具并运行工具。

下一步行动

了解更多关于模型上下文协议
了解更多关于 Azure 容器应用
了解更多关于 Azure AI Foundry（可译为“Azure AI 工厂”或根据具体语境译为“Azure 人工智能铸造厂”，但通常“Azure AI 工厂”更为简洁易懂）
了解更多关于来自微软的相关MCP（可能指“Microsoft Certified Professional”或具体项目/计划的缩写，根据上下文确定）努力/举措

加入社区

我们鼓励您加入我们的Azure AI Foundry开发者社区，分享您的经验、提出问题并获取支持：

aka.ms/foundry/discord（可直接访问的链接，中文意为“Foundry的Discord链接”） - 加入我们的Discord社区，享受实时讨论和支持。
aka.ms/foundry/forum（可译为）：aka.ms/锻造工坊/论坛 - 访问我们的Azure AI Foundry开发者论坛，提出问题并分享您的知识。