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 함수 호출에서 MCP 서버를 호출하는 방법

👤 런타임이 아직 MCP를 지원하지 않는 백엔드 개발자 ⏱ ~15 min intermediate

언제 쓸까: 훌륭한 MCP 서버를 골랐지만 프로덕션 스택이 HTTP+JSON을 원하는 Python 서비스 / OpenAI Assistants API일 때.

사전 조건

일반적으로 실행하는 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.✓ 복사됨

→ 스펙 생성됨; 빠른 테스트 호출 성공

결과: 비MCP 백엔드가 HTTP로 구동할 수 있는 MCP 서버.

함정

장시간 실행 도구가 기본 uvicorn 설정에서 타임아웃 — mcpo에 --timeout-keep-alive 600을 전달하거나 일치하는 타임아웃으로 nginx 앞에 두세요

단일 HTTP 서비스 뒤에 여러 MCP 실행

👤 많은 MCP를 통합하는 플랫폼 엔지니어 ⏱ ~30 min intermediate

언제 쓸까: 각자의 경로 접두사로 time, fetch, filesystem MCP를 호스팅하는 단일 URL을 원할 때.

흐름

구성

Write the mcpo config for 3 servers — time at /time, fetch at /fetch, filesystem at /fs.✓ 복사됨

→ 3개 서비스가 있는 config.yaml; mcpo가 서비스 제공
OAuth 추가

Configure JWT auth via the issuer of my Auth0 tenant. Endpoints require a valid token.✓ 복사됨

→ 토큰 없는 호출이 401 반환

결과: 많은 MCP를 호스팅하는 단일 보안 HTTP 진입점.

함정

2개 서버가 같은 이름의 도구를 노출할 때 충돌 — 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.✓ 복사됨

→ 워크플로 파일 작성됨; 로컬에서 통과
스키마 어설션

Snapshot /openapi.json. Fail the build if the schema changes without an explicit change in the source.✓ 복사됨

→ CI에 스키마 diff 가드 추가됨

결과: MCP 서버에 적용된 표준 HTTP 테스트 파이프라인.

함정

기본 MCP가 시작 시 무거운 의존성을 가져와 불안정해짐 — 테스트 실행 전 /healthz 대기 루프 추가

함께 쓰기: github

조합

다른 MCP와 조합해 10배 효율

mcpo-openapi-mcp + filesystem

검토를 위해 생성된 /openapi.json을 저장소에 유지

mcpo-openapi-mcp + github

OpenAPI 스펙 변경 시 PR 열기

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
GET /docs	(browser)	도구 표면을 시각적으로 탐색	free
GET /openapi.json	(none)	코드젠 / 함수 호출 스펙	free
POST /<tool>	JSON body matching tool input schema	HTTP로 감싼 MCP 도구 호출	1 underlying MCP call

비용 및 제한

운영 비용

API 쿼터: 감싼 MCP의 할당량에 따라 결정
호출당 토큰: 약 50 token 오버헤드 추가
금액: 무료 (Apache 2.0)
팁: 프로세스당 한 번만 감싸세요; 요청마다 새 서브프로세스를 생성하지 마세요

보안

권한, 시크릿, 파급범위

자격 증명 저장: 환경 변수를 통해 감싼 MCP로 전달; mcpo 자체는 아무것도 저장하지 않음

데이터 외부 송신: 감싼 MCP가 이그레스했을 곳과 동일

기본 배포는 인증 없음 — 항상 OAuth 또는 비공개 네트워크 뒤에 두세요

문제 해결

자주 발생하는 오류와 해결

/tool에서 404

URL의 도구 이름은 MCP 도구 이름과 정확히 일치해야 합니다 (대소문자 구분)

확인: /docs에서 올바른 경로 확인

기본 MCP 충돌

mcpo가 기본적으로 재시작하지만 오류를 로그에 기록합니다 — stderr 확인

유효한 토큰으로 OAuth 401

audience와 issuer가 설정과 일치하는지 확인하세요; 일반적인 실수는 후행 슬래시 누락

확인: jwt.io에서 JWT를 디코딩하여 aud/iss 비교

대안