minibridge

Minibridge 充当 MCP 服务器与外部世界之间的桥梁。它 充当后端到前端的连接器，促进 代理和 MCP 服务器之间的通信。它允许安全地将 MCP 服务器暴露给互联网，并且 可以选择与通用策略服务无缝集成，以进行代理身份验证和内容分析。

Minibridge 不需要解释核心 MCP 协议，因为它只处理 数据流。这种设计确保了与未来 MCP 协议更改的前向兼容性。

目前，Minibridge 兼容任何使用协议的兼容 MCP 服务器 版本 2024-11-05。对 2025-03-26 版本的支持正在进行中。

注意：Minibridge 仍在积极开发中。

目录

<!-- vim-markdown-toc GFM -->

• All In One
• Backend
• Frontend
  • Stdio
  • HTTP+SSE
• Policer
  • Police Request API
  • Police Response API
  • Agent Authentication
    • Global
    • Forward
• Todos

<!-- vim-markdown-toc -->

All In One

Minibridge 可以充当位于标准 基于 stdio 的 MCP 服务器前面的单个网关。

要将所有内容作为单个进程启动，请运行：

minibridge aio --listen :8000 -- npx -y @modelcontextprotocol/server-filesystem /tmp

此命令在单个进程中启动前端和后端， 这在某些情况下可能很有用。

您可以使用 HTTP 客户端直接连接：

$ curl http://127.0.0.1:8000/sse
event: endpoint
data: /message?sessionId=UID

$ curl http://127.0.0.1:8000/message?sessionId=UID \
  -X POST \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

流程如下所示：

flowchart LR
    agent -- http+sse --> minibridge
    minibridge -- stdio --> mcpserver

为了保护连接，您需要为传入连接启用 HTTPS：

minibridge aio --listen :8443 \
  --tls-server-cert ./server-cert.pem \
  --tls-server-key ./server-key.pem \
  --tls-server-client-ca ./clients-ca.pem \
  -- npx -y @modelcontextprotocol/server-filesystem /tmp

这将启用 HTTPS，并且使用 --tls-server-client-ca，它要求客户端 发送由该客户端 CA 签名的证书。

您现在可以使用 HTTP 客户端直接连接：

$ curl https://127.0.0.1:8443/sse \
  --cacert ./server-cert.pem --cert ./client-cert.pem --key ./client-key.pem
event: endpoint
data: /message?sessionId=UID

$ curl https://127.0.0.1:8443/message?sessionId=UID \
  --cacert ./server-cert.pem --cert ./client-cert.pem --key ./client-key.pem \
  -X POST \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Backend

启动后端会启动一个 MCP 服务器，并通过 基于 WebSocket 的接口公开其 API。可以配置 TLS，无论是否使用客户端 证书，具体取决于您的安全要求。

例如，要启动一个基于文件系统的 MCP 服务器：

minibridge backend -- npx -y @modelcontextprotocol/server-filesystem /tmp

您现在可以使用 websocket 客户端直接连接：

wscat --connect ws://127.0.0.1:8000/ws

注意：如果您已使用 TLS 启动 minibridge 后端，请使用 wss 方案。

注意：目前，minibridge 后端仅支持基于 stdio 的 MCP 服务器。

流程如下所示：

flowchart LR
    agent -- websocket --> minibridge
    minibridge -- stdio --> mcpserver

为了保护连接，您需要为传入连接启用 HTTPS：

minibridge backend --listen :8443 \
  --tls-server-cert ./backend-server-cert.pem \
  --tls-server-key ./backend-server-key.pem \
  --tls-server-client-ca ./clients-ca.pem \
  -- npx -y @modelcontextprotocol/server-filesystem /tmp

这将启用 HTTPS，并且使用 --tls-server-client-ca，它要求客户端 发送由该客户端 CA 签名的证书。您现在可以使用以下命令连接：

wscat --connect wss://127.0.0.1:8443/ws \
  --ca ./server-cert.pem \
  --cert ./client-cert.pem

Frontend

虽然 WebSockets 解决了普通 POST+SSE 的许多限制，但它们尚未 成为官方 MCP 协议的一部分。为了保持与 现有代理的向后兼容性，前端可以使用 POST+SSE、 HTTP+STREAM（即将推出）或普通 STDIO 公开本地接口。然后，它将透明地将 数据通过 WebSockets 和 HTTPS 转发到 Minibridge 后端。

Stdio

要启动一个 stdio 前端：

minibridge frontend --backend wss://127.0.0.1:8000/ws

然后，您可以通过 stdin 发送请求，并从 stdout 读取响应。 前端维护与后端的单个 WebSocket 连接，并且将 在发生故障时自动重新连接。

流程如下所示：

flowchart LR
    agent -- stdio --> mb1[minibridge]
    mb1 -- websocket --> mb2[minibridge]
    mb2 -- stdio --> mcpserver

HTTP+SSE

要启动一个 SSE 前端：

