모델 컨텍스트 프로토콜(MCP)은 Anthropic에 의해 출시된 이후로 상당한 주목을 받고 있습니다. AI 통합 작업을 하는 개발자로서, 저는 API와 대규모 언어 모델(LLM)을 간편하게 연결할 수 있는 도구를 지속적으로 찾고 있습니다. Mintlify가 MCP 서버 생성기를 발표했을 때, 저는 흥미를 느꼈습니다. 문서에서 직접 MCP 서버를 생성하여 AI 지원 API 호출을 가능하게 하는 것은 게임 체인저처럼 들렸습니다. 하지만, 저와 같은 기능을 제공하는 대안인 Apidog와 비교하고 싶기도 했습니다.
이 리뷰에서는 Mintlify의 MCP 서버 생성기를 테스트한 경험을 깊이 있게 살펴보겠습니다. 설정, 기능 및 성능에 중점을 두고, 제가 API 워크플로를 디버깅하는 데 유용하다고 생각한 Apidog와 비교해 보겠습니다.
Mintlify MCP 서버 생성기란 무엇인가요?
Mintlify의 MCP 서버 생성기는 문서에서 직접 모델 컨텍스트 프로토콜(MCP) 서버를 생성하기 위해 설계된 도구입니다. MCP는 AI 모델이 GitHub, Slack 또는 귀하의 맞춤 API와 같은 외부 도구 및 데이터 소스와 상호 작용할 수 있도록 허용하는 표준화된 프로토콜입니다—각 연결에 대해 맞춤 통합이 필요하지 않습니다. Mintlify는 이를 활용하여 개발자가 OpenAPI 사양과 같은 기존 데이터 구조를 사용하여 MCP 서버를 생성할 수 있도록 합니다.
생성기는 세 가지 주요 시나리오를 간소화하는 것을 목표로 합니다:
- 문서에서 일반적인 검색 및 답변 검색.
- AI 응용 프로그램을 통한 실시간 API 쿼리 및 실행.
- LLM을 통해 제품 세부정보를 쿼리하는 사용자에 대한 맥락적 답변.
Mintlify는 이것을 API와 AI 생태계 간의 간극을 메우는 방법으로 홍보하여, 문서를 인간과 AI 에이전트 모두에게 더 접근 가능하게 만듭니다. 하지만 이 약속을 이행할까요? 제 테스트 과정을 자세히 살펴보겠습니다.
Mintlify MCP 서버 생성기 설정하기
먼저, MCP 서버 생성기를 설치하기 위해 Mintlify의 설치 가이드를 따랐습니다. 이 프로세스는 간단한 CLI 설치가 필요하며, 저는 npm을 사용하여 다음과 같이 실행했습니다:
npm install -g @mintlify/mcp-generator
설치 후, 저는 OpenAPI 사양 파일(openapi.yaml)이 포함된 프로젝트 디렉토리로 이동했습니다. Mintlify의 문서에 따르면, 생성기는 이 사양을 기반으로 동적으로 MCP 서버를 생성할 수 있다고 합니다. 다음 명령을 실행하여 서버를 생성했습니다:
mintlify mcp-generate --spec openapi.yaml
CLI는 생성된 MCP 서버 파일의 목적지를 선택하라는 메시지를 표시했습니다. 몇 초 만에 Node.js를 런타임 환경으로 사용하는 경량 서버 설정이 생성되었습니다. 생성된 서버에는 일반 검색, API 쿼리 및 작업 실행을 위한 엔드포인트가 포함되어 있으며, 이는 Mintlify가 명시한 사용 사례와 일치했습니다.
하지만 설정 중에 약간의 문제에 직면했습니다. 생성기는 Node.js 버전 18 이상을 가정했지만 제 시스템에는 버전 16이 설치되어 있었습니다. Node.js를 업그레이드한 후, 프로세스는 순조롭게 완료되었습니다. 이는 핵심 포인트를 강조합니다: 시작하기 전에 환경이 요구 사항을 충족하는지 확인하세요.
MCP 서버 테스트: API 통합 및 AI 상호작용
다음으로, 생성된 MCP 서버를 AI 클라이언트와 통합하여 테스트했습니다. 저는 Cursor라는 AI 기반 IDE를 사용하여 서버와 상호작용했습니다. Cursor는 MCP 클라이언트를 지원하여 프로토콜을 통해 검색하고 작업을 실행할 수 있도록 합니다. 제 목표는 두 가지 시나리오를 테스트하는 것이었습니다: 문서를 검색하고 API 호출을 실행하는 것입니다.
시나리오 1: 문서 검색
저는 Cursor에게 API 문서에서 특정 엔드포인트를 검색하라고 지시했습니다: “Foo API로 인증하는 방법은?” 로컬에서 실행 중인 MCP 서버는 http://localhost:3000에서, OpenAPI 사양에서 가져온 구조화된 답변으로 응답했습니다. 이 응답에는 인증 엔드포인트, 필요한 헤더 및 샘플 요청 본문이 포함되었습니다:
{
"endpoint": "/auth/login",
"method": "POST",
"headers": {
"Content-Type": "application/json"
},
"body": {
"username": "string",
"password": "string"
}
}
이것은 매끄럽게 작동했으며 응답 시간도 인상적이었습니다—200밀리초 이내였습니다. MCP 서버 생성기는 제 문서를 AI 응용 프로그램을 위한 검색 가능한 자원으로 효과적으로 변환했습니다.
시나리오 2: API 호출 실행
두 번째 테스트에서는 MCP 서버가 제 대신 API 호출을 실행할 수 있는지 확인하고 싶었습니다. 필요한 API 키로 Cursor를 인증한 후, “특정 충전 ID에 대해 Stripe 환불을 시작하세요.”라고 요청했습니다. MCP 서버는 요청을 처리하고 적절한 API 호출을 생성한 후 Stripe API를 사용하여 이를 실행했습니다. 응답은 환불을 확인했습니다:
{
"id": "re_1N5X7Y2eZvKYlo2C0X5Y7Z8",
"amount": 1000,
"status": "succeeded"
}
이 기능은 정보를 검색하는 것 뿐만 아니라 행동을 취할 수 있도록 해 주므로, 전통적인 문서에서 큰 향상입니다. 그러나 API 트래픽에 대한 상세한 로깅이 부족하여 문제가 발생했을 때 디버깅하기 어려운 점은 발견했습니다. 이는 Apidog가 뛰어난 점입니다. 나중에 이 부분에 대해 논의하겠습니다.
MCP 서버 생성기의 성능 및 확장성
기본 기능을 테스트한 후, 생성된 MCP 서버의 성능 및 확장성을 평가했습니다. 다른 엔드포인트를 쿼리하는 100개의 동시 요청을 시뮬레이션하기 위해 간단한 스크립트를 사용하여 부하 테스트를 수행했습니다. 서버는 평균 응답 시간이 250밀리초로 잘 처리되었으며, 충돌 없이 운영되었습니다.
하지만 동시 요청을 500개로 늘리자 응답 시간이 1.2초로 급증했으며, 서버는 가끔 503 오류를 반환했습니다. 이는 MCP 서버의 기본 구성이 고트래픽 시나리오에 최적화되지 않았음을 시사합니다. 이를 해결하기 위해, 작업자 스레드 수를 늘리도록 서버 구성을 수정했습니다:
const server = require('./mcp-server');
server.setWorkerThreads(4);
server.start();
이 조정으로 같은 부하에서 응답 시간이 800밀리초로 줄어들었지만, 여전히 MCP 서버 생성기가 프로덕션 환경을 위한 추가 최적화가 필요할 수 있음을 나타냅니다.
Mintlify MCP 서버 생성기와 Apidog 비교하기
Mintlify의 MCP 서버 생성기는 사용자 편의성으로 저에게 깊은 인상을 주었지만, MCP 서버 설정 및 API 테스트를 위해 사용해본 다른 도구인 Apidog와 비교하지 않을 수 없었습니다. Apidog는 API 사양과 직접 통합되는 MCP 서버 솔루션을 제공하며, Mintlify와 유사하지만 특정 시나리오에서 더 나은 대안이 될 수 있는 추가 기능을 제공합니다.
설정 및 구성
Apidog의 설정 과정은 Mintlify보다 약간 더 복잡하며, 데이터 소스를 정의하기 위한 Node.js 및 구성 파일이 필요합니다. 하지만 Apidog는 로컬 파일, 데이터베이스 및 원격 API를 포함한 여러 데이터 소스를 기본적으로 지원합니다. 반면에 Mintlify는 주로 OpenAPI 사양에 주력하여 유연성이 제한됩니다.
디버깅 및 가시성
Apidog가 Mintlify보다 뛰어난 분야는 디버깅입니다. Apidog는 MCP 서버와 Cursor와 같은 AI 클라이언트 간의 API 트래픽을 캡처하고 검사할 수 있도록 합니다. 예를 들어, Apidog의 MCP 서버로 동일한 Stripe 환불 시나리오를 테스트할 때 정확한 요청 페이로드와 응답을 확인할 수 있었습니다:
요청:
{
"charge": "ch_1N5X7Y2eZvKYlo2C0X5Y7Z8",
"amount": 1000
}
응답:
{
"id": "re_1N5X7Y2eZvKYlo2C0X5Y7Z8",
"amount": 1000,
"status": "succeeded"
}
이 수준의 가시성은 Mintlify 서버에서는 명확하지 않았던 인증 문제를 해결하는 데 도움이 되었습니다. Apidog가 API 사양을 로컬에 캐시하고 필요 시 새로 고칠 수 있도록 지원하는 것도 AI가 항상 최신 데이터를 사용할 수 있도록 보장합니다.
코드 생성 및 사용자 정의
Apidog는 API 사양에 따라 AI가 코드를 생성할 수 있도록 하여 MCP 서버 기능을 한 단계 발전시킵니다. 예를 들어, 저는 Apidog를 사용하여 “Product” 스키마에 대한 Java 레코드를 생성했습니다:
public record Product(String id, String name, double price) {}
Mintlify의 MCP 서버 생성기는 이 기능을 제공하지 않고, 검색 및 API 실행에 초점을 맞추고 있습니다. 이는 Mintlify가 문서 개선 목표에 부합하지만, Apidog의 더 폭넓은 기능 세트는 복잡한 AI 워크플로를 작업하는 개발자에게 더 유용합니다.
Apidog MCP 서버를 통해 AI와 Apidog에서 게시한 온라인 API 문서 연결하기
Apidog MCP 서버는 AI가 Apidog에서 게시한 온라인 API 문서에 연결하고 활용할 수 있게 해줍니다.
이 구성 방법은 공개적으로 게시된 온라인 문서만 지원하며, 비밀번호 또는 화이트리스트 설정가 있는 문서는 지원하지 않습니다. 비공식 문서의 경우, Apidog 프로젝트 데이터를 읽기 위해 프로젝트 ID와 개인 API 액세스 토큰을 사용하는 것이 권장됩니다. 자세한 내용은 Apidog 프로젝트 내 API 문서를 AI와 연결하기를 참조하십시오.
온라인 문서에 대한 MCP 활성화
구성을 활성화한 후, 온라인 문서에 접근할 때 Vibe Coding(via MCP) 버튼이 나타납니다.
버튼을 클릭하면 구성 가이드와 MCP 구성 파일이 표시되며, 문서의 site-id가 자동으로 포함됩니다. 이 구성을 IDE 통합을 위해 간단히 복사하십시오.
Cursor에서 MCP 구성 설정: MCP 구성 파일 수정하기Cursor 편집기를 열고, 설정 아이콘(오른쪽 상단)을 클릭한 후, 왼쪽 메뉴에서 "MCP"를 선택하고 "+ 새 전역 MCP 서버 추가"를 클릭하십시오.
구성 추가온라인 문서에서 복사한 MCP JSON 구성을 열려 있는 mcp.json 파일에 붙여넣습니다:macOS / LinuxWindows
{
"mcpServers": {
"apidog-site-123456": {
"command": "npx",
"args": [
"-y",
"apidog-mcp-server@latest",
"--site-id=123456"
]
}
}
}구성 확인연결을 테스트하기 위해 AI(에이전트 모드)에게 요청합니다, 예를 들어:
API 문서를 MCP를 통해 가져오고, 프로젝트에는 몇 개의 엔드포인트가 있는지 알려주세요.AI가 올바른 API 정보를 반환하면 연결이 성공적입니다.
중요 참고사항: 서로 다른 API 문서와 작업해야 하는 경우, 여러 MCP 서버 구성을 구성 파일에 간단히 추가하십시오.
각 API 문서에는 고유한 <site-id>가 있어야 합니다. 온프레미스 배포를 사용하는 경우, IDE MCP 구성에서 온프레미스 서버의 API 주소를 포함시켜야 합니다: "--apidog-api-base-url=<http:// 또는 https://로 시작하는 온프레미스 서버의 API 주소>" 또한, www.npmjs.com에 대한 네트워크 접근이 올바른지 확인하십시오.
{
"mcpServers": {
"apidog-site-123456": {
"command": "npx",
"args": [
"-y",
"apidog-mcp-server@latest",
"--site-id=123456",
// 온프레미스 배포에 필요:
"--apidog-api-base-url=<온프레미스 서버의 API 주소>"
]
}
}
}Mintlify MCP 서버 생성기의 장단점
제 경험을 요약하기 위해, Mintlify의 MCP 서버 생성기의 장단점은 다음과 같습니다:
장점
- 쉬운 설정: CLI 기반의 설치 및 생성 프로세스가 간단하여 5분 이내에 완료됩니다.
- 매끄러운 AI 통합: 서버는 Cursor와 같은 AI 클라이언트와 잘 통합되어 맥락적 검색 및 API 실행이 가능합니다.
- 문서 중심: 문서를 AI에 접근 가능하게 만들어 사용자 경험을 개선합니다.
단점
- 제한된 확장성: 기본 구성은 고트래픽 시나리오에서 어려움을 겪으며, 수동 최적화가 필요합니다.
- 디버깅 도구 부족: API 트래픽을 검사하는 내장된 방법이 없어 문제 해결이 어려울 수 있습니다.
- 좁은 초점: 주로 OpenAPI 사양만 지원하여 다른 데이터 소스에 대한 적용 가능성이 제한됩니다.
왜 Apidog가 MCP 서버 필요에 대한 더 나은 대안인가요?
Mintlify의 MCP 서버 생성기가 문서 중심의 사용 사례에 대한 견고한 도구인 반면, Apidog는 MCP 서버와 함께 작업하는 개발자에게 더 종합적인 솔루션을 제공합니다. Apidog는 여러 데이터 소스를 처리하고, 상세한 API 트래픽 통찰력을 제공하며 코드 생성을 지원하는 기능 덕분에 복잡한 워크플로에 더 적합한 선택입니다. 또한, Apidog의 MCP 서버 베타 버전은 활성적으로 업데이트되고 있으며 개발자 피드백에 중점을 두어 실제 필요를 충족하도록 진화하고 있습니다.
API와 AI 모델을 통합하려는 개발자라면, Apidog를 시작하는 것을 추천합니다. 강력한 기능 세트와 디버깅 능력은 Mintlify의 더 제한적인 제공에 비해 시간을 절약하고 노력을 덜어 줄 것입니다.
결론: Mintlify MCP 서버 생성기를 사용해야 할까요?
Mintlify의 MCP 서버 생성기를 철저히 테스트한 후, 저는 이 도구가 문서를 AI 준비 상태로 만들고자 하는 개발자에게 유망한 도구라고 할 수 있습니다. 사용의 용이성과 API 통합에 대한 초점은 칭찬할 만하지만, 확장성과 디버깅에서 부족함을 드러냅니다—Apidog가 뛰어난 분야입니다. AI 기능으로 문서를 개선하는 것이 주요 목표라면 Mintlify는 좋은 선택입니다. 그러나 더 고급 MCP 서버 요구 사항이 있다면 Apidog가 더 나은 대안입니다.
MCP가 계속 진화함에 따라, Mintlify와 Apidog와 같은 도구는 개발자들이 API와 AI를 통합하는 방식을 형성하는 데 중요한 역할을 할 것입니다. 두 플랫폼이 향후 어떻게 개선될지 기대되며, 현재로서는 Apidog의 다재다능함과 개발자 친화적인 기능에 제 선택을 맡기고 있습니다.