❓ FAQ

🌐 Q: 왜 로컬 OpenAPI 도구 서버가 WebUI 인터페이스에서 접근할 수 없나요?

A: 도구 서버가 로컬에서 실행 중이라면(e.g. http://localhost:8000), 브라우저 기반 클라이언트는 CORS(Cross-Origin Resource Sharing) 정책 때문에 접근이 제한될 수 있습니다.

OpenAPI 서버에서 CORS 헤더를 명시적으로 활성화해야 합니다. 예를 들어 FastAPI를 사용 중이라면 다음과 같은 코드를 추가할 수 있습니다:

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # 또는 클라이언트 출처를 지정
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

또한, Open WebUI가 HTTPS(e.g. https://yourdomain.com)를 통해 제공된다면, 로컬 서버는 다음 조건 중 하나를 충족해야 합니다:

• HTTPS를 사용하여 동일한 도메인에서 접근 가능해야 합니다(e.g. https://localhost:8000).
• 또는, 로컬 개발을 위해 브라우저에서 보안 완화를 허용할 수 있는 localhost(127.0.0.1)에서 실행되어야 합니다.
• 그렇지 않으면 브라우저는 혼합 콘텐츠 규칙으로 인해 HTTPS 페이지에서 HTTP API로의 비보안 요청을 차단할 수 있습니다.

운영 중인 HTTPS 환경에서 안전하게 작동하려면 OpenAPI 서버도 HTTPS를 통해 제공되어야 합니다.

---

🚀 Q: 서버 구현에 FastAPI를 반드시 사용해야 하나요?

A: 그렇지 않습니다! 참조 구현은 명확성과 사용 편의를 위해 FastAPI로 작성되었지만, 유효한 OpenAPI(Swagger) 명세를 생성하는 모든 프레임워크나 언어를 사용할 수 있습니다. 일반적인 선택지는 다음과 같습니다:

• FastAPI (Python)
• Flask + Flask-RESTX (Python)
• Express + Swagger UI (JavaScript/Node)
• Spring Boot (Java)
• Go with Swag or Echo

핵심은 서버가 유효한 OpenAPI 스키마를 제공하고 HTTP(S)로 통신한다는 점입니다. 모든 엔드포인트에 대해 사용자 정의 operationId를 설정하는 것이 중요합니다.

---

🚀 Q: OpenAPI를 MCP 대신 선택해야 하는 이유는 무엇인가요?

A: OpenAPI는 간단함, 도구 생태계, 안정성 및 개발자 친화성 덕분에 대부분의 실제 시나리오에서 MCP보다 우위를 점합니다. 이유는 다음과 같습니다:

• ✅ 기존 코드를 재사용할 수 있음: REST API를 이미 구축한 경우 대부분의 작업이 완료된 상태입니다. 로직을 다시 작성할 필요 없이, 준수하는 OpenAPI 규격을 정의하고 현재 코드를 도구 서버로 노출하기만 하면 됩니다.

  MCP는 사용자 지정 프로토콜 계층 내에서 도구 로직을 다시 구현해야 했으며, 이는 작업 중복과 유지 관리 부담을 증가시켰습니다.

• 💼 유지 관리 및 디버깅 부담 감소: OpenAPI는 현대적 개발 워크플로우에 자연스럽게 적응합니다. Postman으로 엔드포인트를 테스트하고, 내장된 API로 로그를 점검하며, 성숙한 생태계 도구를 사용하여 가급적 주요 앱을 수정하지 않고도 문제를 해결할 수 있습니다.

  MCP는 운송 계층, 스키마 파싱, 런타임 이상 동작 등 새로운 계층을 도입했으며, 이 모든 것을 수동으로 디버깅해야 했습니다.

• 🌍 표준 기반: OpenAPI는 기술 업계 전반에서 널리 채택되었습니다. 잘 정의된 구조로 인해 도구, 에이전트, 서버가 특별한 브리지나 변환 없이 즉시 상호 운용 가능합니다.

• 🧰 더 나은 도구 지원: OpenAPI를 지원하는 도구의 방대한 생태계가 있습니다—클라이언트/서버 자동 생성, 문서화, 검증, 목킹, 테스트 및 보안 감사 도구까지 포함됩니다.

• 🔐 일류 보안 지원: OpenAPI는 OAuth2, JWT, API 키, HTTPS 같은 항목에 대한 기본 지원을 포함하며, 공통 라이브러리와 표준을 사용하여 보안 엔드포인트를 더 쉽게 구축할 수 있습니다.

• 🧠 더 많은 개발자가 이미 알고 있음: OpenAPI를 사용하면 백엔드 팀, 프론트엔드 개발자, DevOps 및 제품 엔지니어에게 익숙한 언어를 사용하는 것입니다. 학습 곡선이나 높은 온보딩 비용이 필요하지 않습니다.

• 🔄 미래 지향적이고 확장 가능: OpenAPI는 API 표준과 함께 발전하며, 전방위 호환성을 유지합니다. 이에 반해 MCP는 특수 제작되고 실험적이어서 주변 생태계가 변화할 때 수정이 필요했습니다.

🧵 결론: OpenAPI는 더 적은 노력으로 더 많은 작업을 처리할 수 있도록 하며, 코드 중복과 놀라움을 줄입니다. 처음부터 모든 것을 다시 구축하지 않고도, LLM 도구를 실행하기에 적합한 생산 준비 완료 상태의 개발자 친화적인 경로를 제공합니다.

---

🔐 Q: OpenAPI 도구 서버를 어떻게 보안 처리하나요?

A: OpenAPI는 다음과 같은 산업 표준 보안 메커니즘을 지원합니다:

• OAuth 2.0
• API 키 헤더
• JWT(JSON Web Token)
• 기본 인증

데이터 전송을 암호화하기 위해 프로덕션 환경에서는 HTTPS를 사용하고, 적절한 인증/인가(auth/authz) 방법으로 엔드포인트를 제한하세요. 이는 OpenAPI 스키마에서 securitySchemes 필드를 사용하여 직접 통합할 수 있습니다.

---

❓ Q: OpenAPI 도구 서버를 사용하여 어떤 종류의 도구를 만들 수 있나요?

A: REST API를 통해 노출할 수 있다면 무엇이든 구축할 수 있습니다. 일반적인 도구 유형은 다음과 같습니다:

• 파일 시스템 작업(파일 읽기/쓰기, 디렉토리 목록)
• Git 및 문서 저장소 액세스
• 데이터베이스 쿼리 또는 스키마 탐색
• 웹 스크랩 또는 요약
• 외부 SaaS 통합(e.g., Salesforce, Jira, Slack)
• LLM 연결 메모리 스토어 / RAG 컴포넌트
• 에이전트가 노출된 내부 마이크로서비스를 보호

---

🔌 질문: 여러 도구 서버를 동시에 실행할 수 있나요?

답변: 물론입니다. 각 도구 서버는 독립적으로 실행되며 자체 OpenAPI 스키마를 노출합니다. 에이전트 구성은 여러 도구 서버를 가리킬 수 있어 필요에 맞게 혼합 및 활용이 가능합니다.

서버마다 자체 포트나 주소에서 실행되며 에이전트 호스트에서 접근 가능하도록 설정되어야 합니다.

---

🧪 질문: LLM 에이전트에 연결하기 전에 도구 서버를 테스트하려면 어떻게 하나요?

답변: OpenAPI 도구 서버를 테스트할 때 다음을 사용할 수 있습니다:

• Swagger UI 또는 ReDoc (기본적으로 FastAPI에 내장됨)
• Postman 또는 Insomnia
• 명령줄에서 curl 또는 httpie
• Python의 requests 모듈
• OpenAPI validator 및 mocker

검증이 완료되면 도구 서버를 LLM 에이전트 또는 Open WebUI를 통해 등록할 수 있습니다.

---

🛠️ 질문: 참조 서버를 확장하거나 사용자 정의할 수 있나요?

답변: 예! servers/ 디렉터리에 있는 모든 서버는 간단한 템플릿으로 만들어졌습니다. 이를 포크 및 수정하여 다음과 같은 작업을 수행할 수 있습니다:

• 새로운 엔드포인트 및 비즈니스 로직 추가
• 인증 통합
• 응답 형식 변경
• 새로운 서비스나 내부 API 연결
• Docker, Kubernetes, 클라우드 호스트를 통한 배포

---

🌍 질문: AWS나 GCP와 같은 클라우드 플랫폼에서 OpenAPI 도구 서버를 실행할 수 있나요?

답변: 가능합니다. 이 서버는 표준 HTTP 서비스로, 다음과 같은 방식으로 배포할 수 있습니다:

• API 게이트웨이와 함께 AWS Lambda (서버리스)
• EC2 또는 GCP Compute Engine 인스턴스
• GKE/EKS/AKS의 Kubernetes 서비스
• Cloud Run 또는 App Engine
• Render, Railway, Heroku 등

에이전트나 사용자가 필요로 할 때 서버가 안전하게 설정되고 공개적으로 접근 가능하거나(VPN) 보안이 확보된 상태여야 합니다.

---

🧪 질문: 기존 MCP 서버가 있는 경우 어떻게 하나요?

답변: 좋은 소식입니다! MCP-to-OpenAPI 브릿지 mcpo를 사용하면 기존 MCP 기반 도구를 OpenAPI 호환 API로 변환하는 작업이 더욱 간단해졌습니다. 코드 재작성 없이 빠르고 간단하게 설정할 수 있습니다. 🚀

이미 MCP 프로토콜을 사용하여 도구를 구축한 경우 mcpo는 Open WebUI 및 모든 OpenAPI 기반 에이전트를 통해 도구를 즉시 활용 가능하도록 도와줍니다. 이를 통해 작업 결과를 유지하며 미래를 대비할 수 있습니다.

설치 지침은 문서의 MCP 브릿지 선택 섹션을 확인하세요.

빠른 시작:

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

✨ 이제 MCP 서버가 OpenAPI 준비가 완료되었습니다!

---

🗂️ 질문: 하나의 OpenAPI 서버에서 여러 도구를 구현할 수 있나요?

답변: 가능합니다. 단일 OpenAPI 서버는 여러 관련 기능을 각기 다른 엔드포인트로 그룹화하여 제공할 수 있습니다. 예를 들어, 문서 서버는 검색, 업로드, OCR, 요약 기능을 하나의 스키마 내에서 제공할 수 있습니다.

완전히 모듈화를 원할 경우, 도구별로 분리하여 개별 OpenAPI 서버를 생성하는 것도 가능합니다.

---

🙋 추가 질문이 있으신가요? GitHub 디스커션을 방문하여 커뮤니티에서 도움과 피드백을 받아보세요:
👉 커뮤니티 디스커션