mcpsnoop — AI 에이전트 개발

최신 도구 가이드 / AI 에이전트 개발 / mcpsnoop.html

MCP(Model Context Protocol) 통신 내용을 실시간으로 살펴보고 분석하는 AI 에이전트 개발 도구입니다.

기본 정보

이 프로그램은 무엇인가?

mcpsnoop는 AI 에이전트와 MCP(Model Context Protocol) 서버 사이의 통신을 중간에서 캡처해 분석하는 개발 도구입니다. MCP 서버와 클라이언트 사이에 프록시로 동작하여, 툴 호출·리소스 요청·알림 메시지를 사람이 읽기 쉬운 형태로 표시합니다.

MCP 기반 에이전트를 개발할 때 어떤 도구가 호출됐고, 어떤 파라미터가 전달됐으며, 서버가 어떤 응답을 돌려줬는지 확인하는 것이 핵심 디버깅 작업입니다. mcpsnoop는 이 흐름을 실시간으로 기록하고, 필터링·검색·재생 기능을 제공합니다.

어떤 문제를 해결하는가?

• ('에이전트 디버깅에서', '에이전트가 어떤 MCP 도구를 호출하는지 모르겠을 때', '프록시 캡처에서 도구 호출 목록과 파라미터를 확인할 수 있습니다.')
• ('서버 개발에서', 'MCP 서버가 올바른 응답을 돌려주는지 검증이 필요할 때', '요청-응답 쌍을 나란히 표시해 스키마·타입 오류를 찾을 수 있습니다.')
• ('통합 테스트에서', 'MCP 통신을 자동화 테스트에 포함시켜야 할 때', '캡처된 통신을 JSON으로 내보내 재생(replay) 테스트에 활용할 수 있습니다.')

주요 기능

프록시 캡처

MCP 클라이언트·서버 사이에 프록시를 두고 통신을 캡처

• 활용 상황: 에이전트-서버 통신 분석
• 얻는 결과: 서버 수정 없이 통신 내용 확인
• 제한 사항: MCP 서버가 프록시 인증서를 요구하면 설정 추가 필요.

툴 호출 추적

툴 호출·리소스 읽기·알림을 타임라인으로 시각화

• 활용 상황: 에이전트 행동 흐름 파악
• 얻는 결과: 어떤 도구가 어떤 순서로 호출됐는지 시각적으로 확인
• 제한 사항: 고빈도 호출 시 타임라인이 밀집할 수 있습니다.

JSON 내보내기·재생

캡처한 통신을 JSON으로 저장하고 재생

• 활용 상황: 회귀 테스트·공유
• 얻는 결과: MCP 서버 변경 후 통신 호환성 검증
• 제한 사항: 재생 시 실제 서버 호출이 발생하지 않으므로 외부 효과 주의.

필터·검색

툴 이름·파라미터·응답 내용으로 실시간 필터

• 활용 상황: 대량 트래픽에서 관련 통신만 추출
• 얻는 결과: 원하는 통신을 빠르게 찾기
• 제한 사항: 정규식 필터는 CPU를 많이 쓸 수 있습니다.

설치 및 실행

Node.js (npm)

npm으로 전역 설치합니다.

npm install -g mcpsnoop
mcpsnoop --version

Python (pip)

Python 환경에서는 pip로 설치합니다.

pip3 install mcpsnoop

소스 빌드

소스에서 빌드할 때 Node.js 18+ 필요.

git clone https://github.com/mcpsnoop-dev/mcpsnoop
cd mcpsnoop
npm install
npm run build

실제 사용 예제

프록시 모드로 실행

MCP 서버를 프록시로 감싸 캡처를 시작합니다.

$ mcpsnoop --proxy --server "npx @modelcontextprotocol/server-filesystem /data" --port 9229

[mcpsnoop] proxy listening on :9229
[mcpsnoop] MCP server attached: filesystem
[mcpsnoop] ready — connect your client to localhost:9229

툴 호출 확인

캡처된 툴 호출을 실시간으로 확인합니다.

[tool.call]  read_file  {"path": "/data/config.yaml"}
[tool.result] 200 OK  (128 bytes, 3ms)
[tool.call]  list_directory  {"path": "/data"}
[tool.result] 200 OK  (14 entries, 5ms)

캡처 저장·재생

캡처를 JSON으로 저장하고 나중에 재생합니다.

$ mcpsnoop --save session.json
$ mcpsnoop --replay session.json --server mock://filesystem
# 재생 완료: 24 calls, 0 errors

장점과 한계

장점

• 서버 수정 없이 프록시 방식으로 MCP 통신 캡처
• 툴 호출·응답을 사람이 읽기 쉬운 타임라인으로 시각화
• JSON 내보내기·재생으로 회귀 테스트 지원
• Node.js·Python 양쪽 설치 방법 지원

사용 전에 고려할 점

• MCP 사양이 빠르게 변경되어 최신 프로토콜 기능 반영이 늦을 수 있습니다.
• 프록시 경유 시 약간의 지연이 추가됩니다(보통 수 ms).
• 대량 통신 캡처 시 메모리 사용량 관리 필요.

비슷한 프로그램과 비교

공식 자료 및 추가 학습

• 공식 홈페이지 — https://mcpsnoop.dev/
• 공식 문서 / 지식베이스 — https://mcpsnoop.dev/docs/
• 공식 다운로드 — https://mcpsnoop.dev/downloads
• 릴리스 노트 — https://mcpsnoop.dev/changelog
• 소스 / 개발 자료 — https://github.com/kerlenton/mcpsnoop

버전·지원 환경 정보는 2026-10-18 기준으로 공식 사이트에서 확인한 값입니다. 설치 명령은 사용하는 배포판과 버전에 따라 달라질 수 있으므로 공식 설치 문서를 함께 확인하세요.

실제 실행 화면

아래는 사용 흐름을 이해하기 위해 만든 합성 예시 화면입니다(실제 실행 결과 아님). 화면은 합성 예시이며 실제 실행 결과가 아닙니다.

실제 운영 중인 서버

이 문서는 화면 표시용 가상 디렉터리의 항목입니다. 실제 서버 파일시스템과 연결되지 않으며, 파일 실행이나 시스템 명령을 수행하지 않습니다.