emqx_mcp_gateway

EMQX MCP 网关

MCP 网关是一个 EMQX 插件，可用于：

1. 让使用 MCP over MQTT 协议的 MCP 客户端与使用其他协议的 MCP 服务交互。
2. 提供统一的方式，用于在 MQTT Broker 上管理和分配 MCP 服务名称。
3. 简化 MCP 服务和客户端的 ACL 配置流程。
4. 提供基于角色的访问控制。

下图展示了使用 MCP over MQTT 的客户端如何通过此网关插件与使用其他协议的 MCP 服务交互：

                                                               ┌────────────────┐         
                                                   ┌─MCP/HTTP──┼ MCP HTTP Server│         
                                                   │           └────────────────┘         
                                                   │                                      
                                                   │                                      
                               ┌───────────────┐   │                                      
     ┌──────────┐              │               │   │           ┌─────────────────┐        
     │MCP Client┼──MCP-MQTT────┼    Gateway    ┼───┼─MCP/STDIO─┼ MCP STDIO Server│        
     └──────────┘              │               │   │           └─────────────────┘        
                               └───────────────┘   │                                      
                                                   │                                      
                                                   │                                      
                                                   │           ┌──────────────────┐       
                                                   └─CALL/gRPC─┼ MCP Server Plugin│       
                                                               └──────────────────┘       

配置 MCP 服务名称和服务名称筛选器

配置 MCP-MQTT 服务的服务名称

MCP 网关支持为 MCP 服务配置由 Broker 建议的 server names，以避免服务名称冲突，并在不同 MCP 服务之间保持命名规范一致。

要为 MCP 服务配置服务名称，请准备一个 mcp_server_name.json 文件，内容如下：

[
  {"condition": "select * where username = 'server-user-1'", "server_name": "devices/vehicle/xiaopeng/EP7"},
  {"condition": "select * where mcp_meta.service_type = 'vehicle'", "server_name": "devices/vehicle/{{mcp_meta.manufacturer}}/{{mcp_meta.vehicle_type}}"}
]

该文件是一个 JSON 文件，其中包含一个对象列表。每个对象有两个字段：condition 和 server_name。 condition 是 MCP 网关可以求值的条件；满足条件时，server_name 是将发送给 MCP 服务的服务名称（通过 CONNACK 数据包中的 MCP-SERVER-NAME 用户属性发送）。

condition 可以是 SQL 表达式，用于匹配 MCP 服务的 username、clientid、mcp_meta 或其他 MQTT 属性。

server_name 是一个模板字符串，渲染后将作为建议的服务名称。例如，{{mcp_meta.vehicle_type}} 将替换为从 MCP-META 获取的 vehicle_type 值。

请注意，配置服务名称后，MCP 网关会自动设置 ACL，将 MCP 服务限制为只能访问与该服务名称匹配的 MQTT 主题。

配置 MCP-MQTT 客户端的服务名称筛选器

同样，MCP 网关也可以为 MCP 客户端配置 server name filters，以便 Broker 引导 MCP 客户端仅连接到其有权访问的特定 MCP 服务。

要为 MCP 客户端配置服务名称筛选器，请准备一个 mcp_server_name_filter.json 文件，内容如下：

[
  {"condition": "select * where username = 'user-1'", "server_name_filters": ["devices/vehicle/#"]},
  {"condition": "select * where mcp_meta.app_type = 'vehicle'", "server_name_filters": ["devices/vehicle/xiaopeng/+", "devices/vehicle/byd/+"]}
]

该文件包含一个 JSON 对象列表，每个对象有两个字段：condition 和 server_name_filters。condition 与 mcp_server_name.json 文件中的条件相同；server_name_filters 是客户端有权访问的服务名称筛选器列表（由 ACL 控制）。满足条件时，server_name_filters 将发送给 MCP 客户端（通过 CONNACK 数据包中的 MCP-SERVER-NAME-FILTERS 用户属性发送）。

请注意，为 MCP 客户端配置服务名称筛选器后，MCP 网关会自动设置 ACL，将 MCP 客户端限制为只能访问与这些服务名称筛选器匹配的 MQTT 主题。

基于角色的访问控制（RBAC）

MCP 网关支持基于角色的访问控制（RBAC），用于管理对 MCP 服务及其工具/资源的访问。要配置 RBAC，请准备一个 mcp_rbac.json 文件，内容如下：

[
  {
    "condition": "select * where username = 'user-1'",
    "rbac": [
      {"server_name": "devices/vehicle/xiaopeng/EP7", "role_name": "admin"}
    ]
  },
  {
    "condition": "select * where mcp_meta.app_id = 'app-1'",
    "rbac": [
      {"server_name": "devices/vehicle/byd/song", "role_name": "admin"},
      {"server_name": "devices/vehicle/byd/tang", "role_name": "user"}
    ]
  }
]

当 MCP 客户端连接到 Broker 时，MCP 网关会对条件求值，并通过 CONNACK 数据包向 MCP 客户端发送 MCP-RBAC 用户属性。

MCP 服务可以在元数据中通过 rbac 字段发送在线通知。该字段是 MCP 服务所支持的角色定义列表。请参阅服务注册。

MCP 服务配置示例

连接到 STDIO MCP 服务

在配置文件中添加一个 STDIO MCP 服务：

stdio_servers.weather = {
  enable = true
  server_name = "system_tools/office/weather"
  command = "uv"
  args = [
    "--directory",
    "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather",
    "run",
    "weather.py"
  ]
  env = [
    {"API_KEY", "eee" }
  ]
}

连接到 HTTP MCP 服务

在配置文件中添加一个 HTTP MCP 服务：

http_servers.calculator = {
  enable = true
  server_name = "system_tools/math/calculator"
  url = "https://localhost:3300"
}

使用 EMQX 插件设置嵌入式 MCP 服务

按照文档构建并安装该插件。