Remote MCP Adapter

Remote MCP Adapter

远程 MCP 服务很棒，但工具一旦需要真实文件，情况就不同了。 将 MCP 服务放进 Docker、Kubernetes 或另一台机器后，本地文件路径就失去意义了。Remote MCP Adapter 位于中间，妥善处理文件上传和生成的文件，并提供在实际运行时通常需要的会话和工具界面防护措施。

---

问题所在

大多数 MCP 服务的设计都假设客户端与服务端共享文件系统。将服务移到 Docker、Kubernetes 或远程机器后，会立刻出现两个问题：

1. 文件输入失效。 工具收到客户端传来的本地路径，但服务端无法读取。
2. 文件输出失效。 工具在服务端生成截图或 PDF，但客户端无法取回。

Remote MCP Adapter 位于客户端和上游 MCP 服务之间。它能修复这些文件路径问题，而不会颠覆其余技术栈。

---

适用场景

• 你的 MCP 客户端和上游服务运行在不同机器或不同容器中
• 你的工具需要上传文件、截图、PDF、下载文件或其他依赖文件系统的功能
• 你希望在多个上游 MCP 服务前放置一个网关

不适用场景

• 客户端和上游服务已经安全地共享文件系统
• 上游工具完全不处理文件

---

用一个提示词验证

演示环境启动后，将 Agent 指向适配器并尝试：

Go to https://www.csm-testcenter.org/ and upload the readme of our repo there.
Take a screenshot for evidence and report back once done.
Also give me the download URL for the screenshot.

这会一次性走完整个故障路径：从客户端上传文件，在服务端使用该文件，在那里生成截图，然后将结果取回。没有适配器的话，这条链路通常会在中途某处断掉。

---

快速开始

Docker Compose（推荐）

仓库提供了一个 compose.yaml，可启动运行在 8931 端口的 Playwright MCP 和运行在 8932 端口的适配器。

git clone https://github.com/aakashH242/remote-mcp-adapter.git
cd remote-mcp-adapter
docker compose up --build

curl http://localhost:8932/healthz

从源代码安装

需要 Python 3.12+ 和 uv。

git clone https://github.com/aakashH242/remote-mcp-adapter.git
cd remote-mcp-adapter
uv sync
# config.local.yaml has upstream.url set to http://localhost:8931/mcp
uv run remote-mcp-adapter --config config.local.yaml

在第二个终端中启动 Playwright MCP（需要 Node.js）：

npx @playwright/mcp --headless --port 8931

---

连接你的 Agent

GitHub Copilot — 添加到 mcp.json：

{
  "servers": {
    "playwright": {
      "url": "http://localhost:8932/mcp/playwright",
      "type": "http"
    }
  }
}

OpenAI Codex — 添加到 config.toml：

[mcp_servers.playwright]
url = "http://localhost:8932/mcp/playwright"

Antigravity — 添加到 mcp_config.json：

{
  "mcpServers": {
    "playwright": {
      "serverUrl": "http://localhost:8932/mcp/playwright"
    }
  }
}

---

核心概念

功能	实现方式
暂存上传文件	创建 upload:// 句柄；在调用工具前重写路径
捕获产物	拦截文件输出；返回客户端可读取的 artifact:// 引用
安全代理	会话隔离、配额、运行状况检查、熔断器、TTL 清理
多服务中继	在一个网关下公开多个上游服务（/mcp/<server>）

生产环境与安全性

在超越本地演示、转向实际应用后，这些功能可增强运维能力。此适配器不仅是文件桥接工具，还提供了更安全的路由、更安全的模型可见工具元数据以及更安全的存储控制。

领域	功能
安全性	Bearer 令牌身份验证、一次性签名上传 URL、可选的签名产物下载
安全性	上传文件/产物的会话隔离，以及有状态请求的身份验证上下文绑定
安全性	清理可见工具文本中的元数据；可按策略保留、截断或移除描述
安全性	固定工具定义，以检测会话期间的偏移、架构变更和上游暗中撤换
可靠性	对不稳定的上游服务进行重试、重新连接和熔断
运维	根据部署架构使用内存、SQLite 或 Redis 支持的状态存储
运维	原子写入、孤立文件清理、配额限制、TTL 清理、安全存储边界
可观测性	OpenTelemetry 指标，并可选择导出日志
Agent 易用性	通过代码模式将工具界面简化为发现/执行流程
部署	Docker 镜像和已发布的 Kubernetes Helm 图表

---

工作原理

• 会话。 每个客户端连接都由 Mcp-Session-Id 标识。适配器会自动将上传文件、产物和配额限定到相应会话；启用适配器身份验证后，还会将有状态请求绑定到建立该会话时使用的相同适配器身份验证上下文。

• 上传句柄。 Agent 调用 <server_id>_get_upload_url(...)，通过 POST 上传文件，并获取 upload://sessions/<sid>/<upload_id> 句柄。适配器会在转发到上游服务前将其解析为真实路径。如果部署在反向代理、入口网关或负载均衡器后方，请在任何部署中设置 core.public_base_url，以确保返回的 URL 指向实际外部地址。

