# MCP Inspector 완벽 활용 가이드 — 클라이언트 없이 MCP 서버를 단독 검증하는 법

MCP Inspector 완벽 활용 가이드 — 클라이언트 없이 MCP 서버를 단독 검증하는 법

지난 강의에서 우리는 mcp_server.py 에 두 개의 도구(read_doc_contents, edit_document) 를 정의했습니다. 그런데 막상 잘 만들었는지 어떻게 확인할까요?

가장 무식한 방법은 클라이언트 코드를 다 짠 다음 챗봇을 켜고 "문서 읽어줘" 라고 시켜보는 거예요. 하지만 그러면 버그가 어디서 났는지 추적하기가 까다롭습니다. 도구 자체 문제? 클라이언트 문제? 프롬프트 문제? 디버깅이 미궁에 빠지죠.

오늘 등장하는 MCP Inspector 는 이 문제를 정면으로 해결합니다. 클라이언트도, Claude도 없이 MCP 서버를 단독으로 검증 할 수 있는 브라우저 기반 도구예요. 🔍

---

🤔 MCP Inspector란?

한 줄 정의:

MCP 서버에 직접 연결해서, 도구·리소스·프롬프트를 GUI 로 호출하고 응답을 확인할 수 있는 개발자용 검증 도구.

어떤 문제를 풀어주나?

문제	Inspector 가 주는 해법
🤔 "도구가 정말 등록됐을까?"	List Tools 로 카탈로그 즉시 확인
🤔 "JSON 스키마가 의도대로 생성됐을까?"	도구별 입력 폼이 자동 생성되어 시각적으로 검증
🤔 "응답 형식이 올바른가?"	결과를 JSON 으로 그대로 보여줌
🤔 "에러는 어떻게 보일까?"	잘못된 입력으로 일부러 실패시켜도 메시지 확인
🤔 "이 버그가 서버 탓인가, 클라이언트 탓인가?"	클라이언트를 배제한 채 서버만 격리 테스트

💡 핵심: 클라이언트·LLM 을 모두 우회하고 서버만 따로 확인 할 수 있다는 게 진짜 가치입니다.

---

🚀 Inspector 띄우기

먼저 프로젝트의 Python 환경이 활성화돼 있는지 확인하세요 (UV 또는 venv).

그리고 한 줄로 실행:

mcp dev mcp_server.py

이게 일어나는 일:

1. 🚀 MCP 서버를 자식 프로세스로 실행 (stdio 모드)
2. 🌐 로컬에서 개발 서버를 띄움 — 보통 http://localhost:6277 같은 URL
3. 🖥️ 콘솔에 브라우저로 열 URL 이 출력됨

🔍 MCP Inspector listening on http://localhost:6277
   Open this URL in your browser to start testing.

URL 을 클릭하면 MCP Inspector 대시보드가 열립니다.

⚠️ 인터페이스 변동성 주의: Inspector 는 적극 개발 중이라 화면이 강의의 스크린샷과 다를 수 있습니다. 단, 도구·리소스·프롬프트 테스트라는 핵심 기능은 동일합니다. 버튼 위치가 살짝 달라져도 당황하지 마세요.

---

🔌 Connect 버튼 — 서버에 연결하기

대시보드 좌측에 "Connect" 버튼이 있습니다. 클릭하면:

• ✅ MCP 서버 프로세스 기동
• ✅ stdio 채널로 핸드셰이크
• ✅ 상단 네비게이션에 Resources / Prompts / Tools 등 탭 활성화

💡 이 시점에 연결이 안 된다면?

• 서버 코드에 문법 오류 (콘솔 로그 확인)
• mcp SDK 미설치 또는 버전 문제
• stdout 에 다른 출력이 섞여 들어가 stdio 통신을 깨뜨리는 경우 (print() 호출 등)

---

🛠️ 도구 테스트 — 5단계 워크플로

도구를 검증하는 순서는 단순합니다.

1️⃣ Tools 탭으로 이동
        ↓
2️⃣ "List Tools" 클릭 — 등록된 도구 카탈로그 표시
        ↓
3️⃣ 테스트할 도구 선택 — 입력 폼 자동 생성
        ↓
4️⃣ 필수 파라미터 입력
        ↓
5️⃣ "Run Tool" 클릭 — 결과 확인

예시 — read_doc_contents 테스트

