Getting Started with Remote MCP Servers using Azure Container Apps (Node.js/TypeScript)

使用 Azure Container Apps 入门：远程 MCP 服务（Node.js/TypeScript）

本快速入门指南介绍了使用 Azure Container Apps 搭建远程模型上下文协议（MCP）服务的基本组成部分。该 MCP 服务使用 Node.js 和 TypeScript 构建，可在无服务器环境中运行各种工具和服务。本项目还实现了多层安全架构，将基于 JWT 的身份验证与基于角色的访问控制（RBAC）相结合，以保护 MCP 服务端点和工具。

警告

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

什么是 MCP？

模型上下文协议（MCP）是一种开放协议，支持大语言模型（LLM）以标准化方式与外部工具和服务交互。MCP 让 LLM 能够访问和使用各种资源，例如数据库、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 是一个完全托管的无服务器容器平台，可简化容器化应用的部署和运行。ACA 还提供无服务器 GPU 支持，让你可以使用自己的容器，并将其部署到 GPU 支持的环境中，这些环境会根据需求自动扩缩。

主要优势：

• 自动扩缩 – 空闲时缩容至零，随使用量增加而扩容
• 按秒计费 – 仅为实际使用的计算资源付费
• 易于使用 - 加快开发速度，轻松使用任意容器，并在云端 GPU 上运行
• 无需管理基础设施 – 专注于模型和应用
• 企业级功能 – 开箱即用地支持使用自有虚拟网络、托管标识、专用终结点等，并提供全面的数据治理

前置条件

1. 安装最新版本的 VS Code
2. 安装 GitHub Copilot 和 GitHub Copilot Chat 扩展

在本地运行 MCP 服务

如果你更愿意在本地运行 MCP 服务，可以按照以下步骤操作。

你需要在本地计算机上安装以下工具：

• git，用于克隆仓库。
• Node.js 和 npm。

安装好前置条件后，可以按照以下步骤在本地运行 MCP 服务：

1. 克隆此仓库：

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

2. 安装项目依赖

npm install

3. 生成新的 JWT 配置：

npm run generate-token -- --admin

说明

你也可以使用 --admin、--user 或 --readonly 标志生成具有不同角色的令牌。生成的令牌将根据你选择的角色拥有不同的权限（详情请参阅 src/auth/authorization.ts）。

这会在项目根目录的 .env 文件中追加（或创建）新的 JWT 配置。生成的令牌将用于验证发往 MCP 服务的请求。

重要

在生产环境中，应使用更安全的方法来管理机密信息和令牌。

4. 启动开发服务

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

4. 要访问和使用 MCP 服务，请阅读下文的使用你的 MCP 服务部分。

说明

应用启动时，服务会创建一个内存中的 SQLite数据库。此数据库用于存储工具的状态及其与 MCP 服务的交互记录。

将 MCP 服务部署到 Azure Container Apps

要将 MCP 服务部署到 Azure Container Apps，可以使用 Azure Developer CLI（azd）。这样可以轻松地在 Azure 上预配并部署项目：

• 安装 Azure Developer CLI。

安装好前置条件后，可以按照以下步骤将 MCP 服务部署到 Azure Container Apps：

1. 克隆此仓库

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

2. 登录 Azure 帐户

azd auth login

对于 GitHub Codespaces 用户，如果上一条命令失败，请尝试：

azd auth login --use-device-code

1. 预配并部署项目（运行此命令时，请确保位于克隆的仓库文件夹中）：

azd up

4. 部署完成后，你可以使用输出中提供的 URL 访问 MCP 服务。该 URL 格式如下：

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

5. 要访问和使用 MCP 服务，请阅读下文的使用你的 MCP 服务部分。

说明

如果你只是在测试部署，可以运行以下命令移除并清理所有已部署的资源，以避免产生费用：

azd down --purge --force

其他安装选项

