mcpo (MCP-to-OpenAPI)

为什么要用

核心特性

即插即用：任意 stdio MCP 转为 HTTP + OpenAPI
自动生成 /docs Swagger UI
工具输入和输出的 JSON Schema
支持 OAuth（客户端凭据 + JWT）
在单个进程中运行多个封装好的 MCP
轻量 Python（FastAPI），Apache 2.0

实时演示

实际使用效果

mcpo-openapi-mcp.replay ▶ 就绪

0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcpo-openapi-mcp": {
      "command": "uvx",
      "args": [
        "mcpo",
        "--",
        "uvx",
        "mcp-server-time"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcpo-openapi-mcp": {
      "command": "uvx",
      "args": [
        "mcpo",
        "--",
        "uvx",
        "mcp-server-time"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcpo-openapi-mcp": {
      "command": "uvx",
      "args": [
        "mcpo",
        "--",
        "uvx",
        "mcp-server-time"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标，然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcpo-openapi-mcp": {
      "command": "uvx",
      "args": [
        "mcpo",
        "--",
        "uvx",
        "mcp-server-time"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcpo-openapi-mcp",
      "command": "uvx",
      "args": [
        "mcpo",
        "--",
        "uvx",
        "mcp-server-time"
      ]
    }
  ]
}

Continue 使用服务器对象数组，而非映射。

~/.config/zed/settings.json

{
  "context_servers": {
    "mcpo-openapi-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "mcpo",
          "--",
          "uvx",
          "mcp-server-time"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add mcpo-openapi-mcp -- uvx mcpo -- uvx mcp-server-time

一行命令搞定。用 claude mcp list 验证，claude mcp remove 卸载。

使用场景

实战用法： mcpo (MCP-to-OpenAPI)

如何从 curl / Postman / OpenAI function-calling 调用 MCP 服务器

👤 运行时还不支持 MCP 的后端开发者 ⏱ ~15 min intermediate

何时使用： 你选了一个很好的 MCP 服务器，但生产栈是 Python 服务 / OpenAI Assistants API / 需要 HTTP+JSON 的东西。

前置条件

一个通常会直接启动的 MCP 命令 — 例如 uvx mcp-server-time 或 npx -y @modelcontextprotocol/server-fetch

步骤

封装

Run uvx mcpo --port 8000 -- uvx mcp-server-time and confirm /docs is up.✓ 已复制

→ Swagger UI 将工具显示为端点
用 curl 调用

Show me a working curl that calls the time tool with timezone=America/Los_Angeles.✓ 已复制

→ 返回当前时间 + 时区信息
接入 OpenAI

Generate a function-calling spec from /openapi.json that I can paste into the OpenAI API.✓ 已复制

→ spec 已生成；快速测试调用成功

结果： 一个非 MCP 后端可以通过 HTTP 驱动的 MCP 服务器。

注意事项

长时间运行的工具在默认 uvicorn 设置下超时 — 向 mcpo 传入 --timeout-keep-alive 600，或在前面加一层超时设置匹配的 nginx

在单个 HTTP 服务中运行多个 MCP

👤 整合多个 MCP 的平台工程师 ⏱ ~30 min intermediate

何时使用： 你希望用一个 URL 托管时间、fetch 和 filesystem 三个 MCP，各自挂载在独立的路径前缀下。

步骤

组合配置

Write the mcpo config for 3 servers — time at /time, fetch at /fetch, filesystem at /fs.✓ 已复制

→ config.yaml 包含 3 个服务；mcpo 提供服务
添加 OAuth

Configure JWT auth via the issuer of my Auth0 tenant. Endpoints require a valid token.✓ 已复制

→ 不带 token 的调用返回 401

结果： 一个托管多个 MCP 的单一安全 HTTP 入口。

注意事项

两个服务器暴露了同名工具 — mcpo 按前缀命名空间；工具冲突通过 URL 路径解决

在 HTTP 集成测试套件中使用 MCP

👤 QA 工程师 / SDET ⏱ ~25 min advanced

何时使用： 你希望用标准 HTTP 测试工具来断言 MCP 服务器的行为。

步骤

在 CI 中启动

Add a GitHub Actions job that runs mcpo wrapping our MCP, then runs Playwright/pytest against it.✓ 已复制

→ 工作流文件已写入；本地通过
schema 断言

Snapshot /openapi.json. Fail the build if the schema changes without an explicit change in the source.✓ 已复制

→ CI 中的 schema 差异守卫

结果： 标准 HTTP 测试流水线应用于 MCP 服务器。

注意事项

如果底层 MCP 启动时导入了大量依赖，测试会不稳定 — 测试运行前添加 /healthz 等待循环

搭配使用： github

组合

与其他 MCP 搭配，撬动十倍杠杆

mcpo-openapi-mcp + filesystem

将生成的 /openapi.json 持久化到仓库以便评审

Save current /openapi.json to /api/contracts/$(date +%F).json.✓ 已复制

mcpo-openapi-mcp + github

OpenAPI spec 变更时自动开 PR

If the snapshot diff is non-empty, open a PR titled 'OpenAPI changed'.✓ 已复制

工具

此 MCP 暴露的能力

工具	输入参数	何时调用	成本
GET /docs	（浏览器访问）	可视化探索工具接口	免费
GET /openapi.json	（无）	代码生成 / function-calling 规范	免费
POST /<tool>	符合工具输入 schema 的 JSON 请求体	通过 HTTP 调用封装好的 MCP 工具	1 次底层 MCP 调用

成本与限制

运行它的成本

API 配额: 取决于被封装 MCP 的配额
每次调用 Token 数: 约增加 50 token 开销
费用: 免费（Apache 2.0）
提示: 每个进程封装一次；不要为每个请求生成新子进程

安全

权限、密钥、影响范围

凭据存储： 通过环境变量透传给被封装的 MCP；mcpo 本身不存储任何内容

数据出站： 与被封装 MCP 的出站行为相同

默认部署无需认证——务必放在 OAuth 或私有网络之后

故障排查

常见错误与修复

/tool 返回 404

URL 中的工具名必须与 MCP 工具名完全匹配（区分大小写）

验证： 查看 /docs 确认正确路径

底层 MCP 崩溃

mcpo 默认会重启，但会记录错误——检查 stderr

有效 token 返回 OAuth 401

检查 audience 和 issuer 是否与配置匹配；常见错误是末尾斜杠缺失

验证： 在 jwt.io 解码 JWT 并对比 aud/iss

替代方案