1. Tools 탭 → read_doc_contents 선택
2. 입력 폼에 자동 생성된 doc_id 필드 표시
3. deposition.md 입력
4. Run Tool 클릭

결과:

✅ Result:
"This deposition covers the testimony of Angela Smith, P.E."

예시 — edit_document 후 다시 읽기 (체이닝)

문서 편집 도구를 테스트할 땐 편집 → 읽기 순서로 체이닝해서 변경사항을 확인하는 게 좋습니다.

[1] edit_document(
       doc_id="plan.md",
       old_str="implementation",
       new_str="rollout"
    ) → ✅ 성공

[2] read_doc_contents(doc_id="plan.md")
    → "The plan outlines the steps for the project's rollout."

🎯 두 도구가 상태를 공유하고 있다는 점도 함께 검증됩니다. 메모리 dict 가 잘 작동하는지 확인하는 셈이죠.

---

🐞 에러 케이스도 일부러 돌려보세요

운영 직전엔 잘못된 입력 으로 실패시키는 테스트가 정말 중요합니다.

시도	기대 응답
read_doc_contents(doc_id="없는파일.md")	ValueError: Doc with id 없는파일.md not found
read_doc_contents(doc_id="")	(Pydantic 검증) 또는 ValueError
edit_document 의 old_str 이 본문에 없는 경우	(현재 구현은 그냥 무변경 — 개선 가능 포인트)

💡 Inspector 는 "사람이 직접 굴리는 단위 테스트" 입니다. 자동화된 테스트 슈트로 넘기기 전에 손으로 한 번 굴려보면, 요구사항 빈틈 이 눈에 잘 띄어요.

---

🔄 개발 사이클이 빨라진다

Inspector 를 일상적으로 쓰면 다음 같은 효율적인 루프가 만들어집니다.

1️⃣ 코드 수정
       ↓
2️⃣ Inspector 가 자동으로 reload (또는 Connect 재클릭)
       ↓
3️⃣ 도구 호출 즉시 결과 확인
       ↓
4️⃣ 문제 있으면 1번으로 돌아가기

Inspector 없을 때	Inspector 있을 때
① 서버 수정	① 서버 수정
② 클라이언트 코드도 같이 손봄	② Inspector 에서 Run Tool
③ Claude API 호출까지 가서 검증	③ 결과 즉시 확인
④ 어디서 실패한 건지 추적	④ 끝
⑤ 비용까지 발생	(비용 0)

🎯 결정적 차이: Inspector 는 Claude API 호출 없이 서버만 검증합니다. 비용도 0, 시간도 0. 도구 정의 단계의 디버깅은 거의 100% 여기서 끝내는 게 좋아요.

---

💼 한국 개발자를 위한 부가 팁

1️⃣ 트러블슈팅 — 흔히 마주치는 문제

🚨 "Connection failed" / 연결 실패

원인 후보:

• 서버 코드의 import 에러나 문법 오류 — 콘솔 로그 먼저 확인
• 서버 시작 시 print() 가 stdout 으로 흘러나가 통신을 깨뜨림 → print 대신 logging 사용 (또는 file=sys.stderr 로 분리)
• mcp SDK 미설치 / 구버전

🚨 포트 6277 이 이미 사용 중

# 다른 프로세스가 6277 점유 중일 때
lsof -i :6277        # 무엇이 잡고 있는지
kill <PID>           # 종료 후 재시작

🚨 한글 입력/출력 깨짐 (Windows)

# mcp_server.py 상단
import sys
sys.stdout.reconfigure(encoding='utf-8')
sys.stderr.reconfigure(encoding='utf-8')

2️⃣ Hot Reload 활용

mcp dev 는 보통 파일 변경을 감지하고 자동으로 재시작 합니다. 코드를 수정하면 Inspector 에서 다시 Connect 만 누르면 새 코드가 반영돼요.

💡 Tip: 크게 수정한 뒤엔 한 번 Connect → Disconnect → Connect 로 깨끗하게 재연결하는 습관이 안전합니다. 메모리 상태가 새 시작점으로 초기화돼요.

3️⃣ Inspector 로 검증할 항목 체크리스트

배포 전 다음을 모두 한 번씩 굴려보세요.