• 产物引用。 配置为产物生成器的工具写入文件时，适配器会捕获该文件，并返回 artifact://sessions/<sid>/<artifact_id>/<filename> URI。Agent 可对该 URI 调用 resources/read，以获取文件字节内容。

---

更新内容

v0.3.0 (03-16-2026)

• 现在，适配器对模型可见的工具元数据采用更安全的默认策略：
  • core.tool_metadata_sanitization.mode 现在默认为 sanitize
  • core.tool_definition_pinning.mode 现在默认为 warn
• 新增了工具定义固定和漂移检测功能。适配器现在可以固定会话中首次可见的工具目录、检测后续工具定义漂移，并根据策略选择发出警告、阻止操作或使会话失效。
• 新增了对模型可见的工具元数据清理功能，适用于工具标题、描述、注释标题和架构文本。在更严格的模式下，可以阻止元数据不规范的工具，而不是将其转发。
• 在 tool_description_policy 下新增了适用于所有工具的描述策略，包含 preserve、truncate 和 strip 模式。此策略同时适用于顶层工具描述和嵌套架构描述。
• 启用适配器身份验证后，有状态会话处理将更加严格。现在，会话会绑定到创建该会话的身份验证上下文，因此不能在不同的已验证上下文中使用复用的 Mcp-Session-Id。
• 扩展了安全文档，新增专门的文档章节，以及仓库根目录中的 SECURITY.md，概述已实施的控制措施和当前限制。

v0.2.0 (03-10-2026)

• 现在可以按服务器隐藏工具，方式是使用工具名称或正则表达式。在 servers[].disabled_tools 下设置。
• 可以全局或按服务器启用 代码模式。
• 可以使用 core.shorten_descriptions 或按服务器设置 shorten_descriptions，缩短上传使用者的工具描述。
• 新增用于部署的 Helm chart。

---

最小配置

servers:
  - id: "playwright"
    mount_path: "/mcp/playwright"
    upstream:
      url: "http://localhost:8931/mcp"

    adapters:
      - type: "upload_consumer"
        tools: ["browser_file_upload"]
        file_path_argument: "paths"

      - type: "artifact_producer"
        tools: ["browser_take_screenshot", "browser_pdf_save"]
        output_path_argument: "filename"
        output_locator:
          mode: "regex"

servers[] 是唯一必需的部分。其他所有内容都有安全的默认值。完整的 config.yaml.template 在各字段旁提供了说明。

---

部署说明

启用适配器后，适配器和上游服务必须共享一个目录，可以通过本地文件系统或网络存储实现。

根据你的环境，可以通过以下几种方式部署适配器：

• Docker Compose，用于本地端到端测试
• Docker 镜像，用于简单的容器部署
• Helm chart，通过已发布的 Helm 仓库部署到 Kubernetes

使用配置参考创建配置，确保上游服务正在运行，并确保适配器与上游服务共享由 storage.root 配置的存储路径。如果客户端会通过主机名、代理、入口或负载均衡器使用 <server_id>_get_upload_url(...) 或 HTTP 资源下载链接，请将 core.public_base_url 设置为该外部基础 URL。否则，适配器可能会生成仅在容器或 Pod 网络内部有效的 URL。

对于 Kubernetes，请使用已发布的 Helm 仓库：

• https://aakashh242.github.io/remote-mcp-adapter

这是 Helm 在执行 helm repo add 时需要的仓库 URL，因为这里是发布 index.yaml 的 GitHub Pages 根目录。如果你想检查或为源 chart 做贡献，可以查看 charts/remote-mcp-adapter，但该源目录并非面向最终用户的主要安装路径。

Helm 安装流程示例：

helm repo add remote-mcp-adapter https://aakashh242.github.io/remote-mcp-adapter
helm repo update
helm upgrade --install remote-mcp-adapter remote-mcp-adapter/remote-mcp-adapter \
  --namespace remote-mcp-adapter \
  --create-namespace \
  -f values.yaml

有关 Kubernetes 部署方式、覆盖模式和面向生产环境的示例，请参阅：

• 部署文档
• 使用 Helm 部署

如需直接部署容器，请拉取并运行镜像：

docker pull ghcr.io/aakashH242/remote-mcp-adapter:latest

docker run -d -v ./shared:/<your-path> -v ./config.yaml:/etc/remote-mcp-adapter/config.yaml -p 8932:8932 ghcr.io/aakashH242/remote-mcp-adapter:latest

---

文档

完整文档请参阅 MkDocs 网站：

页面	内容说明
快速入门	不到 5 分钟即可运行适配器
核心概念	会话、upload:// 句柄、artifact:// 引用
工作原理	工具分组、请求流程图
配置	附带示例的快速配置指南
配置参考	所有字段及默认值
部署	选择 Docker Compose 或 Helm 部署方式
使用 Helm 部署	Kubernetes 配置结构、覆盖项和安装流程
安全	身份验证、信任边界、漂移防护和运维态势
遥测	OpenTelemetry 指标目录
健康状态	/healthz 端点语义和示例载荷
故障排除	常见问题及解决方法

维护者可参阅仓库根目录下的 SECURITY.md，其中记录了已实施的安全控制和信任边界。

---

许可证

MIT