MCPJam으로 MCP 서버 테스트하기

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

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

바로 그 역할을 하는 도구가 MCPJam입니다. “Postman for MCP”라고 불리는 이 개발 플랫폼으로 MCP 서버를 디버깅하고, AI 모델과 대화하면서 테스트하고, 여러 AI 클라이언트에 걸쳐 평가까지 돌릴 수 있어요. 이 글을 처음 쓴 4월 이후로 MCPJam은 3.x 버전대로 올라오면서 화면 구성이 크게 바뀌고 기능도 많이 늘었는데요. 이번에 v3.12 기준으로 직접 돌려 본 화면을 곁들여 다시 정리했습니다.

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가 시작되고 브라우저가 http://127.0.0.1:6274로 열립니다. 패키지가 요구하는 Node.js 버전은 22 이상이고, 데스크톱 앱과 마찬가지로 STDIO와 HTTP/HTTPS 서버를 모두 지원합니다. 이 글의 화면은 모두 이 방식으로 띄운 v3.12.3에서 캡처했습니다.

Docker를 선호한다면 컨테이너로도 실행할 수 있어요. 예전에는 Docker Hub에 이미지가 올라와 있었는데, 지금은 배포 이미지가 없어서 저장소를 받아 직접 빌드해야 합니다.

git clone https://github.com/MCPJam/inspector.git
cd inspector
docker build -t mcpjam/mcp-inspector:local -f mcpjam-inspector/Dockerfile .
docker run -p 127.0.0.1:6274:6274 mcpjam/mcp-inspector:local

보안을 위해 docker run의 포트를 반드시 127.0.0.1에 바인딩해야 한다는 점을 기억해주세요. macOS나 Windows에서 호스트에 떠 있는 MCP 서버에 붙으려면 http://host.docker.internal:포트 주소를 쓰면 됩니다.

서버 연결하기

처음 Inspector를 열면 서버 연결 창이 바로 뜹니다. 예전에는 연결 타입을 드롭다운에서 고르고 이름과 URL을 따로 입력했는데, 지금은 입력란 하나에 URL이나 실행 명령어를 넣기만 하면 HTTP, SSE, STDIO를 알아서 구분해 줍니다. 테스트할 서버가 아직 없다면 “Try the Excalidraw demo server”를 눌러 데모 서버로 시작해도 됩니다.

여기서는 제가 기여하고 있는 Rust MCP SDK(rmcp) 저장소의 카운터 예제 서버를 http://127.0.0.1:8000/mcp에 띄워 연결해 봤습니다. 연결되면 왼쪽 사이드바의 Home 화면으로 넘어가는데요. 프로젝트의 서버 수와 최근 도구 실행 횟수 같은 요약 정보, “What’s new” 소식, 추천 서버와 추천 클라이언트가 한눈에 보입니다. 가운데 입력창은 Ask MCPJam이라는 도우미 에이전트로, “서버 상태 확인해 줘”처럼 말로 작업을 맡길 수 있어요.

사이드바도 예전과 구성이 달라졌습니다. Explore(Home, Connect, Playground), Measure(Swarms, User Testing, Evaluate), Verify(OAuth Debugger, XAA Debugger), Inspect(Tools, Resources, Prompts, Tasks, WebMCP) 네 묶음으로 정리되었는데요. 연결한 서버는 Connect 화면에서 한꺼번에 관리합니다. 서버마다 연결 스위치와 “Supported by N” 배지가 붙어 있고, 오른쪽에는 오가는 JSON-RPC 로그가 실시간으로 쌓입니다.

도구 직접 호출하기

도구 하나를 콕 집어 호출해 보고 싶다면 Inspect 묶음의 Tools로 갑니다. Postman에서 API를 테스트하듯 도구를 고르고 파라미터를 채운 뒤 “Run”을 누르면 가운데에 응답이, 오른쪽에 JSON-RPC 요청과 응답이 그대로 찍혀요. 아래는 카운터 서버의 sum 도구에 1234와 5678을 넘긴 결과입니다. 로그에서 tools/call 요청을 펼치면 실제로 전송된 params까지 확인할 수 있죠.

화면 위쪽 “Saved” 탭에 자주 쓰는 요청을 저장해 두면 서버를 고친 뒤 같은 요청을 다시 보내 보기도 편합니다.

Playground: 채팅과 앱 테스트를 한곳에서

