mcpo (MCP-to-OpenAPI) — Сценарии использования, Установка & Живое демо

Зачем использовать

Ключевые функции

Drop-in: любой stdio MCP становится HTTP+OpenAPI
Автоматически генерируемый Swagger UI /docs
JSON Schema для входных и выходных данных инструментов
Поддержка OAuth (client credentials + 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 использует ту же схему mcpServers, что и Claude Desktop. Конфиг проекта приоритетнее глобального.

VS Code → Cline → MCP Servers → Edit

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

Щёлкните значок MCP Servers на боковой панели Cline, затем "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 использует массив объектов серверов, а не map.

~/.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)

Как вызвать MCP-сервер из curl / Postman / OpenAI function-calling

👤 Backend-разработчики, чья runtime-среда пока не поддерживает MCP ⏱ ~15 min intermediate

Когда использовать: Вы нашли отличный MCP-сервер, но ваш production-стек — 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.✓ Скопировано

→ Возвращает текущее время + информацию о tz
Подключить к OpenAI

Generate a function-calling spec from /openapi.json that I can paste into the OpenAI API.✓ Скопировано

→ Spec сгенерирован; быстрый тестовый вызов проходит

Итог: MCP-сервер, который backend без поддержки MCP может вызывать по HTTP.

Подводные камни

Долгие инструменты превышают timeout по умолчанию в uvicorn — Передайте --timeout-keep-alive 600 в mcpo, или поставьте nginx с соответствующими таймаутами

Несколько MCP за одним HTTP-сервисом

👤 Platform-инженеры, консолидирующие множество MCP ⏱ ~30 min intermediate

Когда использовать: Вы хотите один URL, где MCP для времени, fetch и filesystem живут каждый под своим путём.

Поток

Скомпоновать

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

Итог: Единая защищённая HTTP-точка входа для многих MCP.

Подводные камни

Два сервера предоставляют инструменты с одинаковым именем — mcpo задаёт пространство имён через URL-путь; конфликты инструментов разрешаются по нему

Использование MCP в HTTP-интеграционных тестах

👤 QA / SDET-команды ⏱ ~25 min advanced

Когда использовать: Вы хотите проверять поведение MCP-сервера стандартными HTTP-инструментами тестирования.

Поток

Запустить в CI

Add a GitHub Actions job that runs mcpo wrapping our MCP, then runs Playwright/pytest against it.✓ Скопировано

→ Workflow-файл написан; проходит локально
Утверждения схемы

Snapshot /openapi.json. Fail the build if the schema changes without an explicit change in the source.✓ Скопировано

→ Защита от изменений схемы добавлена в CI

Итог: Стандартный HTTP-пайплайн тестирования применён к MCP-серверу.

Подводные камни

Нестабильность при тяжёлых зависимостях MCP при старте — Добавьте цикл ожидания /healthz перед запуском тестов

Сочетать с: github

Комбинации

Сочетайте с другими MCP — эффект x10

mcpo-openapi-mcp + filesystem

Сохранять сгенерированный /openapi.json в репозитории для ревью

mcpo-openapi-mcp + github

Открывать PR при изменении OpenAPI-спецификации

Инструменты

Что предоставляет этот MCP

Инструмент	Входные данные	Когда вызывать	Стоимость
GET /docs	(браузер)	Визуально изучить поверхность инструментов	бесплатно
GET /openapi.json	(нет)	Кодогенерация / спецификации function-calling	бесплатно
POST /<tool>	JSON-тело, соответствующее входной схеме инструмента	Вызвать обёрнутый MCP-инструмент по HTTP	1 вызов нижележащего MCP

Стоимость и лимиты

Во что обходится

Квота API: Ограничен квотами обёрнутого MCP
Токенов на вызов: Добавляет ~50 токенов overhead
Деньги: Бесплатно (Apache 2.0)
Совет: Оборачивайте один раз на процесс; не создавайте новый подпроцесс на каждый запрос

Безопасность

Права, секреты, радиус поражения

Хранение учётных данных: Передаётся в обёрнутый MCP через переменные среды; mcpo сам ничего не хранит

Исходящий трафик: Туда, куда бы уходил обёрнутый MCP

По умолчанию развёртывание без аутентификации — всегда ставьте за OAuth или в приватную сеть

Устранение неполадок

Частые ошибки и исправления

404 на /tool

Имя инструмента в URL должно точно совпадать с именем MCP-инструмента (с учётом регистра)

Проверить: Проверьте правильный путь в /docs

Нижележащий MCP упал

mcpo перезапускает по умолчанию, но логирует ошибку — проверьте stderr

OAuth 401 при валидном token

Проверьте, совпадают ли audience и issuer с конфигом; типичная ошибка — отсутствующий завершающий слэш

Проверить: Декодируйте JWT на jwt.io и сравните aud/iss

Альтернативы

mcpo (MCP-to-OpenAPI) в сравнении

Альтернатива	Когда использовать	Компромисс
sparfenyuk/mcp-proxy	Вам нужен только мост транспорта stdio↔HTTP, без OpenAPI-поверхности	mcp-proxy более низкоуровневый; mcpo даёт /docs и OAuth
Ручная FastAPI-обёртка	Вам нужна очень специфическая бизнес-логика рядом	mcpo даёт 90% бесплатно

Ещё

Ресурсы

📖 Читать официальный README на GitHub

🐙 Открытые задачи

🔍 Все 400+ MCP-серверов и Skills