minibridge frontend --listen :8081 --backend wss://127.0.0.1:8000/ws

在这种模式下，将为每个传入的 /sse 端点连接建立一个新的 WebSocket 连接到后端。这保留了会话状态。 但是，在这种模式下，WebSocket 不会尝试重新连接，并且任何 活动流将在发生网络故障时终止。

您可以使用 HTTP 客户端直接连接：

$ curl http://127.0.0.1:8001/sse
event: endpoint
data: /message?sessionId=UID

$ curl http://127.0.0.1:8001/message?sessionId=UID \
  -X POST \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

流程如下所示：

flowchart LR
    agent -- http+sse --> mb1[minibridge]
    mb1 -- websocket --> mb2[minibridge]
    mb2 -- stdio --> mcpserver

为了保护连接，您需要为传入连接启用 HTTPS：

minibridge frontend --listen :8444 \
  --backend wss://127.0.0.1:8000/ws
  --tls-server-cert ./server-cert.pem \
  --tls-server-key ./server-key.pem \
  --tls-server-client-ca client-ca.pem ]\
  --tls-client-cert ./client-cert.pem \
  --tls-client-key ./client-key.pem \
  --tls-client-backend-ca ./backend-server-cert.pem

这将启用 HTTPS，并且使用 --tls-server-client-ca，它要求客户端 发送由该客户端 CA 签名的证书。它还使前端使用提供的客户端证书（MTLS）向后端进行身份验证。

您现在可以使用 HTTP 客户端直接连接：

$ curl https://127.0.0.1:8444/sse \
  --cacert ./server-cert.pem --cert ./client-cert.pem --key ./client-key.pem
event: endpoint
data: /message?sessionId=UID

$ curl https://127.0.0.1:8444/message?sessionId=UID \
  --cacert ./server-cert.pem --cert ./client-cert.pem --key ./client-key.pem \
  -X POST \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Policer

虽然 Minibridge 已经提供了高级功能，例如强大的客户端 身份验证和原生 WebSocket 支持，但可以通过与 Policer 集成来进一步增强它。 Policer 负责：

• 身份验证
• 授权
• 输入分析和日志记录
• 完整请求跟踪
• 以及更高级的基于策略的控制

如果设置了 Policer，它将被调用并传递各种信息，以便它可以 根据发起请求的用户和请求的内容来决定如何处理请求。

注意：您可以在 policers/example 中找到 policer 的示例。

然后，您可以使用以下参数启动 Minibridge，使用 aio 或 backend 子命令：

minibridge aio --policer-url https://policer.acme.com/police --policer-token $PTOKEN

集成后，后端收到的来自用户的任何命令或来自 MCP 服务器的响应 首先传递给 Policer 进行身份验证和/或分析。

Police Request API

Policer 在 --policer-url 端点接收一个 POST 请求，格式如下：

{
  "type": "input"
  "token": "<agent-token>",
  "mcp": {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
  }
}

注意：对于来自 MCP 服务器的响应，type 将设置为 output 并且不会传递用户。

注意：minibrige --policer-token 将在发送到 policer 的 POST 请求的 Authorization 标头中传递。

Police Response API

如果请求通过了策略检查，Policer 必须以 HTTP 状态代码 200 OK 响应。 任何其他状态代码都将被视为失败，并且请求将被阻止。

对于允许请求的策略决策：

{
  "decision": "allow"
}

对于拒绝请求的策略结果：

{
  "decision": "deny",
  "reasons": ["You are not allowed to list the tools"]
}

如果请求被拒绝（或者 Policer 没有返回 200 OK），Minibridge 将不会将其转发到 MCP 服务器。相反，它将向客户端返回一个描述性的 MCP 错误，指示请求被阻止的原因。

示例：

$ mcptools tools http://127.0.0.1:8000
error: RPC error 451: request blocked: ForbiddenUser: You are not allowed to list the tools

Agent Authentication

前端可以使用两种模式转发代理凭据。

Global

此模式使用在 Minibridge 前端启动期间设置的单个令牌。 当桥只有一个用户时，它很有用——例如，当它在 用户的笔记本电脑上运行并连接到远程 Minibridge 后端时。

要以该模式启动前端：

minibridge frontend -l :8000 -A wss://backend.minibridge.acme.com/ws --agent-token "$TOKEN"

Forward

此模式只是将 HTTP Authorization 标头转发到 Minibridge 后端。当前端在公共网络上运行时，并且您希望 policer 验证多个调用者时，它很有用。

要以该模式启动前端：

minibridge frontend -l :8000 -A wss://backend.minibridge.acme.com/ws --agent-token-passthrough

Todos

Minibridge 仍然缺少以下功能：

• [ ] 单元测试
• [x] 通过 websocket 通道传输用户信息
• [x] 支持用户提取以传递给 policer
• [ ] 优化 aio 模式下前端/后端之间的通信
• [ ] 插入 prometheus 指标