MCPJam으로 MCP 서버 테스트하기

MCP 서버를 만들어 보신 적 있으신가요? 도구(tool)를 정의하고 JSON-RPC 메시지를 주고받는 코드를 작성하고 나면… 이게 제대로 동작하는지 어떻게 확인하셨나요? 🤔

Claude나 ChatGPT에 직접 연결해서 테스트하다 보면 문제가 생겼을 때 원인 파악이 어렵습니다. LLM이 도구를 엉뚱하게 호출한 건지, 서버가 잘못된 응답을 보낸 건지, 전송 계층 문제인지 구분이 안 되거든요. Postman으로 REST API를 테스트하듯 MCP 서버도 전용 도구로 검증할 수 있으면 좋겠다는 생각이 드실 겁니다.

바로 그 역할을 하는 도구가 MCPJam입니다. “Postman for MCP”라고 불리는 이 개발 플랫폼으로 MCP 서버를 디버깅하고, AI 모델과 대화하면서 테스트하고, 여러 LLM에 걸쳐 평가까지 돌릴 수 있어요. 이 글에서는 MCPJam이 뭘 해주는 도구인지, 실제로 어떻게 쓰는지 살펴보겠습니다.

MCP Inspector와 MCPJam Inspector

MCP(Model Context Protocol)를 다뤄보신 분이라면 Anthropic에서 제공하는 공식 MCP Inspector를 사용해보셨을 수 있습니다. 공식 Inspector는 MCP 서버의 도구, 리소스, 프롬프트를 수동으로 호출해보고 JSON-RPC 메시지를 들여다볼 수 있는 가벼운 디버깅 도구입니다.

MCPJam Inspector는 여기서 한 걸음 더 나아갑니다. 수동 검사는 물론이고 실제 LLM과 대화하면서 테스트하거나 OAuth 디버깅, 평가(Evals) 실행, CI/CD 통합까지 되는 개발 플랫폼이에요. 공식 Inspector가 “서버가 프로토콜 스펙을 잘 지키는가”에 초점을 맞춘다면, MCPJam Inspector는 “실제 AI 모델이 이 서버의 도구를 올바른 맥락에서 제대로 호출하는가”까지 확인해줍니다.

설치하기

MCPJam Inspector는 세 가지 방식으로 사용할 수 있습니다.

가장 간단한 방법은 웹 브라우저에서 바로 접속하는 겁니다. app.mcpjam.com을 열면 설치 없이 바로 쓸 수 있고 항상 최신 버전이죠. 다만 HTTPS 원격 MCP 서버만 연결되기 때문에 로컬 STDIO 서버를 테스트하려면 데스크톱 앱이나 터미널 방식을 써야 합니다.

데스크톱 앱은 Mac과 Windows 용으로 나와 있습니다. Node.js 같은 런타임이 필요 없고 HTTP/HTTPS 원격 서버와 로컬 STDIO 서버를 모두 테스트할 수 있어서 개인적으로 가장 추천하는 방식이에요.

터미널에서 npx로 실행하는 방법도 있습니다.

npx @mcpjam/inspector@latest

이 명령을 실행하면 로컬에서 Inspector가 시작되고 브라우저에서 접속할 수 있습니다. Node.js 20 이상이 필요하고, 데스크톱 앱과 마찬가지로 STDIO와 HTTP/HTTPS 서버를 모두 지원합니다.

Docker를 선호한다면 컨테이너로도 실행할 수 있어요.

docker run -p 127.0.0.1:6274:6274 mcpjam/mcp-inspector

보안을 위해 반드시 127.0.0.1에 바인딩해야 한다는 점을 기억해주세요. 실행 후 브라우저에서 http://127.0.0.1:6274로 접속하면 됩니다.

서버 연결하기

MCPJam Inspector를 열고 나면 가장 먼저 할 일은 테스트할 MCP 서버를 연결하는 것입니다. 우측 상단의 “Add Server” 버튼을 클릭하면 연결 설정 화면이 나타납니다.

연결 타입은 드롭다운에서 선택할 수 있는데, HTTP, STDIO, SSE 세 가지를 지원합니다. 원격 서버라면 HTTP나 SSE를, 로컬에서 실행 중인 서버라면 STDIO를 선택하면 됩니다. 서버 이름과 URL(또는 STDIO의 경우 실행 명령어)을 입력하고 연결하면 서버가 노출하는 도구, 리소스, 프롬프트 목록이 좌측 패널에 표시됩니다.

여기서부터는 Postman에서 API 테스트하듯 도구를 골라서 파라미터를 넣고 “Execute”를 누르면 됩니다. 모든 JSON-RPC 메시지가 실시간으로 찍히기 때문에 요청과 응답 흐름을 통째로 들여다볼 수 있어요.

Chat 기능

Chat은 MCPJam Inspector에서 가장 눈에 띄는 기능입니다. MCP 서버를 연결한 채로 실제 AI 모델과 대화를 나눌 수 있거든요. Claude, GPT, 로컬 Ollama 모델까지 지원합니다.

왜 이게 중요할까요? 도구를 수동으로 호출해서 응답이 잘 오는 것과 AI 모델이 자연어 대화 중에 적절한 시점에 올바른 도구를 골라 호출하는 것은 전혀 다른 문제입니다. 도구의 description이 모호하면 모델이 엉뚱한 도구를 고를 수 있고, inputSchema가 복잡하면 잘못된 인자를 넘기기도 해요.

