使用说明

MCP网关

MCP网关 是一个反向代理和管理层模型上下文协议（MCP）服务器，实现Kubernetes环境中MCP服务器的可扩展、会话感知路由、授权和生命周期管理。

概述

该项目提供：

一个数据网关，用于将流量路由到具有会话相关性的MCP服务器。
用于管理MCP服务器生命周期（部署、更新、删除）的控制平面。
企业级集成点，包括遥测、访问控制和可观察性。

关键概念

MCP服务器：实现模型上下文协议的服务器，通常是可流式传输的HTTP端点。
适配器：表示网关中MCP服务器的逻辑资源，在 /adapters 范围。被设计为与其他资源类型共存（例如。， /agents)在统一的人工智能开发平台上。
工具：使用MCP工具定义注册的资源，可以通过工具网关路由器动态路由。每个工具都包含有关其执行端点和输入模式的元数据。
工具网关路由器：充当智能路由器的MCP服务器，根据工具定义将工具执行请求引导到适当的注册工具服务器。多个路由器实例可以在网关后面运行，以实现会话关联。
会话感知状态路由：确保所有具有给定条件的请求 session_id 被一致地路由到相同的MCP服务器实例。

建筑

flowchart LR
    subgraph Clients[" "]
        direction TB
        DataClient["🔌 Agent/MCP<br>Data Client"]
        MgmtClient["⚙️ Management<br>Client"]
    end

    subgraph Gateway["MCP Gateway"]
        direction TB
        
        subgraph Auth1["Authentication & Authorization"]
            Auth["🔐 Data Plane Auth<br>Bearer Token / RBAC"]
            Auth2["🔐 Control Plane Auth<br>Bearer Token / RBAC"]
        end
        
        subgraph DataPlane["Data Plane"]
            Routing["🔀 Adapter Routing<br>/adapters/{name}/mcp"]
            ToolRouting["🔀 Tool Router Gateway<br>/mcp"]
        end

        subgraph ControlPlane["Control Plane"]
            direction LR
            AdapterMgmt["📦 Adapter Management<br>/adapters CRUD"]
            ToolMgmt["🔧 Tool Management<br>/tools CRUD"]
        end
        
        subgraph Management["Backend Services"]
            DeploymentMgmt["☸️ Deployment Manager"]
            MetadataMgmt["📋 Metadata Manager"]
        end
    end

    subgraph Cluster["Kubernetes Cluster"]
        direction TB
        
        subgraph ServerRow[" "]
            direction LR
            
            subgraph MCPServers["MCP Servers"]
                direction TB
                PodA["mcp-a-0"]
                PodA1["mcp-a-1"]
                PodB["mcp-b-0"]
            end
            
            subgraph ToolRouters["Tool Gateway Routers"]
                direction TB
                Router1["toolgateway-0"]
                Router2["toolgateway-1"]
            end
        end
        
        subgraph ToolServers["Registered Tool Servers"]
            direction LR
            Tool1["tool-1-0"]
            Tool2["tool-2-0"]
        end
    end

    Metadata[("💾 Metadata Store<br>Server & Tool Info")]

    DataClient -->|"MCP Requests"| Auth
    MgmtClient -->|"API Calls"| Auth2
    
    Auth --> Routing
    Auth --> ToolRouting
    Auth2 --> AdapterMgmt
    Auth2 --> ToolMgmt
    
    AdapterMgmt & ToolMgmt --> DeploymentMgmt
    AdapterMgmt & ToolMgmt --> MetadataMgmt
    
    Routing -.->|"Session Affinity"| MCPServers
    ToolRouting -.->|"Session Affinity"| ToolRouters
    ToolRouters ==>|"Dynamic Routing"| ToolServers
    
    DeploymentMgmt -->|"Deploy & Monitor"| Cluster
    MetadataMgmt <-->|"Read/Write"| Metadata

    style Gateway fill:#e1f5ff
    style Cluster fill:#fff4e1
    style Metadata fill:#f0f0f0

特性

控制平面——用于MCP服务器管理的RESTful API

MCP服务器管理（适配器）

POST /adapters --部署并注册新的MCP服务器。
GET /adapters --列出用户可以访问的所有MCP服务器。
GET /adapters/{name} --检索特定适配器的元数据。
GET /adapters/{name}/status --检查部署状态。
GET /adapters/{name}/logs --访问服务器的运行日志。
PUT /adapters/{name} --更新部署。
DELETE /adapters/{name} --删除服务器。

