Horizons MCP Gateway

关键词

JSON-RPC网关多租户远程调用微服务路由

使用说明（Markdown 格式）

  • 项目简介

    • Horizons 中的 MCP 网关模块负责对外暴露 MCP 请求的入口，能够将来自 LLM 客户端的请求通过 JSON-RPC 2.0 的格式传输并路由到后端的一个或多个 MCP 服务器实例，支持 stdio 和 HTTP 传输方式。

  • 主要功能点

    • 支撑 MCP 的基本请求：工具列表查询、调用工具等，并通过统一网关对外暴露。
    • 多传输协议支持：stdio（通过子进程的 JSON-RPC 2.0）以及 HTTP（JSON-RPC 请求转发到远端服务器）。
    • 多服务器路由：可配置一组 MCP 服务器，网关根据请求名称进行前缀路由，支持前缀式服务器名分发。
    • 身份与作用域校验（RBAC/作用域接口）: 通过 McpScopeProvider 对调用进行作用域检查，尽管当前实现包含基础通路，具体权限控制可在下游实现中扩展。
    • 配置化管理：支持动态重新配置 MCP 服务器集合（reconfigure），并对旧的服务器进行优雅关停。
    • 同步工具发现：聚合已配置服务器的工具清单，返回形式统一，便于客户端按需调用。

  • 安装步骤

    • 编译与运行：在包含 horizons_server 的工作流中构建并运行 Horizons 服务，服务端会自动暴露 MCP 相关的 HTTP 路由供 MCP 客户端调用。
    • 运行示例（高层次描述，实际命令以项目构建产物为准）：
      • cargo build --release
      • Horizons 服务器启动后，通常通过 horizons_server serve 启动 MCP 相关路由（具体路由见 README 中的接口列表，例如 /api/v1/mcp/config、/api/v1/mcp/tools、/api/v1/mcp/call）。

  • 服务器配置（MCP 网关配置用于 MCP 客户端说明）

    • MCP 客户端需要的配置信息主要来自网关端，而网关自身需要知道被代理的 MCP 服务器信息。以下 JSON 配置示例用于网关配置，描述了一个本地_stdio 后端和一个远端 HTTP 后端的搭建方式。配置格式遵循代码实现的结构：server name、transport、command/args 等字段。请注意，客户端在实际接入时并不需要此配置，而是由服务器端在部署时加载配置。
    • 配置示例（JSON） [ { "name": "mcp_server_stdio", "transport": { "type": "stdio", "command": "/path/to/mcp_server_stdio_binary", "args": ["--config", "dev"], "env": { "ENVIRONMENT": "development" } } }, { "name": "mcp_server_http", "transport": { "type": "http", "url": "http://localhost:4011", "headers": { "Authorization": "Bearer your_api_key_here" }, "call_path": "/call" } } ]
    • 说明
      • 第一个条目采用标准输入输出的 MCP 服务，将由网关通过 JSON-RPC 与之通信。command 指定可执行的 MCP 实例路径，args 为启动参数，env 为环境变量。
      • 第二个条目通过 HTTP 访问远端 MCP 服务，endpoint 使用 url，与子服务之间的通信遵循 HTTP JSON-RPC 2.0 协议，call_path 指定在 e.g. url/call 的路径执行 RPC 调用。
      • MCP 客户端（下游 LLM 客户端）不需要理解这些内部配置；它只需要通过网关暴露的 API 进行工具调用等。
    • 端点简述
      • /POST api/v1/mcp/config：配置 MCP 网关的后端服务器集合（stdio/http），网关将据此进行路由。
      • /GET api/v1/mcp/tools：列出网关可用的工具（来自已配置的后端 MCP 服务器）。
      • /POST api/v1/mcp/call：向指定工具发起调用，网关对请求进行身份校验、路由与返回结果。

  • 基本使用方法

    • 启动后端 MCP 网关并配置子 MCP 服务器：
      • 将上述配置写入网关的配置文件，启动网关服务。
      • 使用工具查询工具列表，调用需要的工具。
    • 常见工作流：
      • 客户端请求网关获取工具列表；
      • 客户端请求调用某个工具，网关将请求转发至对应的子 MCP 服务器；
      • 子 MCP 服务器返回执行结果，网关再将结果包装成统一的 MCP 响应返回给客户端。
    • 多租户与鉴权：
      • MCP 网关支持按租户隔离的访问控制，默认通过 Bearer API Key 做身份识别（参照 README 段落的说明）。在实际环境中，请为每个租户配置独立的访问凭据，确保访问控制能够隔离跨租户的请求。

  • 运行与部署提示

    • 如需在本地快速验证，可以将一个子 MCP 服务器做成一个简单的本地进程，配置 stdio 的命令路径指向该进程；另一端可使用一个本地 HTTP 模拟端点作为远端 MCP 服务器。
    • 监控与扩展：Horizons 提供了多种传输与监控接口，结合现有的 Observability、Audit 与 RBAC 框架，可以对 MCP 流量进行监控与审计。

  • 重要提醒

    • MCP 网关作为服务端的一部分，主要职责是将 MCP 客户端请求转发到后端 MCP 服务器，属于 MCP 服务器生态的一环，具备完整的路由、配置、工具发现等能力。
    • 客户端只关心对网关暴露的 MCP 接口的正确使用，不需要直接了解后端 MCP 服务器的实现细节。

服务器信息

访问项目