Chat에서는 최대 3개 모델을 나란히 놓고 같은 대화를 돌려볼 수 있습니다. Claude는 도구를 잘 호출하는데 GPT는 실패한다? 도구 설명을 개선해야 할 신호겠죠. Chat, Trace, Raw 뷰를 오가면서 대화 내용부터 JSON-RPC 추적, 원시 메시지까지 자유롭게 살펴볼 수 있습니다.

App Builder

MCPJam의 App Builder는 MCP 앱과 ChatGPT 앱을 디버깅하는 환경입니다. 채팅 인터페이스를 넘어 앱이 실제 사용자에게 어떻게 보이는지까지 확인할 수 있어요.

디바이스 에뮬레이터가 내장되어 있어서 Desktop, Tablet, Mobile에서 앱이 어떻게 돌아가는지 미리 볼 수 있습니다. OpenAI의 Apps SDK를 지원하니 ChatGPT 앱을 만들고 있다면 특히 쓸모가 많겠죠. 도구 호출을 직접 트리거하거나 패널에서 채팅하면서 전체 흐름을 따라갈 수 있습니다.

OAuth 디버거

원격 MCP 서버를 배포하면 인증은 빠질 수 없는 부분입니다. MCPJam에는 OAuth 전용 디버거가 들어 있어서 MCP OAuth 스펙을 제대로 따르고 있는지 단계별로 확인해볼 수 있어요.

Dynamic Client Registration(DCR)과 Client ID Metadata Documents(CIMD)를 지원하고 OAuth 스펙 버전도 03-26, 06-18, 11-25를 모두 다룹니다. OAuth 흐름 어디서 문제가 터지는지 정확히 짚어주니까 인증 디버깅 시간이 확 줄어들어요.

평가(Evals)

MCP 서버를 한 번 만들고 끝이 아니라 계속 유지보수해야 한다면 평가(Evals) 기능을 눈여겨보세요. 테스트 케이스를 정의해서 특정 프롬프트에 대해 AI 모델이 기대한 도구를 호출하는지 자동으로 검증할 수 있거든요.

예를 들어 “서울의 현재 날씨를 알려줘”라는 프롬프트에 get_weather 도구가 location: "Seoul" 인자로 호출되어야 한다는 테스트 케이스를 만들 수 있습니다. 이걸 Claude, GPT, Ollama 등 여러 모델에서 돌려보고 정확도를 추적하면 서버를 고쳤을 때 기존 동작이 깨지는 걸 일찍 잡아낼 수 있어요.

CLI로 CI/CD에 통합하기

MCPJam은 GUI 도구로만 끝나지 않습니다. CLI와 SDK도 제공하기 때문에 터미널에서 바로 돌리거나 자동화 파이프라인에 넣을 수 있어요.

CLI는 npm으로 설치합니다.

bun add -g @mcpjam/cli
npm install -g @mcpjam/cli

평가를 실행하려면 세 개의 설정 파일이 필요합니다. 테스트 케이스를 정의하는 tests.json, MCP 서버 연결 정보를 담는 environment.json, LLM API 키를 관리하는 llms.json입니다.

mcpjam evals run --tests tests.json --environment environment.json --llms llms.json

이 명령 하나면 정의해둔 테스트 케이스를 여러 LLM에 대해 실행하고 결과까지 볼 수 있습니다. GitHub Actions나 GitLab CI에 넣으면 PR마다 MCP 서버의 회귀(regression)를 자동으로 잡아주죠.

GitHub Actions 워크플로우에 넣는 흐름은 대략 이렇습니다.

name: MCP Server Test
on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g @mcpjam/cli
      - run: npm install
      - run: npm run build
      - run: mcpjam evals run --tests tests.json --environment environment.json --llms llms.json

서버를 빌드하고 MCPJam CLI로 평가를 돌리는 단계를 추가하면 됩니다. 테스트가 실패하면 CI가 실패하면서 문제 있는 PR이 병합되는 것을 막아줍니다.

워크스페이스와 팀 협업

MCPJam은 워크스페이스라는 개념으로 팀 협업을 지원합니다. 여러 MCP 서버를 하나의 워크스페이스로 묶어서 관리하고 팀원 간 실시간 동기화도 됩니다.

웹 앱에서는 MCP 서버 링크를 Google Docs 공유하듯 팀원에게 보낼 수 있어요. “이 서버 한번 테스트해봐”하면서 링크 하나 던져주면 상대방도 같은 환경에서 바로 시작할 수 있죠. 서버 설정을 일일이 공유하고 다시 입력할 필요가 없습니다.

마치며

MCP 서버 개발이 보편화되면서 “잘 만드는 것” 못지않게 “잘 테스트하는 것”도 중요해지고 있습니다. MCPJam Inspector는 수동 검사부터 LLM 연동 테스트, OAuth 디버깅, 자동화 평가까지 MCP 서버 개발의 전 과정을 다루는 도구입니다.

여러 AI 모델에 걸쳐 도구 호출 정확도를 비교하고 추적하는 기능은 MCP 서버를 프로덕션 환경에서 안정적으로 운영하는 데 큰 도움이 됩니다. CLI와 CI/CD 통합으로 자동화도 되니 MCP 서버를 다루고 있다면 한번 도입해보세요.

MCPJam은 Apache 2.0 라이선스의 오픈소스 프로젝트입니다. 더 자세한 내용은 MCPJam 공식 문서를 참고하세요.