工具登记和管理

POST /tools --使用MCP工具定义元数据注册和部署工具。
GET /tools --列出用户可以访问的所有已注册工具。
GET /tools/{name} --检索特定工具的元数据和工具定义。
GET /tools/{name}/status --检查工具部署状态。
GET /tools/{name}/logs --访问工具服务器的运行日志。
PUT /tools/{name} --更新工具部署和定义。
DELETE /tools/{name} --删除已注册的工具。

数据平面——MCP服务器的网关路由

直接访问MCP服务器

POST /adapters/{name}/mcp --建立可流式传输的HTTP连接。

通过工具网关路由器进行动态工具路由

POST /mcp --将请求路由到工具网关路由器，该路由器根据工具定义动态路由到已注册的工具。路由器本身是一个MCP服务器，在网关后面托管了多个实例，以实现可扩展性。

身份验证和授权支持

网关为mcp服务器和工具提供entra-id身份验证和基本应用程序角色授权：

阅读资源创建者被授予访问权限，主体被分配了配置的角色值（例如 mcp.engineer)，以及任何担任强制管理员角色的人 mcp.admin.
写访问权限仅限于资源创建者或持有 mcp.admin 角色。

有关配置Azure Entra ID（创建 mcp.admin 以及其他角色值，将其分配给用户或服务主体，并在适配器/工具有效负载中提供这些值），请参阅 docs/entra-app-roles.md.

附加功能

新：支持 代理本地和远程MCP服务器。参见示例和用法.
具有分布式会话存储的无状态反向代理（生产模式）。
使用StatefulSets和headless服务进行Kubernetes本地部署。

刀具注册和动态布线

MCP网关现在支持 工具注册 通过动态路由功能，实现了用于管理和执行MCP工具的可扩展架构。

运作原理

工具注册：开发人员通过注册工具 /tools API端点，提供：
- 容器图像详细信息（名称和版本）
- MCP工具定义（名称、描述、输入模式）
- 执行端点配置（端口和路径）
- 部署配置（副本、环境变量）
工具网关路由器：充当智能路由器的专用MCP服务器：
- 在网关后作为多个实例运行，以实现高可用性
- 保持对所有注册工具及其定义的了解
- 将工具执行请求动态路由到相应的工具服务器
- 通过访问 POST /mcp 端点（不带适配器名称）
动态路由：当客户端向发送MCP请求时 /mcp:
- 网关将请求路由到具有会话关联性的可用工具网关路由器实例
- 路由器分析请求中的工具调用
- 根据工具定义，它将执行转发到正确的注册工具服务器
- 结果通过路由器返回给客户端

入门-本地部署

1.准备当地发展环境

2.运行本地Docker注册表

docker run -d -p 5000:5000 --name registry registry:2.7

3.构建和发布MCP服务器映像

构建MCP服务器映像并将其推送到本地注册表(localhost:5000).

docker build -f sample-servers/mcp-example/Dockerfile sample-servers/mcp-example -t localhost:5000/mcp-example:1.0.0
docker push localhost:5000/mcp-example:1.0.0

4.构建和发布MCP网关和工具网关路由器

（可选）打开 dotnet/Microsoft.McpGateway.sln 使用Visual Studio。

发布MCP网关映像：

dotnet publish dotnet/Microsoft.McpGateway.Service/src/Microsoft.McpGateway.Service.csproj -c Release /p:PublishProfile=kamalberrybytes.pubxml

发布工具网关路由器映像：

dotnet publish dotnet/Microsoft.McpGateway.Tools/src/Microsoft.McpGateway.Tools.csproj -c Release /p:PublishProfile=kamalberrybytes.pubxml

5.将MCP网关部署到Kubernetes集群

应用部署清单：

kubectl apply -f deployment/k8s/local-deployment.yml

6.启用端口转发

转发网关服务端口：

kubectl port-forward -n adapter svc/mcpgateway-service 8000:8000

7.测试API-MCP服务器管理

从导入OpenAPI定义 openapi/mcp-gateway.openapi.json 进入工具类邮递员, 布鲁诺，或 Swagger编辑器.

发送创建新适配器资源的请求：