예전 버전에서 따로 있던 Chat 탭과 App Builder 탭은 이제 Playground 하나로 합쳐졌습니다. 왼쪽에는 연결된 서버의 도구 목록이, 가운데에는 채팅 화면이 있는 IDE 같은 구성이에요. MCP 서버를 연결한 채로 실제 AI 모델과 대화를 나눌 수 있고, 로그인하지 않아도 MCPJam이 제공하는 무료 모델로 바로 시작할 수 있습니다. 물론 자신의 API 키를 넣거나 로컬 Ollama 모델을 붙여도 됩니다.

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

“1234와 5678을 더하면 얼마야?”라고 물어보면 모델이 sum 도구를 호출하는 과정이 카드로 표시되고, 카드를 펼치면 모델이 넘긴 입력과 서버가 돌려준 결과가 보입니다.

채팅 위의 Trace 탭으로 넘어가면 같은 대화를 타임라인으로 볼 수 있습니다. 사용자 메시지, 모델의 첫 응답, 도구 호출, 최종 응답이 폭포수(waterfall) 형태로 나열되고, 단계마다 걸린 시간과 토큰 사용량이 함께 나와요. 응답이 느릴 때 모델 쪽이 느린 건지 서버 쪽이 느린 건지 바로 구분할 수 있습니다. 여기서는 전체 4.61초 중 sum 도구 실행은 14ms에 불과했네요.

Playground는 예전 App Builder의 역할도 이어받았습니다. MCP 앱이나 ChatGPT 앱처럼 UI 위젯을 돌려주는 서버를 연결하면 위젯이 채팅 안에서 그대로 렌더링돼요. 데모용 Excalidraw 서버에 다이어그램을 그려 달라고 했더니, 모델이 도구를 호출하고 손그림 스타일의 다이어그램 위젯이 채팅창에 나타났습니다. 위쪽 도구 모음에서 표시 모드, 로캘, 시간대, 기기 크기, 테마 같은 호스트 환경을 바꿔 가며 위젯이 어떻게 보이는지도 확인할 수 있습니다.

클라이언트별로 비교하기

이번 업데이트에서 가장 크게 달라진 개념이 클라이언트(Client)입니다. 예전에는 “모델” 단위로 비교했다면, 지금은 ChatGPT, Claude, Cursor처럼 실제로 MCP 서버를 쓰는 AI 클라이언트의 설정을 흉내 낸 클라이언트 단위로 테스트합니다. 같은 서버라도 클라이언트마다 지원하는 프로토콜 버전과 기능, 위젯을 다루는 방식이 다르기 때문이에요.

Playground 입력창의 클라이언트 선택기에서 “Add clients”를 누르면 AgentCore, ChatGPT, Claude, Cursor, VS Code, Goose 등 템플릿이 쭉 나옵니다.

클라이언트를 여러 개 고르면 최대 3개까지 화면을 나눠 같은 프롬프트를 동시에 보낼 수 있어요. 아래는 ChatGPT 클라이언트와 MCPJam 기본 클라이언트에 같은 질문을 던진 결과입니다. 한쪽은 도구를 잘 호출하는데 다른 쪽은 실패한다면? 도구 설명이나 서버 설정을 손봐야 한다는 신호겠죠. 각 창마다 Chat, Trace, Raw 뷰가 따로 있어서 어디서 갈라졌는지 나란히 추적할 수 있습니다.

채팅을 돌려 보기 전에 정적으로 호환성을 따져 볼 수도 있습니다. Connect 화면의 서버 설정 창에서 Clients 탭을 열면 서버의 도구와 위젯을 기준으로 클라이언트별 지원 여부가 표시돼요. “Run checks”를 누르면 모든 클라이언트에 공통으로 적용되는 스펙 적합성(conformance) 검사도 돌아갑니다.

실제로 카운터 예제 서버에 검사를 돌려 보니 리소스 목록 응답에 MCP 2026-07-28 스펙의 캐시 힌트가 빠져 있다는 등 몇 가지 실패가 잡혔고, 최신 스펙 버전을 아직 따라가지 못한 클라이언트는 “Protocol version differs”로 구분되었습니다. “Fix these checks first. They affect every host.”라는 문구처럼, 특정 클라이언트 문제로 보이던 것이 사실은 서버 쪽 스펙 위반인 경우를 먼저 걸러 주는 셈이에요.