你还可以通过其他方式开始使用此模板。最快捷的方式是使用 GitHub Codespaces，因为它会为你设置好所有工具，并且你可以在浏览器中运行 MCP 服务。

GitHub Codespaces

你可以使用 GitHub Codespaces 虚拟运行此模板。该按钮会在浏览器中打开基于 Web 的 VS Code 实例：

1. 打开模板（这可能需要几分钟）：

   

2. 打开终端窗口

3. 继续执行后续步骤，在本地运行 MCP 服务或将其部署到 Azure Container Apps。

说明

如果你在 GitHub Codespaces 中运行 MCP 服务，请务必将端口可见性更改为 Public： 点击“PORTS”选项卡 → 右键单击已打开的端口（默认为 3000）→ Port visibility → Public。

VS Code Dev Containers

另一个相关选项是 VS Code Dev Containers，它会使用 Dev Containers 扩展在本地 VS Code 中打开项目：

1. 如果尚未安装，请安装 Docker Desktop 和 VS Code Dev Containers 扩展。

2. 启动 Docker Desktop（如果尚未安装，请先安装）

3. 打开项目：

   

4. 打开终端窗口

5. 继续执行后续步骤，在本地运行 MCP 服务或将其部署到 Azure Container Apps。

使用你的 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}"
      }
    }
  }
}

打开此文件后，你可以点击内联的“start”操作按钮，连接 MCP 服务并获取可用工具。

**IMPORTANT：**由于服务使用 JWT 令牌进行保护，VS Code 会提示你输入令牌。你需要复制 npm run generate-token 命令创建的 .env 文件中的 "JWT_TOKEN" 值。

说明

在实际场景中，你应验证令牌并使用更安全的身份验证方式。这只是用于测试的演示令牌。了解如何保护服务请点击此处。

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

1. 从命令面板添加 MCP 服务，并填写正在运行的服务的 HTTP 终结点 URL：

对于本地开发，URL 为：

http://localhost:3000/mcp

对于 Azure Container Apps，URL 为：

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

1. 选择 HTTP（HTTP 或 Server-Sent Events） 作为要添加的 MCP 服务类型。
2. 输入正在运行的 HTTP 终结点 URL，并在末尾包含 /mcp 路径。
3. 输入服务 ID。（名称可自行设置）
4. 选择要在用户设置中运行（对你使用的所有应用均可用），还是在工作区设置中运行（仅对此应用可用）。
5. 在 Copilot 聊天的 Agent 模式下输入提示词以触发工具，例如，选择一些代码并输入此提示词

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

7. 系统提示运行工具时，点击 Continue 以表示同意，
8. 完成后，在终端窗口中按 Ctrl+C 停止 func.exe 主机进程，然后从命令面板选择 List MCP Servers 并停止本地服务。

选项 3 - MCP Inspector

1. 在新的终端窗口中，安装并运行 MCP Inspector

npm run inspect

1. 按住 CTRL 并单击终端中显示的 URL（例如 http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=xyz），以打开 MCP Inspector Web 应用
2. 将传输类型设置为 Streamable HTTP。
3. 添加身份验证标头：Authorization，并使用 Bearer 令牌，该令牌的值为 npm run generate-token 命令创建的 .env 文件中的 "JWT_TOKEN"。
4. 将 URL 设置为正在运行的服务的 HTTP 端点，然后单击 Connect：

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

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

5. 列出工具。单击某个工具，然后运行该工具。

后续步骤

• 了解有关 Model Context Protocol 的更多信息
• 了解有关 Azure Container Apps 的更多信息
• 了解有关 Azure AI Foundry 的更多信息
• 了解有关 Microsoft 的相关 MCP 工作 的更多信息

加入社区

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

• aka.ms/foundry/discord​ - 加入我们的 Discord 社区，参与实时讨论并获取支持。
• aka.ms/foundry/forum - 访问 Azure AI Foundry 开发者论坛，提出问题并分享知识。