POST http://localhost:8000/adapters
Content-Type: application/json

{
   "name": "mcp-example",
   "imageName": "mcp-example",
   "imageVersion": "1.0.0",
   "description": "test"
}

8.测试API-MCP服务器访问

部署MCP服务器后，使用类似以下的客户端 VS Code 以测试连接。请参阅指南：在VS代码中使用MCP服务器.

注：确保VSCode是最新的，以访问最新的MCP功能。
- 连接到已部署的 mcp-example 服务器，使用：
  - http://localhost:8000/adapters/mcp-example/mcp （流式HTTP）
样品 .vscode/mcp.json 连接到 mcp-example 服务器
```
{
  "servers": {
    "mcp-example": {
      "url": "http://localhost:8000/adapters/mcp-example/mcp",
    }
  }
}
```
对于其他服务器：
- http://localhost:8000/adapters/{name}/mcp （流式HTTP）

9.测试工具注册和动态路由

构建并发布工具服务器映像

首先，构建工具服务器映像并将其推送到本地注册表：

docker build -f sample-servers/tool-example/Dockerfile sample-servers/tool-example -t localhost:5000/weather-tool:1.0.0
docker push localhost:5000/weather-tool:1.0.0

注册工具

发送注册工具及其定义的请求：

POST http://localhost:8000/tools
Content-Type: application/json

{
  "name": "weather",
  "imageName": "weather-tool",
  "imageVersion": "1.0.0",
  "description": "Weather tool for getting current weather information",
  "toolDefinition": {
    "tool": {
      "name": "weather",
      "title": "Weather Information",
      "description": "Gets the current weather for a specified location.",
      "type": "http",
      "inputSchema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          }
        },
        "required": ["location"]
      }
    },
    "port": 8000
  }
}

验证工具部署

检查工具部署状态：

GET http://localhost:8000/tools/weather/status

通过工具网关路由器进行测试工具路由

使用MCP客户端（如VS Code）连接到工具网关路由器：

样品 .vscode/mcp.json 其连接到工具网关路由器：

{
  "servers": {
    "tool-gateway": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

路由器将根据MCP请求中的工具名称自动将工具调用路由到相应的注册工具服务器。

10.清洁环境

要删除所有已部署的资源，请删除Kubernetes命名空间：

kubectl delete namespace adapter

入门-部署到Azure

云基础设施

1.准备云开发环境

活跃 Azure订阅随着 所有者 访问
安装Azure命令行界面

2.设置Entra ID（Azure Active Directory）

云部署的服务需要使用Azure Entra ID进行承载令牌身份验证。请按照以下步骤配置应用程序注册。

创建和配置应用程序注册

首选应用程序注册
点击 +新注册
- 名字：选择一个有意义的名字，例如。， mcp-gateway
- 支持的帐户类型：选择 单租户
- 点击注册
转到应用程序注册概述并复制：
- 应用程序（客户端）ID -这是用于部署的API客户端ID

公开API（定义范围）

在左侧菜单中，转到 公开API
点击添加旁边 应用程序ID URI，并将其保留为默认值：
```
api://<your-client-id>
```
点击 +添加作用域
- 作用域名称: access
- 管理员同意显示名称: Access MCP Gateway
- 管理员同意说明：任何简短描述
- 点击 添加范围

授权Azure CLI和VS代码作为客户端应用程序

允许Azure CLI和VS Code作为令牌获取的客户端。

仍然 公开API，向下滚动到 授权客户端应用程序
点击 +添加客户端应用程序
- 客户端ID: 04b07795-8ddb-461a-bbee-02f9e1bf7b46 （Azure命令行界面）
- 客户端ID: aebc6443-996d-45c2-90f0-388ff96faa56 （VS代码）
- 在“授权范围”中，选择范围 access
- 点击添加

配置应用程序角色以进行授权

docs/entra-app-roles.md

3.部署服务资源

参数

名称	描述
`resourceGroup`	资源组的名称。必须仅包含小写字母和数字（字母数字）。
`clientId`	应用注册中的Entra ID（Azure AD）客户端ID。
`location`	（可选）将部署资源的Azure区域。默认为资源组的位置。
`resourceLabel`	（可选）一种小写字母数字字符串，用作命名资源的后缀和DNS标签。如果没有提供，它将是resourceGroup名称。建议：将此值设置为默认值，与资源组名称相同，并确保资源组名称仅包含较低的字母数字。

部署将：

通过二头肌模板部署Azure基础架构

资源名称	资源类型
mgreg<resourceLabel>	容器注册表
mg存储-<resourceLabel>	Azure Cosmos数据库帐户
mg aag-<resourceLabel>	应用程序网关
mg ai-<resourceLabel>	应用洞察
mg-aks-<resourceLabel>	Kubernetes服务（aks）
mg标识-<resourceLabel>	托管标识
mg pip-<resourceLabel>	公共IP地址
mg vnet-<resourceLabel>	虚拟网络

部署Kubernetes资源（包括 mcp-gateway)到已配置的AKS集群

注：建议使用托管身份进行无凭据身份验证。此部署遵循该设计。

4.构建和发布MCP服务器映像

网关服务在部署期间从新配置的Azure容器注册表（ACR）中提取MCP服务器映像。

在ACR中构建MCP服务器映像：

az acr build -r "mgreg$resourceLabel" -f sample-servers/mcp-example/Dockerfile sample-servers/mcp-example -t "mgreg$resourceLabel.azurecr.io/mcp-example:1.0.0"

5.测试API-MCP服务器管理

从导入OpenAPI规范 openapi/mcp-gateway.openapi.json 进入邮递员, 布鲁诺，或 Swagger编辑器

在本地获取不记名代币：

az account get-access-token --resource $clientId

发送POST请求以创建适配器资源：

POST http://<resourceLabel>.<location>.cloudapp.azure.com/adapters
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "mcp-example",
  "imageName": "mcp-example",
  "imageVersion": "1.0.0",
  "description": "test",
  "requiredRoles": [] // Add entra id application role to restrict access
}

