개인적인 필요에서 시작되었습니다

얼마 전, 몇 개의 MCP 서버를 연결하여 프로젝트를 진행하고 있었습니다. 가끔씩 무언가 미묘하게 잘못되곤 했습니다. 서버가 충돌한 것도 아니고 로그도 깨끗했지만, 반대편의 AI 클라이언트가 이상하게 동작했습니다. 도구를 건너뛰거나, 결과를 잘못 읽거나, 엉뚱한 방향으로 흘러갔습니다. 그때마다 저는 커밋을 이분 탐색(bisecting)하고 명세(spec)를 다시 읽으며, 제 서버가 어떤 작은 부분을 조용히 제대로 수행하지 않게 되었는지 알아내기 위해 한두 시간을 허비해야 했습니다.

세 번째나 네 번째쯤 되었을 때, 저는 같은 종류의 문제를 수동으로 디버깅하는 것에 지쳤습니다. 제가 실제로 원했던 것은 서버에 연결하여 명세와 대조해 보고, 클라이언트에 도달하기 전에 무엇이 어디서 깨졌는지 명확하게 알려주는 도구였습니다. 제가 원하는 방식으로 작동하는 도구를 찾을 수 없었기에, 직접 만들었습니다.

vexyo가 하는 일

vexyo는 MCP 서버를 위한 CI 네이티브(CI-native) 테스트 하네스(testing harness)입니다. 두 가지 기능을 수행합니다.

적합성 (Conformance). AI 클라이언트와 정확히 동일한 방식으로 서버에 연결하여 초기화(initialization), 발견(discovery), 오류 의미론(error semantics), 전송(transport)에 걸쳐 16가지 규칙을 실행하고, 이를 MCP 명세(2025-11-25)와 대조하여 확인합니다. 모든 발견 사항은 준수해야 하는 명세의 정확한 섹션을 인용하므로 추측할 필요가 없습니다:

✗ discovery/tools-list-available
  tools/list failed despite the tools capability being advertised
  spec: Server Features §Tools / Listing Tools
...

회귀 (Regression). 도구가 실제로 어떻게 동작하는지(골든 세트, golden sets)를 기록한 다음, 매 커밋마다 세 가지 종류의 드리프트(drift: 스키마, 동작, 커버리지)를 감지합니다. 이를 통해 작동하던 도구를 조용히 망가뜨리는 변경 사항이 배포되는 대신 빌드를 실패하게 만듭니다.

실패 시 0이 아닌 종료 코드(non-zero exit code)를 반환하므로 기본적으로 CI를 차단(gate)합니다. GitHub Action은 규칙, 심각도, 명세 인용 및 수정 방법을 포함하여 PR(Pull Request)에서 바로 조치할 수 있는 작업 요약(job summary)을 출력합니다. 그 작업 요약이야말로 제가 디버깅 세션 중에 간절히 원했던 바로 그것입니다.

어떤 언어와도 함께 작동합니다

vexyo는 런타임 (runtime)이 아니라 전송 계층 (transport, stdio 또는 Streamable HTTP)을 통해 서버와 통신합니다. 따라서 Python, TypeScript, Go, PHP 등 어떤 언어로 작성된 MCP 서버라도 테스트할 수 있습니다. 명령어나 HTTP URL을 지정하기만 하면 됩니다:

import { defineConfig } from '@vexyo/cli/config';

export default defineConfig({
...

사용해 보기

npm i -D @vexyo/cli
npx vexyo init
npx vexyo run

이렇게 하면 설정 파일 (config)이 스캐폴딩 (scaffolding)되고, 서버를 가리키게 되며, 몇 분 안에 첫 번째 결과를 얻을 수 있습니다.

• 문서 (Docs): https://vexyo.dev
• 저장소 (Repo): https://github.com/vexyohq/vexyo
• 무료이며 오픈 소스 (Apache-2.0)입니다.

이 도구는 우선 저 자신의 문제를 해결하기 위해 만들어졌으며, 다른 사용자들에게는 어떤 부분이 가장 먼저 문제가 되는지 진심으로 궁금합니다. 여러분의 서버에서 실행해 보신다면, 무엇을 찾아냈는지(또는 무엇을 잘못 찾아냈는지) 꼭 듣고 싶습니다.

추신: 직접 사용해 보신다면, 무엇을 잡아냈는지 혹은 무엇을 놓쳤는지 알려주세요. 그래야 도구가 더 발전할 수 있습니다. 질문과 이슈 제기는 언제나 환영합니다.