mcpsnoop: MCP 트래픽 디버깅을 위한 투명 프록시 및 TUI
mcpsnoop: MCP 트래픽 디버깅을 위한 투명 프록시 및 TUI
mcpsnoop는 투명 프록시 역할을 하여 AI 클라이언트(Claude Desktop, Cursor, Claude Code 등)와 Model Context Protocol(MCP) 서버 간의 통신을 실시간으로 가시화합니다. 기존의 인스펙터가 별도의 클라이언트로 연결되는 것과 달리, mcpsnoop는 데이터 경로에 직접 위치해 도구 호출, 응답, 알림을 발생하는 즉시 캡처합니다.
MCP 가시성 격차 해소
MCP 서버 디버깅의 주요 과제는 공식 도구인 MCP Inspector와 같은 것이 독립적인 클라이언트로 동작한다는 점입니다. 즉, 실제 AI 클라이언트가 생성하는 트래픽을 볼 수 없습니다. 도구가 트리거되지 않거나, 기능이 맞지 않거나, 요청이 멈출 때 개발자는 /tmp에서 로그를 수동으로 tail하고 추측에 의존할 수밖에 없습니다.
mcpsnoop는 서버 명령을 래핑함으로써 이 격차를 없앱니다. 클라이언트와 서버 사이의 바이트를 그대로 전달하면서 동시에 모든 JSON‑RPC 프레임의 복사본을 실시간 터미널 UI에 스트리밍합니다. 이를 통해 개발자는 실제 클라이언트가 보내는 내용과 서버가 반환하는 내용을 정확히 확인할 수 있습니다.
핵심 기능 및 디버깅 역량
실시간 트래픽 모니터링 및 분석
mcpsnoop는 요청, 응답, 알림을 포함한 JSON‑RPC 프레임을 색상으로 구분된 실시간 스트림으로 제공합니다. 주요 모니터링 기능은 다음과 같습니다:
- Hung‑Call 감지: 진행 중인 요청은
PENDING으로 표시되고 실시간 타이머가 표시되어 멈춘 도구를 즉시 파악할 수 있습니다. - 오류 플래그: 표준 JSON‑RPC 오류와 도구 수준
result.isError플래그를 모두 표시합니다. - 프레임 검사:
enter키를 눌러任意의 프레임을 확장하면 깔끔하게 포맷된 JSON과 전체 텍스트 검색 기능을 사용할 수 있습니다. - Capability 검사:
c키를 눌러 초기 핸드쉐이크 시 클라이언트와 서버가 합의한 정확한 capability를 확인할 수 있습니다.
재생을 통한 빠른 반복
mcpsnoop의 가장 강력한 기능 중 하나는 캡처된 도구 호출을 새롭고 격리된 서버 인스턴스에 다시 실행할 수 있다는 점입니다. 이를 통해 개발자는 AI 클라이언트를 통해 동작을 다시 트리거하지 않고도 도구 로직을 반복적으로 테스트할 수 있습니다.
고급 필터링
대용량 트래픽을 관리하기 위해 mcpsnoop는 쿼리 기반 필터링 시스템을 지원합니다. 사용자는 공백으로 구분된 토큰을 조합해 스트림을 좁힐 수 있습니다:
- 필드별 필터:
tool:,method:,id:,kind:,dir:,status:등. - 예시:
tool:search status:slow와 같은 쿼리는 검색 도구에 대해 느리게 수행된 호출만을 분리합니다.
아키텍처 및 구현
mcpsnoop는 두 가지 뚜렷한 역할을 가진 단일 바이너리로 구현됩니다:
- Shim:
mcpsnoop -- <server>형태로 실행될 때 AI 클라이언트가 생성하는 투명 프록시 역할을 합니다. - Hub/TUI: 인자를 주지 않고
mcpsnoop만 실행하면 터미널 인터페이스를 시작합니다.
이 두 구성 요소는 잘 알려진 소켓과 디스크 로그를 통해 통신합니다. TUI가 디스크에서 과거 세션을 백필(backfill)하기 때문에 UI는 AI 클라이언트 시작 전이나 후에 열 수 있습니다.
스트리밍 가능한 HTTP 서버의 경우, 다음 명령으로 역방향 프록시로 동작할 수 있습니다:
mcpsnoop http --target http://localhost:3000/mcp --listen :7000
다른 MCP 도구와의 비교
| Feature | MCP Inspector | mcp-trace | mcpsnoop |
|---|---|---|---|
| 실제 클라이언트‑서버 트래픽 확인 | No | Yes | Yes |
| 인터랙티브 터미널 UI | No | Yes | Yes |
| Zero-config / No flags | No | No | Yes |
| Capability 인스펙터 | Partial | No | Yes |
| 캡처된 호출 재생 | No | No | Yes |
| 단일 바이너리 (런타임 의존성 없음) | No | Varies | Yes |
설치
mcpsnoop는 Go, Homebrew 또는 사전 빌드된 바이너리를 통해 설치할 수 있습니다:
- Go:
go install github.com/kerlenton/mcpsnoop/cmd/mcpsnoop@latest - Homebrew:
brew tap kerlenton/mcpsnoop && brew install mcpsnoop
커뮤니티 인사이트
이 도구는 AI 클라이언트 워크플로우에서 중요한 시각화 격차를 메워준다는 평가를 받지만, 커뮤니티 토론에서는 향후 성장 가능성을 시사하는 의견도 있습니다:
"원격 디버깅 및 사후 디버깅 지원이 유용할 수 있습니다. 많은 AI 감사 프록시가 존재합니다... 예를 들어 Aegis와 LiteLLM은 실행 전 방화벽 역할을 하며 암호화된 감사 추적을 추가합니다."
다른 사용자들은 데이터 탐색을 위한 브라우저 기반 인터페이스를 추가하거나, Wireshark 자체를 위한 MCP 서버를 만들어 프로토콜에 네트워크 분석을 더욱 통합하는 방안을 제안했습니다.