6.测试API-MCP服务器访问

部署MCP服务器后，使用类似以下的客户端 VS Code 以测试连接。请参阅指南：在VS代码中使用MCP服务器.

注：确保VSCode是最新的，以访问最新的MCP功能。
- 连接到已部署的 mcp-example 服务器，使用：
  - http://<resourceLabel>.<location>.cloudapp.azure.com/adapters/mcp-example/mcp （流式HTTP）
样品 .vscode/mcp.json 连接到 mcp-example 服务器
```
{
  "servers": {
    "mcp-example": {
      "url": "http://<resourceLabel>.<location>.cloudapp.azure.com/adapters/mcp-example/mcp",
    }
  }
}
```
注：访问MCP服务器仍然需要身份验证，VS Code将帮助处理身份验证过程。
对于其他服务器：
- http://<resourceLabel>.<location>.cloudapp.azure.com/adapters/{name}/mcp （流式HTTP）

7.测试工具注册和动态路由

构建并发布工具服务器映像

构建工具服务器映像并将其推送到ACR：

az acr build -r "mgreg$resourceLabel" -f sample-servers/tool-example/Dockerfile sample-servers/tool-example -t "mgreg$resourceLabel.azurecr.io/weather-tool:1.0.0"

注册工具

获取不记名代币：

az account get-access-token --resource $clientId

发送注册工具及其定义的请求：

POST http://<resourceLabel>.<location>.cloudapp.azure.com/tools
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "weather",
  "imageName": "weather-tool",
  "imageVersion": "1.0.0",
  "useWorkloadIdentity": true,
  "description": "Weather tool for getting current weather information",
  "requiredRoles": [], // Add entra id application role to restrict access
  "toolDefinition": {
    "tool": {
      "name": "weather",
      "title": "Weather Information",
      "description": "Gets the current weather for a specified location.",
      "type": "http",
      "inputSchema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          }
        },
        "required": ["location"]
      },
      "annotations": {
        "readOnly": true
      }
    },
    "port": 8000
  }
}

验证工具部署

检查工具部署状态：

GET http://<resourceLabel>.<location>.cloudapp.azure.com/tools/weather/status
Authorization: Bearer <token>

通过工具网关路由器进行测试工具路由

使用MCP客户端（如VS Code）连接到工具网关路由器：

样品 .vscode/mcp.json 其连接到工具网关路由器：

{
  "servers": {
    "tool-gateway": {
      "url": "http://<resourceLabel>.<location>.cloudapp.azure.com/mcp"
    }
  }
}

