🛰️ MCP 지원

이 문서는 Open WebUI에서 제공하는 MCP (Model Context Protocol)-to-OpenAPI 프록시 서버 (mcpo)를 간단히 설정하고 배포하는 방법을 설명합니다. MCP 기반 툴 서버를 최종 사용자와 개발자에게 적합한 표준 OpenAPI 엔드포인트로 쉽게 노출시키는 방법을 배울 수 있습니다.

📌 MCP 프록시 서버란 무엇인가요?

MCP-to-OpenAPI 프록시 서버는 MCP (Model Context Protocol)로 구현된 툴 서버를 표준 REST/OpenAPI API를 통해 직접 사용할 수 있도록 합니다—복잡하거나 익숙하지 않은 커스텀 프로토콜을 관리할 필요가 없습니다. 최종 사용자나 애플리케이션 개발자라면 강력한 MCP 기반 도구에 REST와 같은 친숙한 엔드포인트를 사용하여 쉽게 상호작용할 수 있습니다.

💡 왜 mcpo를 사용해야 하나요?

MCP 툴 서버는 강력하고 유연하지만, 일반적으로 표준 입력/출력(stdio)으로 통신합니다—이는 종종 로컬 머신에서 실행되며 파일 시스템, 환경 및 기타 네이티브 시스템 기능에 쉽게 접근할 수 있습니다.

이 점은 강점이지만, 동시에 제한이 되기도 합니다.

주요 인터페이스(예: Open WebUI)를 클라우드에 배포하려는 경우 문제가 발생합니다: 클라우드 인스턴스는 로컬 머신에서 stdio를 통해 실행 중인 MCP 서버와 직접 통신할 수 없습니다.

이 문제를 mcpo가 획기적으로 해결합니다.

MCP 서버는 일반적으로 raw stdio 통신에 의존합니다. 이는:

• 🔓 환경 간에 본질적으로 보안이 부족함
• ❌ 대부분의 현대 도구, UI 또는 플랫폼과 호환되지 않음
• 🧩 인증, 문서화, 오류 처리와 같은 중요한 기능 부족

mcpo 프록시는 이러한 문제를 자동으로 제거합니다:

• ✅ 기존 OpenAPI 도구, SDK, 클라이언트와 즉시 호환 가능
• 🛡 도구를 보안성, 확장성, 표준 기반 HTTP 엔드포인트로 래핑
• 🧠 모든 도구에 대해 인터랙티브한 OpenAPI 문서를 자동 생성, 설정 필요 없음
• 🔌 간단한 HTTP 사용—소켓 설정, 데몬 관리, 플랫폼별 glue code 불필요

따라서 처음에는 mcpo가 "단지 또 하나의 레이어"처럼 보일 수 있지만—실제로는 모든 것을 단순화하면서 다음과 같은 점을 제공합니다:

• 더 나은 통합 ✅
• 더 나은 보안 ✅
• 더 나은 확장성 ✅
• 더 만족스러운 개발자 및 사용자 ✅

✨ mcpo를 사용하면, 로컬 전용 AI 도구가 클라우드 준비 완료, UI 친화적, 즉시 상호운용 가능하게 됩니다—툴 서버 코드 한 줄도 변경하지 않고.

✅ 빠른 시작: 로컬에서 프록시 실행하기

가볍고 사용하기 쉬운 툴 mcpo를 사용하여 MCP-to-OpenAPI 프록시 서버를 실행하는 쉽게 간단한 방법은 다음과 같습니다 (GitHub 레포지토리):

1. 사전 준비물

   • pip이 설치된 Python 3.8+
   • MCP 호환 애플리케이션 (예: mcp-server-time)
   • (권장) uv을 설치하여 빠른 시작 및 설정 없이 간편한 사용.

2. mcpo 설치하기

uv를 사용하여 설치(권장):

uvx mcpo --port 8000 -- your_mcp_server_command

또는 pip을 사용하여 설치:

pip install mcpo
mcpo --port 8000 -- your_mcp_server_command

3. 🚀 프록시 서버 실행하기

MCP-to-OpenAPI 프록시 서버를 실행하려면 MCP 호환 툴 서버가 필요합니다. 아직 없으신 경우, MCP 커뮤니티에서 다양한 사용 가능한 MCP 서버 구현을 제공합니다.

✨ MCP 서버를 어디서 찾나요?

다음 레포지토리 예제에서 공식적으로 지원되는 MCP 서버를 발견할 수 있습니다:

• modelcontextprotocol/servers on GitHub

예를 들어, 인기 있는 Time MCP Server는 여기에 문서화되어 있으며, 이는 제공된 MCP 설정 내에서 README에 명확히 참조됩니다. README에서는 다음과 같이 명시하고 있습니다:

Claude 설정에 추가:

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

🔑 MCP 설정을 간단한 로컬 프록시 명령으로 변환:

권장 MCP 서버 (mcp-server-time)를 MCP-to-OpenAPI 프록시 (mcpo)를 통해 쉽게 실행할 수 있습니다:

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

이게 끝입니다! 이제 MCP-to-OpenAPI 프록시를 로컬에서 실행하여 강력한 MCP Time 서버를 다음과 같은 표준 OpenAPI 엔드포인트를 통해 노출합니다:

• 📖 인터랙티브한 OpenAPI 문서: http://localhost:8000/docs

공식 레포지토리에서 발견할 수 있는 다른 사용 가능한 MCP 구현의 MCP 서버 명령으로 uvx mcp-server-time --local-timezone=America/New_York를 자유롭게 대체하세요.

