MCP 支持

本页说明如何部署并使用 OPL 数据空间提供的 MCP（Model Context Protocol）到 OpenAPI 的代理服务器 mcpo。借助它，你可以把基于 MCP 的工具服务器暴露成标准 OpenAPI 端点，更方便地接入到 OPL 数据空间、其他客户端或开发者工作流中。

信息

本页讲的是 mcpo，也就是 MCP-to-OpenAPI bridge。如果你要看 OPL 数据空间的原生 MCP 支持，请阅读 模型上下文协议（MCP）。

凭据持久化的关键配置

如果你在 OPL 数据空间里用 API Key 或 Auth Token 连接这个代理，必须在 OPL 数据空间的 Docker 配置中设置 WEBUI_SECRET_KEY。如果这个 key 发生变化，例如容器重启后重新生成， OPL 数据空间将无法解密已保存的工具凭据。

什么是 MCP Proxy Server

MCP-to-OpenAPI 代理让你可以通过标准 REST/OpenAPI API 使用 MCP 工具服务器，而不需要直接管理 MCP 的原始通信协议。对终端用户和应用开发者来说，这意味着：可以用熟悉的 HTTP 接口访问 MCP 工具，而不是去适配一套陌生的 stdio 协议。

为什么使用 mcpo

MCP 工具服务器通常通过 stdio 通信，并且经常直接运行在本机上，因此可以方便地访问本地文件系统、环境变量和其他系统能力。这很强大，但也有部署限制。

如果你的主界面，例如 OPL 数据空间，运行在云端，那么它通常没法直接通过 stdio 去和你本地的 MCP 服务器通信。

mcpo 的意义就在这里：

• 把 stdio 风格的 MCP 工具包装成标准 HTTP/OpenAPI 接口
• 自动生成交互式 OpenAPI 文档
• 提供更成熟的安全、错误处理和扩展路径
• 让“只能本地跑”的 MCP 工具更容易进入云部署和多客户端环境

它解决的几个核心问题：

• stdio 跨环境使用不方便，也不安全
• 大多数现代 UI、平台、SDK 更容易对接 HTTP/OpenAPI
• OpenAPI 更容易承载鉴权、文档、错误码和部署治理

因此，虽然表面上看像是“又加了一层代理”，但实际上它通常能显著简化接入复杂度，同时提升：

• 集成能力
• 安全性
• 可扩展性
• 开发者与用户体验

提示

事件支持：通过 mcpo 暴露的 MCP 工具，仍然可以使用 OPL 数据空间的 事件 REST 端点 发出状态更新或通知。 OPL 数据空间会自动附带 X-Open-WebUI-Chat-Id 和 X-Open-WebUI-Message-Id。但需要用户输入的交互事件仍然只支持原生 Python 工具。

快速开始：本地运行代理

前置要求

• Python 3.8+
• 一个 MCP 兼容的应用，例如 mcp-server-time
• 可选但推荐：安装 uv

安装 mcpo

推荐用 uv：

uvx mcpo --port 8000 -- your_mcp_server_command

或者用 pip：

pip install mcpo
mcpo --port 8000 -- your_mcp_server_command

启动代理服务

如果你还没有 MCP Server，可以先从官方示例仓库里找现成的：

• modelcontextprotocol/servers

例如官方的 Time MCP Server README 通常会给出一段 MCP 配置：

"mcpServers": {
  "time": {
    "command": "uvx",
    "args": ["mcp-server-time", "--local-timezone=America/New_York"]
  }
}

把它转换为本地 mcpo 启动命令非常直接：

uvx mcpo --port 8000 -- uvx mcp-server-time --local-timezone=America/New_York

启动后，你就得到一个本地 OpenAPI 服务：

• 交互式文档：http://localhost:8000/docs

之后可以把这个 URL 连接到 OPL 数据空间。

访问自动生成的 API

mcpo 启动后会自动：

• 动态发现 MCP 工具
• 生成对应的 REST endpoint
• 自动生成 /docs 文档页

你可以直接用 HTTP 客户端、AI agent 或 OpenAPI 兼容工具访问这些接口。

终端用户工作流示例

假设你用上面的命令启动了 Time Server：

1. 打开 http://localhost:8000/docs
2. 选择自动生成的某个接口，例如 /get_current_time
3. 点击 Execute
4. 立即得到返回结果

这就是最小化的 MCP-to-OpenAPI 使用路径。

生产部署示例

用 Docker 打包 mcpo

FROM python:3.11-slim
WORKDIR /app
RUN pip install mcpo uv

CMD ["uvx", "mcpo", "--host", "0.0.0.0", "--port", "8000", "--", "uvx", "mcp-server-time", "--local-timezone=America/New_York"]

构建并本地运行：

docker build -t mcp-proxy-server .
docker run -d -p 8000:8000 mcp-proxy-server

推送到镜像仓库：

docker tag mcp-proxy-server yourdockerusername/mcp-proxy-server:latest
docker push yourdockerusername/mcp-proxy-server:latest

之后可通过 Docker Compose、Kubernetes、ECS、Azure Container Instances、Render、Heroku 等方式部署。

技术原理

mcpo 在启动时会：

• 连接 MCP server，发现它暴露的工具 schema
• 基于 schema 自动生成 FastAPI endpoint
• 自动生成 Swagger UI 文档
• 用异步 HTTP 方式承接后续请求

技术栈核心通常包括：

• FastAPI
• MCP Client
• JSON over HTTP

为什么这种桥接方式更优

通过 mcpo 把 MCP 包装成 OpenAPI，在很多真实场景下更实用，原因包括：

• 对用户和开发者都更熟悉：直接使用 HTTP
• 可立即接入大量现成的 OpenAPI 工具、SDK 与平台
• 文档自动生成、自动维护
• 不必直接处理 MCP 协议与套接字细节
• 可以直接继承成熟的 HTTPS、JWT、API Key 等安全实践

一句话总结：MCP-to-OpenAPI 让强大的 MCP 工具可以用更直观、更稳定、更易扩展的 REST 方式被广泛访问。

社区与支持

• 有问题、建议或功能请求，可使用 GitHub Issues
• 也可以参与 Community Discussions