注：需要身份验证。VS Code将处理身份验证过程。

路由器将根据MCP请求中的工具名称自动将工具调用路由到相应的注册工具服务器。

8.清洁环境

若要删除所有已部署的资源，请从Azure门户删除资源组或运行：

az group delete --name <resourceGroupName> --yes

9.生产入职培训

TLS配置
使用有效的TLS证书在Azure应用程序网关（AAG）侦听器上设置HTTPS。
网络安全
限制虚拟网络内的传入流量，并配置专用端点以增强网络安全性。
遥测
启用高级遥测、详细指标和警报，以支持生产中的监控和故障排除。
扩展
调整缩放比例 mcp-gateway 基于预期负载的服务和MCP服务器。
身份验证和授权
使用Azure Entra ID（AAD）设置OAuth 2.0进行身份验证。使用RBAC或自定义ACL实现细粒度访问控制 adapter 级别权限。

贡献

该项目欢迎各方提供意见和建议。大多数捐款要求您同意贡献者许可协议（CLA）声明您有权并实际授予我们使用您贡献的权利。有关详细信息，请访问https://cla.opensource.microsoft.com.

当您提交拉取请求时，CLA机器人将自动确定您是否需要提供 CLA并适当地装饰PR（例如，状态检查、评论）。只需按照说明进行操作由机器人提供。您只需使用我们的CLA在所有存储库中执行一次此操作。

该项目采用了微软开源行为准则. 有关更多信息，请参阅行为准则常见问题或联系 opencode@microsoft.com 如有任何其他问题或意见。

商标

此项目可能包含项目、产品或服务的商标或徽标。授权使用Microsoft 商标或徽标必须遵守微软商标和品牌指南. 在本项目的修改版本中使用Microsoft商标或徽标不得造成混淆或暗示Microsoft赞助。任何使用第三方商标或徽标的行为均受这些第三方政策的约束。

数据收集

该软件可能会收集有关您和您使用该软件的信息，并将其发送给Microsoft。Microsoft可能会使用此信息提供服务并改进我们的产品和服务。您可以按照存储库中的说明关闭遥测。软件中还有一些功能，可以让您和Microsoft从应用程序的用户那里收集数据。如果您使用这些功能，则必须遵守适用法律，包括向您的应用程序用户提供适当的通知以及Microsoft隐私声明的副本。我们的隐私声明位于https://go.microsoft.com/fwlink/?LinkID=824704.您可以在帮助文档和我们的隐私声明中了解有关数据收集和使用的更多信息。您使用该软件即表示您同意这些做法。

使用说明

MCP网关

目录

概述

关键概念

建筑

特性

控制平面——用于MCP服务器管理的RESTful API

MCP服务器管理（适配器）

工具登记和管理

数据平面——MCP服务器的网关路由

直接访问MCP服务器

通过工具网关路由器进行动态工具路由

身份验证和授权支持

附加功能

刀具注册和动态布线

运作原理

入门-本地部署

1.准备当地发展环境

2.运行本地Docker注册表

3.构建和发布MCP服务器映像

4.构建和发布MCP网关和工具网关路由器

5.将MCP网关部署到Kubernetes集群

6.启用端口转发

7.测试API-MCP服务器管理

8.测试API-MCP服务器访问

9.测试工具注册和动态路由

构建并发布工具服务器映像

注册工具

验证工具部署

通过工具网关路由器进行测试工具路由

10.清洁环境

入门-部署到Azure

云基础设施

1.准备云开发环境

2.设置Entra ID（Azure Active Directory）

创建和配置应用程序注册

公开API（定义范围）

授权Azure CLI和VS代码作为客户端应用程序

配置应用程序角色以进行授权

3.部署服务资源

4.构建和发布MCP服务器映像

5.测试API-MCP服务器管理

6.测试API-MCP服务器访问

7.测试工具注册和动态路由

构建并发布工具服务器映像

注册工具

验证工具部署

通过工具网关路由器进行测试工具路由

8.清洁环境

9.生产入职培训

贡献

商标

数据收集

相关 MCP

Kubernetes管理服务器

多集群Kubernetes管理服务

Kubernetes 自然语言管理 MCP 服务器

Kubernetes自然语言控制服务

MCP服务器与客户端开发工具

Kubernetes管理协议服务器