BeigeBox MCP 服务器

关键词

模型上下文协议JSON-RPC工具注册表会话管理API 代理

使用说明（Markdown 格式）

项目简介

BeigeBox 内置的 MCP 服务器实现，使得客户端能够通过 MCP（Model Context Protocol）标准化地发现并调用 BeigeBox 的工具集合。服务器提供以下 MCP 方法：

  • initialize：握手并返回服务器能力信息
  • tools/list：列出可用工具及其输入描述
  • tools/call：按名称调用一个工具并返回结果

MCP 客户端通过 POST /mcp 发送符合 MCP 2.0 的 JSON-RPC 请求，服务器返回相应的 JSON-RPC 响应。该实现与 BeigeBox 的工具注册表对接，保证客户端能直接远程调用本地或后端提供的工具。

主要功能点

  • MCP 核心协议支持：完整处理 initialize、tools/list、tools/call 等 MCP 方法，以及对通知（无 id）的处理
  • 服务器端工具暴露：自动将 BeigeBox 注册的工具注册为 MCP 工具，供客户端查询与调用
  • JSON-RPC 交互：遵循 MCP 的 JSON-RPC 2.0 规则，返回统一的响应结构
  • 与现有 BeigeBox 框架整合：通过现有的工具注册表，确保 MCP 调用能触发相应的工具执行
  • 安全与鉴权（与现有 API 一致）：通过 BeigBox 的多钥匙鉴权体系控制访问（同 OpenAI 兼容端点的鉴权逻辑）

安装与运行（简要步骤）

  • 安装并运行 BeigBox 服务（MCP 服务作为 BEIGBOX 的一部分提供）
    • 常规启动方式：运行 BeigBox（如 docker-compose 或 python 启动脚本）并使用配置文件启动代理服务
    • 启动后 MCP 端点地址为 http://<服务器地址>/mcp
  • 启动后即可对 MCP 客户端进行调用，例如 Claude Desktop 等工具，通过 /mcp 端点与 BeigeBox 的工具注册表交互

注：BeigeBox 提供的 MCP 服务器是后端服务的一部分，与前端 UI、模型路由、工具执行等模块复用同一进程与鉴权逻辑，因此无需单独部署额外的 MCP 服务组件。

服务器配置（MCP 客户端启动信息 JSON 描述）

说明：以下为 MCP 客户端的启动配置示意，请以 JSON 形式理解；MCP 客户端需要知道服务器的启动命令与参数以便在需要时自动启动 MCP 服务。MCP 客户端本身不需要你在这里执行代码，仅用于理解如何接入 MCP 服务器。

{ "server": "beigebox", "command": "beigebox", "args": ["dial", "--host", "0.0.0.0", "--port", "1337"] } 注释：

  • server：标识 MCP 服务的服务器名称，这里对应 BeigeBox 的 MCP 服务
  • command：启动 MCP 服务所需的命令（在 BeigeBox 环境中实际通过 BeigBox 主服务启动）
  • args：启动命令的参数，包含服务器绑定地址和端口等信息
  • MCP 端点 URL 参考：MCP 调用地址通常为 http://<host>:<port>/mcp

基本使用方法

  • MCP 客户端通过 POST 请求向 http://<服务器>/mcp 发送 JSON-RPC 请求，格式遵循 MCP 2.0
  • 请求示例（调用工具列表示例，实际请使用真实工具名称）：
    • initialize：握手并获取服务器能力信息
    • tools/list：获取工具清单
    • tools/call：调用某个工具并传入输入参数
  • 客户端应在请求头中携带鉴权信息（如果启用鉴权），如 Authorization: Bearer <token>

注：BeigeBox 的 MCP 实现会自动暴露注册在工具 Registry 的所有工具，调用时通过 tools/call 指定工具名称及输入，服务器返回工具执行结果。

基本注意事项

  • MCP 仅暴露工具接口，不直接暴露资源实现的细节；工具执行的输入通过字符串文本传递（统一 input 字段）
  • MCP 客户端可通过 initialize 获得服务器能力、通过 tools/list 获取可用工具、通过 tools/call 调用具体工具
  • 服务器与客户端之间的通信遵循 JSON-RPC 2.0；同一请求的 id 标识请求/响应，通知类请求无 id
  • 与 BeigeBox 的现有鉴权机制一致，确保 MCP 接口具备与主接口一致的访问控制

如果你需要把 MCP 客户端直接接入 Claude Desktop，请参考项目提供的示例配置和文档链接，该 MCP 服务器实现已经就绪可用于实际生产环境。

服务器信息

访问项目