OAuth 디버거와 XAA 디버거

원격 MCP 서버를 배포하면 인증은 빠질 수 없는 부분입니다. Verify 묶음의 OAuth Debugger는 MCP OAuth 흐름을 한 단계씩 진행하면서 왼쪽 시퀀스 다이어그램과 오른쪽 가이드 패널로 무슨 일이 일어나는지 보여줘요.

동적 클라이언트 등록(DCR)과 클라이언트 ID 메타데이터 문서(CIMD)를 지원하고, MCP 스펙 버전도 2025-03-26, 2025-06-18, 2025-11-25에 더해 최신 2026-07-28까지 골라서 테스트할 수 있습니다.

rmcp 저장소의 OAuth 예제 서버를 대상으로 돌려 봤는데요. 첫 요청에 401이 오는 데까지는 정상이었지만, 3단계에서 보호 리소스 메타데이터(RFC 9728)를 요청하는 /.well-known/oauth-protected-resource마저 401을 돌려준다는 오류가 빨갛게 표시되었습니다. 메타데이터 경로까지 인증 미들웨어 뒤에 있었던 거죠. 클라이언트 입장에서는 어느 인가 서버를 찾아가야 하는지 알 길이 없으니, 실제 클라이언트에서는 “로그인이 안 된다” 정도의 모호한 증상으로만 드러났을 문제입니다.

바로 옆의 XAA Debugger는 Cross-App Access, 즉 사내 신원 공급자(IdP)가 발급한 ID-JAG 토큰으로 MCP 서버에 접근하는 기업용 흐름을 디버깅합니다. MCPJam이 테스트용 IdP 역할을 대신해 주고, OIDC와 SAML 어설션을 모두 지원해요. 잘못된 어설션을 일부러 보내 서버가 제대로 거부하는지 보는 음성 테스트(negative test) 점수표도 들어 있습니다.

평가(Evaluate)

MCP 서버를 한 번 만들고 끝이 아니라 계속 유지보수해야 한다면 Evaluate를 눈여겨보세요. 특정 프롬프트에 대해 AI가 기대한 도구를 호출하는지 자동으로 검증하는 테스트 스위트를 만들어 두고, 서버를 고칠 때마다 돌려서 회귀(regression)를 잡는 기능입니다.

예를 들어 “서울의 현재 날씨를 알려줘”라는 프롬프트에 get_weather 도구가 location: "Seoul" 인자로 호출되어야 한다는 테스트 케이스를 만들 수 있습니다. 예전에는 이런 케이스를 직접 작성해야 했지만, 이제는 연결된 서버에서 “Eval my server”를 누르면 케이스를 자동으로 생성해 줍니다. 스위트를 만들 때는 어떤 클라이언트에서 어떤 모델로 돌릴지 조합을 정하는데, 여기서도 모델이 아니라 클라이언트가 기준이 된다는 점이 눈에 띄어요.

평가를 실제로 돌리고 결과를 저장하려면 MCPJam 계정이 필요합니다.

Swarms와 User Testing

Measure 묶음에는 “New” 배지가 붙은 기능이 두 개 더 있습니다.

Swarms는 가상의 사용자 페르소나를 만들어 목표를 주고, 이들이 실제 클라이언트 환경에서 서버를 쓰게 한 뒤 어디서 막혔는지 보고해 주는 기능입니다. 평가가 “정해 둔 프롬프트에 정답을 내는가”를 본다면, Swarms는 “사람들이 자기 방식대로 쓸 때 목표를 이룰 수 있는가”를 보는 셈이죠. 아래 예시처럼 14개 목표 중 12개를 달성했고 어느 페르소나가 불편을 겪었는지 요약해 줍니다.

User Testing은 여기서 한 발 더 나아가 진짜 사람을 불러옵니다. 스터디 링크를 보내면 참가자가 익숙한 클라이언트 모양의 화면에서 서버를 써 보고, 그 세션이 기록되어 목표, 행동, 결과, 만족도 흐름으로 정리돼요. 두 기능 모두 계정이 있어야 쓸 수 있습니다.

CLI로 CI/CD에 통합하기