🤝 서버를 실행한 후 Open WebUI와 통합하려면 이 문서를 참조하세요.

🚀 생성된 API 액세스하기

시작하자마자 MCP 프록시(mcpo)는 자동으로:

• MCP 도구를 동적으로 검색하고 REST 엔드포인트를 생성합니다.
• 인터랙티브하고 사람이 읽을 수 있는 OpenAPI 문서를 아래에서 접근할 수 있도록 생성합니다:
  • http://localhost:8000/docs

선호하는 HTTP 클라이언트, AI 에이전트, 또는 기타 OpenAPI 도구를 통해 자동 생성된 API 엔드포인트를 직접 호출하세요.

📖 최종 사용자용 예제 워크플로우

위 서버 명령(uvx mcp-server-time)을 시작했다고 가정합시다:

• 로컬 API 문서인 http://localhost:8000/docs를 방문하세요.
• 생성된 엔드포인트(e.g. /get_current_time)를 선택하고 제공된 인터랙티브 폼을 사용하세요.
• "Execute"를 클릭하면 즉시 응답을 받을 수 있습니다.

복잡한 설정 없이, 즉시 사용 가능한 REST API를 제공합니다.

🚀 프로덕션에 배포하기 (예제)

mcpo를 사용한 MCP-to-OpenAPI 프록시를 배포하는 것은 간단합니다. Dockerize하고 클라우드 또는 VPS 솔루션에 쉽게 배포하는 방법을 알아보세요:

🐳 mcpo를 사용하여 프록시 서버 도커화하기

1. Dockerfile 예제

다음 Dockerfile을 배포 디렉토리 내에 작성하세요:

FROM python:3.11-slim
WORKDIR /app
RUN pip install mcpo uv
# 당신의 MCP 서버 명령으로 교체하세요; 예: uvx mcp-server-time
CMD ["uvx", "mcpo", "--host", "0.0.0.0", "--port", "8000", "--", "uvx", "mcp-server-time", "--local-timezone=America/New_York"]

2. 로컬에서 컨테이너 빌드 및 실행

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

3. 컨테이너 배포

DockerHub 또는 다른 레지스트리에 푸시하세요:

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

Docker Compose, Kubernetes YAML 매니페스트 또는 선호하는 클라우드 컨테이너 서비스(AWS ECS, Azure Container Instances, Render.com 또는 Heroku)를 사용하여 배포하세요.

✔️ 당신의 프로덕션 MCP 서버는 이제 REST API를 통해 손쉽게 이용 가능합니다!

🧑‍💻 기술적 세부사항과 배경

🍃 작동 방식 (기술적 요약)

• 동적 스키마 검색 및 엔드포인트: 서버가 시작될 때 프록시는 MCP 서버에 연결하여 사용 가능한 도구를 쿼리합니다. MCP 도구 스키마를 기반으로 자동으로 FastAPI 엔드포인트를 생성하여 간결하고 명확한 REST 엔드포인트를 작성합니다.

• OpenAPI 자동 문서화: 생성된 엔드포인트는 FastAPI의 내장된 Swagger UI(/docs)를 통해 문서화되고 제공됩니다. 추가 문서 작성이 필요 없습니다.

• 비동기식 및 높은 성능: 견고한 비동기 라이브러리로 구축되어 동시에 사용자에게 속도와 안정성을 보장합니다.

📚 속 내부:

• FastAPI (자동 라우팅 및 문서 생성)
• MCP 클라이언트 (표준 MCP 통합 및 스키마 검색)
• HTTP를 통한 표준 JSON (쉬운 통합)

⚡️ MCP-to-OpenAPI 프록시의 우월성

프록시 접근 방식을 통해 MCP 서버를 OpenAPI로 활용하는 것이 왜 훨씬 더 우월한지와 Open WebUI가 이를 적극적으로 지원하는 이유를 아래에서 확인하세요:

• 사용자 친화적이고 익숙한 인터페이스: HTTP REST 엔드포인트만 사용하며, 별도의 커스텀 클라이언트가 필요 없습니다.
• 즉각적인 통합: 수천 개의 기존 REST/OpenAPI 도구, SDK, 서비스와 즉시 호환됩니다.
• 강력하고 자동화된 문서화: 내장 Swagger UI 문서는 자동으로 생성되며 항상 정확하고 유지 관리됩니다.
• 새 프로토콜 부담 없음: MCP 특정 프로토콜 복잡성과 소켓 통신 문제를 직접 처리할 필요성을 없앱니다.
• 검증된 보안 및 안정성: HTTPS 전송, 표준 인증 방법(JWT, API 키), 견고한 비동기 라이브러리 및 FastAPI의 입증된 강건함을 활용합니다.
• 미래 대비: MCP 프록시는 안정적이고 표준적인 REST/OpenAPI 포맷을 사용하여 장기적인 커뮤니티 지원과 진화를 보장합니다.

🌟 결론: MCP-to-OpenAPI는 강력한 MCP 기반 AI 도구를 직관적이고 신뢰성과 확장 가능한 REST 엔드포인트를 통해 널리 접근 가능하게 만듭니다. Open WebUI는 이 최우수 접근법을 자랑스럽게 지원하고 권장합니다.

📢 커뮤니티 및 지원

• 질문, 제안 또는 기능 요청은 GitHub Issue tracker를 사용하거나 Community Discussions에 참여하세요.

성공적인 통합을 기원합니다! 🌟🚀