1. 서론
신규 프로젝트로 사용자가 MCP 정보를 입력하면 Docker 내에 MCP 서버를 자동으로 생성하고 구동시키는 프로젝트가 들어왔습니다. 프론트 구성을 하기 전 공부하던 도중 MCP 만드는 법도 공부했는데 이 과정에서 찾은 MCP Inspector라는 녀석을 통해 MCP Server를 테스트하는 방법을 공유하고자 글을 작성하게 되었습니다.
MCP가 뭔지 궁금한 분들은 아래 링크를 참조해주세요!
MCP 공식 문서
MCP란 무엇인가(한컴독스)
MCP 구현 및 테스트 방법
2. MCP Inspector란
MCP Inspector는 Model Context Protocol(MCP) 서버를 테스트하고 디버깅하기 위한 전용 클라이언트 UI 도구
라고 설명되어 있는데 그냥 쉽게 MCP 전용 Swagger라고 생각하면 됩니다. MCP Inspector라는 녀석을 MCP Server에 붙이고 Server가 가지고 있는 Tool, Prompt 등을 테스트 할 수 있게 해줍니다. 또한 MCP에서 자주 사용하는 SSE, Streamable HTTP도 쓸 수 있습니다.
3. MCP Inspector 구동하기
MCP Inspector는 Node18 이상에서 구동시킬 수 있습니다.
npx @modelcontextprotocol/inspector
위 명령어를 입력하면 MCP Inspector를 구동할 수 있습니다.
MCP Inspector를 처음 열면 나오는 첫 페이지입니다.
좌측을 보면 MCP Server를 연결시킬 방법이 나와있습니다.
Transport Type
MCP Server를 연결시킬 방식입니다.
STDIO, SSE, Streamable HTTP가 있습니다.
1. STDIO
STDIO는 말 그대로 로컬 환경에서 파일을 사용하여 연결하는 방식입니다.
윈도우는 python 명령어로 실행해도 상관없지만 Mac은 python3가 명령어라서 Command에 python3라고 입력해야합니다. argument는 파일, 여러 옵션 등 연결 옵션에 대한 정보를 기입합니다.
SSE, Streamable HTTP
SSE, Streamable HTTP 둘 다 URL과 Connection Type이 있습니다. Connection Type에는 viaProxy, Direct 두 종류가 있습니다.
이 외에도 Authentication, Configuration이 있는데 이는 Swagger와 유사하게 인증 토큰 및 프록시 정보에 대한 설정이므로 넘어가겠습니다.
연결
MCP 서버를 연결하면 Tool, Prompt 등 여러가지를 체크할 수 있는 화면이 나옵니다.
Resources
기능
- 서버가 제공하는 리소스 목록 조회
- 리소스 메타데이터 확인 (MIME type 등)
- 리소스 실제 내용 읽기
- 구독(Subscription) 테스트
- 리소스 변경 시 notification 수신 확인
용도
- 파일 시스템 MCP
- DB 스냅샷 리소스
- 문서 기반 컨텍스트 제공 서버
Prompts
기능
- Inspector에서 할 수 있는 것
- Prompt 템플릿 목록 조회
- 입력 인자 스키마 확인
- 인자 값 입력 후 메시지 렌더링 결과 미리보기
- role/content 구조 검증
- 변수 치환 오류 테스트
- 필수 인자 누락 테스트
- 메시지 배열 구조 오류 테스트
Tools
기능
- Tool 목록 확인
- JSON Schema 기반 입력 스키마 검증
- 직접 인자 넣고 호출
- 정상/에러 응답 확인
- 병렬 호출 테스트
- 가장 많이 사용하는 탭
- MCP 서버 개발 시 80%는 여기서 디버깅
Tasks
기능
- Task 생성
- 진행 상태 조회
- 완료/실패 상태 확인
- 취소 요청 테스트
Apps
MCP 기반 애플리케이션 단위 엔트리포인트
Ping
서버 생존 확인(Health Check)
주로 STDIO 디버깅할 때 사용
Sampling
서버가 클라이언트(LLM)에게 샘플링 요청을 하는 기능
Elicitations
사용자에게 추가 입력을 요청하는 상호작용 흐름
Agent 기반 UX에서 사용
Roots
서버가 접근 가능한 루트 컨텍스트 정의
ex)
- 허용된 파일 시스템 경로
- 특정 데이터 영역
- 보안/권한 관련 개념
Auth
기능
- 인증 플로우 테스트
- 토큰 교환 확인
Metadata
서버의 메타 정보
4. 테스트
탭이 너무 많아서 간단한 Tool 불러오는 테스트 화면만 설명하겠습니다.
//server.py
from fastmcp import FastMCP
# 1. 서버 인스턴스 생성
mcp = FastMCP("My First FastMCP Server 🚀")
# 2. @mcp.tool 데코레이터로 함수를 '도구'로 등록
@mcp.tool
def add(a: int, b: int) -> int:
"""두 숫자를 더합니다."""
return a + b
# 3. 서버 실행 (스크립트가 직접 실행될 때만)
if __name__ == "__main__":
mcp.run()
Tools에서 List Tools를 호출하면 server.py에 있는 Tool 리스트를 져옵니다. 이 중 테스트 하고 싶은 Tool을 선택해서 파라메터를 입력 후 Run Tool을 클릭하여 테스트를 진행할 수 있습니다.
5. MCP Inspector 체크 리스트
Inspector로 확인할 수 있는 체크리스트입니다.
-
연결 확인
[ ] 서버가 정상적으로 시작되는가?
[ ] 클라이언트와 서버 간 핸드셰이크가 성공하는가?
[ ] 서버 정보(이름, 버전)가 올바르게 표시되는가? -
도구 검증
[ ] 모든 도구가 목록에 나타나는가?
[ ] 도구 설명이 명확하고 이해하기 쉬운가?
[ ] 입력 스키마가 올바르게 표시되는가?
[ ] 필수 매개변수가 정확히 표시되는가? -
실행 테스트
[ ] 정상 케이스에서 도구가 올바르게 동작하는가?
[ ] 에러 케이스에서 적절한 오류 메시지가 반환되는가?
[ ] 응답 형식이 MCP 표준을 준수하는가?
6. 정리
오늘은 간단하게 MCP Inspector를 활용한 MCP Server 테스트 환경에 대해 알아보았습니다. 실제로 테스트 해보면서 편하다고 생각은 했는데 초기에 MCP 구현 방법에 대해 공부하고 Inspector에 대해 같이 공부하다보니 아직은 많이 부족한것 같습니다. 차차 프로젝트를 진행하면서 알게 된 내용들을 추가하면서 글을 추가해보려고 하겠습니다. 글 읽어주셔서 감사합니다 ㅎㅎ
