emqx_mcp_gateway

EMQX MCP Gateway

MCP Gateway は、次の機能を提供する EMQX プラグインです。

1. MCP over MQTT プロトコルを使用する MCP クライアントが、他のプロトコルを使用する MCP サーバーとやり取りできるようにします。
2. MQTT ブローカー上で 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 Gateway では、MCP サーバーにブローカーが提案する 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 の2つのフィールドがあります。 condition は MCP Gateway が評価できる条件で、server_name は条件が満たされたときに（CONNACK パケットの MCP-SERVER-NAME ユーザープロパティによって）MCP サーバーに送信されるサーバー名です。

condition には、MCP サーバーの username、clientid、mcp_meta、その他の MQTT プロパティに一致する SQL 式を指定できます。

server_name は、サーバーが提案するサーバー名としてレンダリングされるテンプレート文字列です。たとえば、{{mcp_meta.vehicle_type}} は、MCP-META から取得した vehicle_type の値に置き換えられます。

サーバー名を設定すると、MCP Gateway は MCP サーバーがサーバー名に一致する MQTT トピックにのみアクセスできるよう、ACL を自動的に設定します。

MCP-MQTT クライアントのサーバー名フィルターを設定する

同様に、MCP Gateway では MCP クライアントの server name filters も設定できます。これにより、ブローカーは、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/+"]}
]

このファイルには、condition と server_name_filters の2つのフィールドを持つ JSON オブジェクトのリストが含まれます。condition は mcp_server_name.json ファイルで使用するものと同じで、server_name_filters はクライアントがアクセスを許可されたサーバー名フィルターのリストです（ACL によって制御されます）。条件が満たされると、server_name_filters は（CONNACK パケットの MCP-SERVER-NAME-FILTERS ユーザープロパティによって）MCP クライアントに送信されます。

MCP クライアントにサーバー名フィルターを設定すると、MCP Gateway は MCP クライアントがサーバー名フィルターに一致する MQTT トピックにのみアクセスできるよう、ACL を自動的に設定します。

ロールベースのアクセス制御（RBAC）

MCP Gateway は、MCP サーバーおよびそのツール／リソースへのアクセスを管理するために、ロールベースのアクセス制御（RBAC）をサポートしています。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 クライアントがブローカーに接続すると、MCP Gateway は条件を評価し、CONNACK パケットの MCP-RBAC ユーザープロパティを MCP クライアントに送信します。

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 サーバーをセットアップする

ドキュメントに従って、プラグインをビルドしてインストールします。