• List Tools — 모든 도구가 보이는가?
• 각 도구의 JSON 스키마가 의도와 일치하는가?
• 정상 입력 으로 기대 결과가 나오는가?
• 잘못된 입력 으로 적절한 에러 메시지가 나오는가?
• 빈 문자열, 매우 긴 문자열, 특수문자 같은 엣지 케이스
• 상태가 변하는 도구의 경우, 변경 후 다시 읽기로 확인
• (이후 강의) Resources / Prompts 도 모두 노출되는가?

4️⃣ Inspector vs 자동화 테스트 — 둘 다 필요하다

도구	강점	한계
MCP Inspector	빠른 시각적 확인, 즉시성, 학습 곡선 0	회귀 방지 X, 자동 실행 X
pytest + 단위 테스트	회귀 방지, CI/CD 통합	작성 비용, 시각적 피드백 부족

🎯 권장 흐름: 새 기능을 만들 땐 Inspector 로 빠르게 손에 잡히게 검증한 뒤, 안정화된 시점에 pytest 로 회귀 테스트 를 추가하세요.

5️⃣ 보안 — Inspector 는 로컬 개발 도구

⚠️ Inspector 가 띄우는 개발 서버는 로컬 머신용 입니다. 운영 환경에 노출하지 마세요.

• 외부에서 접근 가능한 IP/포트로 노출 ❌
• 운영 시크릿이 들어 있는 환경에서 띄울 땐 별도 secret 격리
• CI 빌드 머신에서는 띄우지 말 것

---

🔮 다음 강의로 가는 다리

지금까지 우리는:

• ✅ 서버에서 도구 정의 (지난 강의)
• ✅ Inspector 로 도구 검증 (이번 강의)

이제 진짜 클라이언트 를 만들 차례입니다. 다음 강의 "Implementing a client" 에서는 mcp_client.py 를 채워서:

• 🔗 stdio 로 우리 MCP 서버에 연결
• 📋 ListTools 로 도구 목록 가져오기
• 🚀 CallTool 로 도구 실행
• 🔁 그 결과를 Claude API 로 흘려보내기

이 모든 흐름을 직접 코드로 짭니다. 챕터 7 의 클라이맥스가 시작돼요. 🎬

---

🧠 핵심 정리

• 🔍 MCP Inspector = 클라이언트·LLM 없이 서버만 단독 검증하는 GUI 도구.
• 🚀 실행은 한 줄: mcp dev mcp_server.py → 보통 localhost:6277 에서 대시보드.
• 🔌 좌측 Connect 버튼으로 서버 프로세스 기동.
• 🛠️ 도구 테스트 5단계: Tools 탭 → List Tools → 도구 선택 → 파라미터 입력 → Run Tool.
• 🐞 정상 케이스 + 에러 케이스를 모두 굴려보면 빈틈이 잘 보입니다.
• 🔄 Inspector 는 Claude API 호출 없이 서버만 격리 테스트 — 비용 0, 시간 0.
• 🛡️ Inspector 는 로컬 개발용 — 운영 환경에 노출 금지.
• 📋 배포 전 체크리스트: 도구 카탈로그, 스키마, 정상/에러 케이스, 엣지 케이스, 상태 변경 검증.
• 🎯 다음 강의: Implementing a client 에서 stdio 로 직접 연결하는 클라이언트 코드 작성.

---

📚 출처 (Source)

본 글은 Anthropic Academy의 "Building with the Claude API" 코스 중 'The server inspector' 강의 내용을 한국어로 정리·요약한 것입니다.

• 원문 출처: Anthropic Academy
• 강의 챕터: Model Context Protocol → The server inspector
• 저작권: © Anthropic. All rights reserved.

⚠️ 본 글은 학습 목적의 요약본이며, Inspector UI 는 활발히 개발 중이라 화면 구성이 변할 수 있습니다. 정확하고 최신화된 내용은 반드시 MCP 공식 사이트 와 Python SDK 저장소 를 참고해주세요.

---

📝 이 글이 도움이 되셨다면 공감 ♥ 과 구독 부탁드립니다!
Inspector 로 검증한 MCP 서버 경험이 있다면 댓글로 공유해주세요. 다음 강의는 "Implementing a client — MCP 클라이언트 직접 구현하기" 입니다. 🔗

#MCP #ModelContextProtocol #MCPInspector #ClaudeAPI #AnthropicAcademy #ClaudeAI #LLM #AI개발 #API개발 #서버검증 #Debugging #PythonSDK