MCPJam은 GUI 도구로만 끝나지 않습니다. CLI와 SDK도 제공하기 때문에 터미널에서 바로 돌리거나 자동화 파이프라인에 넣을 수 있어요. CLI도 5.x로 올라오면서 명령 체계가 바뀌었는데요. 로컬 서버를 대상으로 하는 명령은 최상위에, MCPJam 계정과 연결되는 명령은 cloud 아래에 모였습니다.

CLI는 전역으로 설치합니다.

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

로컬 서버에 도구를 호출하는 건 명령 한 줄이면 됩니다.

mcpjam tools call --url http://127.0.0.1:8000/mcp --tool-name sum --tool-args '{"a":1234,"b":5678}'

{
  "content": [{ "type": "text", "text": "6912" }],
  "isError": false,
  "_durationMs": 16
}

--expect-success와 --reporter junit-xml을 붙이면 도구 호출 결과를 CI가 이해하는 JUnit XML로 받아볼 수 있습니다.

mcpjam tools call --url http://127.0.0.1:8000/mcp --tool-name sum --tool-args '{"a":1234,"b":5678}' --expect-success --reporter junit-xml

<?xml version="1.0" encoding="UTF-8"?>
<testsuites name="tools-call-validation" tests="1" failures="0" time="0.039">
  <testsuite name="tools-call-validation" tests="1" failures="0" time="0.039">
    <testcase name="tool-call-success-policy" classname="mcpjam.tools-call-validation.validation" time="0.000"/>
  </testsuite>
</testsuites>

이 밖에도 서버 연결 상태를 한 번에 점검하는 mcpjam server doctor, 클라이언트별 호환성을 따지는 mcpjam compat, OAuth 흐름을 검사하는 mcpjam oauth와 mcpjam xaa 같은 명령이 있어서 GUI에서 본 기능 대부분을 터미널에서도 돌릴 수 있어요.

Evaluate에서 만든 평가 스위트는 mcpjam cloud eval run으로 실행합니다. 예전 1.x 시절의 mcpjam evals run --tests tests.json --environment environment.json --llms llms.json 방식은 이제 쓰지 않고, 클라우드에 저장해 둔 스위트 이름을 넘기거나 버전이 붙은 스위트 파일을 올려서 실행해요.

mcpjam cloud eval run --suite counter --wait --reporter junit-xml --out eval-report.xml

--wait은 실행이 끝날 때까지 기다리게 하고, --reporter와 --out은 결과 보고서를 JUnit XML이나 HTML 파일로 남깁니다. GitHub Actions 워크플로우에 넣으면 대략 이렇습니다.

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

jobs:
  eval:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: 22
      - run: npm install -g @mcpjam/cli
      - run: mcpjam cloud eval run --suite counter --wait --reporter junit-xml --out eval-report.xml
        env:
          MCPJAM_API_KEY: ${{ secrets.MCPJAM_API_KEY }}

CI처럼 브라우저로 로그인할 수 없는 환경에서는 MCPJAM_API_KEY 환경 변수로 인증합니다. PR마다 평가를 돌리고 보고서를 남겨 두면 서버를 고치다 기존 동작이 깨지는 걸 병합 전에 잡아낼 수 있어요.

프로젝트와 팀 협업

예전의 워크스페이스는 프로젝트(Project)라는 이름으로 바뀌었습니다. 여러 MCP 서버와 클라이언트, 평가 스위트를 하나의 프로젝트로 묶어 관리하고, 팀원과 실시간으로 동기화할 수 있어요.

웹 앱에서는 MCP 서버 링크를 Google Docs 공유하듯 팀원에게 보낼 수 있습니다. “이 서버 한번 테스트해봐”하면서 링크 하나 던져주면 상대방도 같은 환경에서 바로 시작할 수 있죠. 로컬에서 띄운 서버라면 Connect 화면의 “Create tunnel” 버튼으로 외부에서 접근할 수 있는 주소를 만들어 공유하면 됩니다.

마치며

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

반년 사이 가장 크게 바뀐 점을 하나만 꼽자면 테스트의 기준이 “모델”에서 “클라이언트”로 옮겨 갔다는 것입니다. 사용자는 모델이 아니라 ChatGPT, Claude, Cursor 같은 클라이언트로 서버를 만나니까요. 이번에 rmcp의 예제 서버를 연결해 보면서도 스펙 적합성 검사와 OAuth 디버거가 그냥 지나쳤을 문제를 몇 가지 짚어 줬습니다. MCP 서버를 다루고 있다면 한번 연결해 보세요.

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