실제로 사용하려면, 서버를 클라이언트의 MCP 구성에 래핑하세요.```json
{
  "mcpServers": {
    "my-server": {
      "command": "mcpsnoop",
      "args": ["--", "node", "build/index.js"]
    }
  }
}

`wrap`는 `claude_desktop_config.json`을 찾아 이를
처음에 `claude_desktop_config.json.mcpsnoop.bak`으로 복사하고, 해당 서버 하나의 항목만
다시 작성하므로 나머지 서버와 서식은 그대로 유지됩니다.
다시 작성된 항목 내에서 키는 알파벳 순서로 돌아옵니다. `unwrap`은
파일을 복원하고, 더 이상 래핑된 서버가 없으면 백업을 제거합니다.
두 작업 후에는 Claude Desktop을 다시 시작하세요. MCP 서버는 시작 시 한 번만
실행되기 때문입니다.

그런 다음 평소처럼 클라이언트를 사용하고 UI를 엽니다.```bash
mcpsnoop

모든 응답의 HTTP 상태가 스트림에 표시되므로, 자체적으로 JSON-RPC 메시지를 담지 않은 응답도 아무것도 아닌 것이 아니라 보이는 프레임으로 남는다: 401 챌린지, 거부된 Origin에 대한 403, 알림을 확인하는 202, 그리고 대상에 전혀 도달할 수 없을 때의 502. 401의 `WWW-Authenticate` 헤더는 그대로 유지되어 인스펙터에 표시된다. 이 헤더는 인증 방식과 다음에 이동할 리소스 메타데이터를 명시하기 때문이다. TUI에서 `status:401`로 상태별 필터링하거나, `status:err`로 모든 실패를 필터링할 수 있다. 4xx 또는 5xx는 오류로 간주되므로, 기본 `mcpsnoop check` 실행은 해당 응답에서 실패한다.

자체 서버가 없으신가요? 공개된 테스트 서버를 대상으로 자신의 클라이언트를 사용해 [실제로 시도해 보세요](https://github.com/kerlenton/mcpsnoop/blob/HEAD/docs/TRY_IT.md). 세션이 끝난 후 이를 검사하려면 [로그에서 과거 세션 검토](https://github.com/kerlenton/mcpsnoop/blob/HEAD/docs/POST_MORTEM.md)를 참조하세요.

### 설정 파일

프로젝트 전반에 걸쳐 동일한 shim 플래그를 재사용한다면, 현재 작업 디렉터리의 `.mcpsnoop.toml` 파일에 넣으세요.```toml
label = "filesystem"
trace-file = "trace.jsonl"
redact-secrets = true
redact-key = "token,authorization"
redact-value = "sk-[A-Za-z0-9]+"
redact-path = "$.params.arguments.password"
no-trace = false

### Homebrew```bash
brew install mcpsnoop

`--older-than`는 필수이며(아무것도 삭제하는 기본값은 없습니다)
`30d` 같은 일수 또는 `72h` 같은 Go 기간을 허용합니다. 도구 기준선은
그대로 유지됩니다. 기준선은 세션이 아니라 서버 라벨을 기준으로 키가 지정되기 때문입니다.

실제 파이프 안에 있으며, Inspector처럼 옆에 붙어 있는 것이 아니므로
실제 클라이언트와 서버가 서로 주고받는 내용을 정확히 볼 수 있으며, 서버가
어떤 언어로 작성되었든지 간에 상관없습니다.

## 키 바인딩

| 키 | 동작 | | 키 | 동작 |
|---|---|---|---|---|
| `enter` | 검사 / 드릴다운 | | `/` | 필터 |
| `esc` | 뒤로 | | `:` | 명령 |
| `j` / `k` | 이동 | | `r` | 호출 재생 |
| `g` / `G` | 맨 위 / 맨 아래 | | `c` | 기능 |
| `ctrl-f` / `ctrl-b` | 페이지 | | `s` | 도구 요약 |
| `p` | 일시정지 | | `y` | 복사 |
| `shift`+`<key>` | 열 기준 정렬 | | `e` | 내보내기 |
| `ctrl-d` | 세션 삭제 | | `f` | 추적 |
| `?` | 도움말 | | | |

앱에서 `?`를 누르면 전체 목록을 볼 수 있습니다.

## 스트림 필터링

세션에서 `/`를 누르고 공백으로 구분된 토큰을 AND 조건으로 결합하세요. 일반 텍스트는
메서드, 도구, ID 및 페이로드와 일치합니다.

| 토큰 | 필터 기준 | 예시 |
|---|---|---|
| `tool:` | 도구 이름 | `tool:search` |
| `method:` | JSON-RPC 메서드 | `method:tools/call` |
| `id:` | 요청 ID 및 이를 이어가는 모든 재시도 | `id:7` |
| `task:` | 작업 ID | `task:01J...` |
| `dir:` | 방향 (`c2s`, `s2c`) | `dir:s2c` |
| `kind:` | 프레임 유형 (`req`, `resp`, `notify`, `stderr`, `invalid`) | `kind:invalid` |
| `status:` | 호출 결과 (`ok`, `error`, `cancel`, `late`, `cancelled`, `pending`, `bad`, `warn`, `mismatch`, 또는 `401` 같은 HTTP 상태 코드) | `status:error` |

토큰을 조합하면 원하는 대상을 정확히 지정할 수 있습니다.```text
tool:search status:pending        # in-flight calls to one search tool
status:cancel                     # calls the client gave up on (status:cancelled is a cancelled task)
status:late                       # results that arrived after the cancellation
method:tools/call status:error    # tool calls that failed
dir:s2c kind:req                  # server-initiated requests (servers before 2026-07-28)

| Format | What you get |
|---|---|
| `json` | 연관 호출, 도구별 개수 및 p50/p95/p99 지연 시간, 가장 느린 호출, 기능, 원시 프레임 |
| `html` | 검색 및 접을 수 있는 JSON을 지원하는 자체 포함 브라우저 파일 |
| `text` | 보기 좋은 순수 텍스트 덤프 |
| `har` | 연관 호출당 하나의 항목이 있으며, 브라우저 개발자 도구 및 HAR을 읽는 다른 도구에서 열 수 있음 |
| `otlp` | 연관 호출당 하나의 스팬이 있는 OTLP JSON. W3C 추적 컨텍스트는 호출자 추적을 연결하며, 그렇지 않으면 세션당 하나의 추적이 사용됨 |

MCP는 HTTP가 아니므로 HAR 항목의 URL, 상태 코드 및 타이밍은 의도적인
매핑이지 실제 유선 전송 기록이 아닙니다.

OTLP의 경우 요청의 `_meta.traceparent`는 해당 호출의 추적 및 상위
스팬 ID를 제공하며, `_meta.tracestate`는 스팬에 함께 전달됩니다. traceparent가
없거나 유효하지 않으면 mcpsnoop는 세션에서 파생된 추적을 유지하고 어떤 상태도 전달하지 않습니다.
mcpsnoop는 관여하지 않고 관찰만 하므로 자체 벤더 항목을 추가하지 않으며
호출자의 상태를 변경하지 않고 그대로 전달합니다.```bash
mcpsnoop export -T html -o out.html                    # an HTML file to open in a browser
mcpsnoop export -T text server.py-48213-7f3a1c9e2b04   # a specific session, as text
mcpsnoop export -T json | jq                           # the newest session, piped to jq
mcpsnoop export -T har -o session.har                  # a HAR file to open in browser devtools
mcpsnoop export -T otlp -o trace.json                  # import into an OTLP-compatible tracing backend

이 플래그들은 내보낸 파일 또는 메모리 내 TUI 뷰를 재작성하며, 소스 JSONL은 절대 변경하지 않습니다. `export`는 입력과 같은 파일을 출력으로 지정하는 것을 거부하며, 제자리로 이름이 바뀌는 임시 파일을 통해 작성하므로, 실패한 실행은 이전 파일을 그대로 유지합니다.

`tools/list` 결과에 표시되는 도구의 `inputSchema`와 `outputSchema`는 `--redact-key`와 `--redact-secrets`의 영향을 받지 않습니다. 스키마 내부의 이름은 값이 아닌 타입 선언이므로, 이름 자체는 어느 쪽이든 로그에 남으며, `token`이라는 속성 아래의 하위 스키마를 삭제하면 도구 자체의 검사도 함께 삭제됩니다. 예외는 해당 위치뿐이므로, 우연히 `inputSchema`라는 이름을 가진 인자는 다른 인자와 마찬가지로 삭제되며, 구조가 아닌 데이터를 담고 있는 `default`, `const`, `examples`, `enum`에서 중단됩니다. 스키마 내부의 특정 항목을 지정하려면 `--redact-path`를 사용하고, mcpsnoop이 파싱하는 `type`과 `x-mcp-header`라는 두 키워드를 제외한 모든 위치의 텍스트와 일치하는 `--redact-value`를 사용하세요.

각 플래그가 도달하는 범위는 다르므로, 가정하지 말고 결과를 확인하세요. 네 가지 모두 JSON-RPC 페이로드를 삭제하며, `--redact-key`, `--redact-path`, `--redact-secrets`는 오직 페이로드에만 도달합니다. `--redact-value`만이 stderr, 기타 비-JSON 텍스트, 문자열 내부까지 삭제합니다. `Mcp-Param-*` 헤더는 그것이 반영하는 본문 값과 함께 삭제되며, 다른 봉투 메타데이터, 서버 레이블, `Mcp-Name`, `Mcp-Method`, HTTP 상태는 캡처된 그대로 남습니다. 삭제는 최선 노력 방식이므로, 별도의 출력 경로를 사용하고 공유 전에 결과를 읽어보세요.

### 완료된 호출을 OTLP 수집기로 스트리밍

프록시가 실행되는 동안 OTLP/HTTP JSON 트레이스 엔드포인트를 가리켜 스팬을 전송하세요. 수집기 인증 또는 테넌트 헤더를 위해 `--otlp-header`를 반복하세요.```bash
mcpsnoop \
  --otlp-endpoint http://localhost:4318/v1/traces \
  --otlp-header "Authorization=Bearer $OTLP_TOKEN" \
  -- node build/index.js

mcpsnoop http \
  --target http://localhost:3000/mcp \
  --otlp-endpoint http://localhost:4318/v1/traces

이 보고서는 추가되거나 제거된 도구, 설명 및 `inputSchema` 변경 사항, 상태가 변경된 일치하는 도구 호출, 주목할 만한 소요 시간 변화를 보여줍니다. 호출은 도구 이름과 인수(argument)로 매칭되므로 순서가 바뀐 호출도 올바르게 비교됩니다. 기본적으로 소요 시간 변화는 최소 100ms 및 2배 이상 달라야 하며, `--duration-threshold`와 `--duration-ratio`로 해당 기준을 조정할 수 있습니다.

`--exit-code`를 전달하면 CI를 회귀(regression) 기준으로 게이트할 수 있습니다. after 세션이 도구를 제거하거나, 도구 설명, 제목, 입력 스키마, 출력 스키마 또는 어노테이션을 변경하거나, 상태가 악화된 호출이 있거나, 속도가 느려진 경우 0이 아닌 종료 코드를 반환합니다. 개선 사항(추가된 도구, 수정된 호출, 속도 향상)은 여전히 0으로 종료되며, 동작은 바꾸지 않고 도구의 모양만 바꾸는 아이콘 변경도 마찬가지로 0으로 종료됩니다.

## CI에서 세션 확인

기록된 에이전트 실행을 오류, 스트림 손상, 프로토콜 경고, 라우팅 헤더 불일치, 응답을 받지 못한 호출, 캡처를 불완전하게 남기는 드롭된 프레임, 도구 정의 드리프트 또는 더 이상 사용되지 않는 프로토콜 기능 사용을 기준으로 게이트합니다.```bash
mcpsnoop check [--format text|junit|sarif] [--fail-on error,invalid,warn,mismatch,pending,late-result,drift,deprecated,incomplete,schema] [session-id|log.jsonl|-]

드롭된 프레임 수는 아티팩트와 함께 전달되므로, 실제보다 적게 보고하는 캡처는 어디서 열어도 그 사실이 드러납니다: JSON 내보내기의 `missing_frames`, HAR의 `log.comment`, OTLP의 `mcpsnoop.session.missing_frames` 리소스 속성이 그것입니다.```bash
mcpsnoop check build-agent
mcpsnoop check --fail-on error,invalid artifacts/session.jsonl
mcpsnoop check --fail-on mismatch gateway-run.jsonl

### CI가 이미 확인하는 곳에 보고

`--format junit`은 신호 및 세션마다 하나의 `<testcase>`를 작성하며, 그 실패는
텍스트 출력과 동일한 `--fail-on` 선택을 따릅니다.```yaml
- name: Check captured MCP session
  run: |
    mkdir -p test-results
    mcpsnoop check --format junit artifacts/session.jsonl > test-results/mcpsnoop.xml
- name: Upload mcpsnoop JUnit report
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: mcpsnoop-junit
    path: test-results/mcpsnoop.xml

### 본문과 일치하지 않는 라우팅 헤더 감지

streamable-HTTP 전송에서 게이트웨이는 `Mcp-Method`와 `Mcp-Name`을 기준으로 라우팅하는 반면 서버는 본문을 읽으므로, 본문과 일치하지 않는 헤더는 두 주체가 서로 다른 요청을 보고 있음을 의미합니다. `mismatch` 신호는 이러한 경우, 주소를 지정할 수 없는 배치에 실려 오는 헤더, 그리고 필수 헤더가 완전히 누락된 경우를 포착합니다.

2026-07-28 기준으로 라우팅 헤더 누락은 검증 실패이며, 규격 준수 서버는 `400` 및 `-32020`으로 요청을 거부합니다. mcpsnoop은 세션이 해당 리비전 이상을 사용하는 것으로 확인된 경우에만 이를 발생시킵니다. 이전 리비전에서는 이러한 헤더가 전혀 정의되지 않았고, 그 환경에서 생략하는 것이 올바르기 때문입니다. 서버가 자체적으로 `-32020`으로 거부하는 경우도 동일한 신호로 간주됩니다.

HTTP 필드 값에 맞지 않는 이름이나 리소스 URI는 `=?base64?…?=` 센티널에 Base64로 실려 전송되며, 비교 전에 디코딩되므로 올바르게 인코딩하는 클라이언트는 결코 플래그로 표시되지 않습니다.

HTTP `tools/call` 요청에서 mcpsnoop은 각 `Mcp-Param-{Name}` 헤더도 표시하며, 일치하는 광고된 도구 정의가 알려진 경우 이를 주석이 달린 인수 경로와 비교합니다. 중첩 속성, Base64 센티널, 불리언 및 숫자와 동등한 안전 정수는 문자열 비교 오탐 없이 처리됩니다. 알 수 없는 파라미터 헤더와 일치하는 도구 정의가 없는 세션은 관찰용으로만 남습니다. 키 및 값 기반 마스킹(redaction)은 캡처된 파라미터 헤더 값이 sink에 도달하기 전에 적용되며, mcpsnoop이 스스로 마스킹한 값은 불일치로 보고되지 않습니다.

### 도구 정의 드리프트 감지

서버 라벨에 대해 관찰된 첫 번째 완전한 `tools/list`가 신뢰할 수 있는 기준선이 됩니다. 이후 세션에서는 해당 기준선을 필드별로 비교합니다: 설명, 제목, 입력 및 출력 스키마, 주석과 아이콘, 그리고 추가되거나 제거된 도구까지 포함합니다. 주석이 가장 중요합니다. `readOnlyHint`로 승인된 도구가 나중에 자신을 파괴적이라고 선언하는 것이 바로 이 검사가 존재하는 이유인 rug-pull(뒤통수 치기)이기 때문이며, 스펙은 클라이언트에게 주석을 신뢰할 수 없는 것으로 취급하라고 지시합니다. 제목과 아이콘은 사용자가 보는 것이므로 추적되며, 스펙은 도구의 `title`을 `annotations.title` 및 이름보다 우선시합니다. sessions 테이블과 도구 요약은 MCP 트래픽을 차단하거나 변경하지 않고 드리프트를 플래그로 표시합니다.

주석은 스펙 기본값을 통해 비교되므로, 이미 의존하고 있던 힌트를 명시적으로 표기하기 시작한 서버는 보고되지 않습니다. mcpsnoop이 필드를 추적하기 전에 기록된 기준선은 기록된 필드에 대해서는 계속 작동하며, 답할 수 없는 필드가 무엇인지도 알려줍니다. 현재 정의를 신뢰하게 되면 `mcpsnoop baseline --accept`로 다시 기록하세요.

마스킹이 기록하는 내용을 변경하면 드리프트가 비교하는 내용도 변경됩니다. `--redact-value` 없이 기록한 기준선을 `--redact-value`로 캡처한 결과와 비교하면 마스킹된 필드가 변경된 것으로 보고되는데, 이는 올바른 동작입니다. 기록된 정의가 실제로 변경되었기 때문입니다. 마스킹 설정을 변경한 후에는 `--accept`로 다시 기록하세요.

명령 이름이나 대상 호스트가 충돌할 수 있는 각 서버에는 안정적이고 고유한 `--label`을 사용하세요. 기준선은 일반적인 mcpsnoop 상태 디렉터리에 저장되므로 `MCPSNOOP_HOME` 및 `XDG_STATE_HOME`이 적용됩니다.```bash
mcpsnoop check --fail-on drift session.jsonl
mcpsnoop baseline session.jsonl
mcpsnoop baseline --accept session.jsonl  # trust a legitimate definition change
mcpsnoop baseline --reset session.jsonl   # trust the next complete tools/list

`drift`는 `check`에 대해 옵트인(opt-in) 방식입니다. 기본 `error,invalid,warn` 게이트는 변경되지 않습니다.

### 폐기 예정 프로토콜 기능 플래그 지정

2026-07-28 개정판에서는 Roots, Sampling, Logging을 폐기 예정(deprecated)으로 지정합니다. 이 기능들은 최소 1년간 계속 작동하므로, mcpsnoop은 이를 오류로 취급하는 대신 플래그로 표시합니다. 스트림, 기능 검사기, 내보내기 모두 이들을 플래그로 표시하며, 각 플래그는 대체 항목을 명시합니다.

세 기능 중 두 가지는 이제 다중 왕복 요청을 통해서만 접근할 수 있으며, 메서드 이름은 프레임 자체가 아닌 서버의 `inputRequests` 맵 안에 있습니다. 이러한 경우도 플래그로 표시되므로, 새 패턴으로 전환한 서버도 조용히 보고를 중단하지 않습니다.```bash
mcpsnoop check --fail-on deprecated session.jsonl

이 열은 경고 색상을 띠며 ERR 열의 빨간색을 사용하지 않습니다. mcpsnoop는 여전히 전달하는 트래픽을 변경하지 않습니다.

아무것도 해석되거나 가져오지 않습니다. 외부 `$ref`는 형태만으로 인식되며, 그것이 가리키는 스키마는 결코 읽히지 않습니다.

### 컨텍스트에서 서버가 얼마나 비용을 발생시키는지 확인하기

도구 정의는 매 대화마다 모델의 컨텍스트에 들어가고, 도구 결과는 매 호출마다 들어갑니다. 도구 요약(`s`)은 실제로 캡처한 세션에서 두 가지를 모두 측정합니다.

`definitions` 줄은 고정 비용입니다. 단 한 번의 호출이 이루어지기 전에 이 서버의 `tools/list`가 차지하는 비용입니다. `DEF` 열은 이를 도구별로 세분화하며, `RESULT`는 지금까지 각 도구의 응답이 발생시킨 비용입니다. 테이블은 오류와 지연 시간 순으로 정렬되므로 `DEF`를 훑어 비용이 많이 드는 정의를 찾으십시오. 내보내기에서는 가장 무거운 것이 먼저 나열됩니다. 테이블 아래의 한 줄은 합계로는 숨겨지는 가장 무거운 단일 결과를 명명합니다.

정의 수치는 의미 없는 공백이 제거된 JSON이므로, `tools/list`를 pretty-print하는 서버가 그렇지 않은 서버보다 더 비싼 것으로 계산되지 않으며, 동일한 서버는 캡처 간에도 동일하게 측정됩니다. `RESULT`는 도착한 그대로의 바이트입니다. 결과는 정규화할 가치가 있는 계약이라기보다 일회성 페이로드입니다.```bash
mcpsnoop export -T json | jq '.summary.definitions'

소켓은 원격의 상태 디렉터리 아래에 있으며, `MCPSNOOP_HOME`,
다음으로 `XDG_STATE_HOME/mcpsnoop`, 다음으로 `~/.local/state/mcpsnoop` 순서로 확인됩니다. 기본적으로 mcpsnoop은
`user@host`에서 Linux 홈 `/home/<user>`를 가정하며, 해당 추측으로 대체될 때마다
stderr에 알림을 출력합니다. 원격이 다른 경로로 확인되면,
기본값이 아닌 해당 항목을 지정하세요.```bash
# a non-Linux or custom home, macOS is /Users/<user> and root is /root
mcpsnoop remote --remote-home /Users/remote-user remote-user@remote-host

# an explicit MCPSNOOP_HOME on the remote
mcpsnoop remote --remote-mcpsnoop-home /srv/mcpsnoop remote-user@remote-host

# an explicit XDG_STATE_HOME on the remote
mcpsnoop remote --remote-xdg-state-home /var/lib/state remote-user@remote-host

대신 로컬 사본을 유지하려면, 로그를 세션 디렉토리로 scp하고
TUI를 평소처럼 실행하세요.```bash
# copy the remote logs into your local sessions directory
mkdir -p ~/.local/state/mcpsnoop/sessions
scp remote-user@remote-host:'~/.local/state/mcpsnoop/sessions/*.jsonl' \
  ~/.local/state/mcpsnoop/sessions/

# open the TUI, it backfills the copied sessions
mcpsnoop

원격 워크플로우의 경우 SSH 터널링 또는 SSH 파일 전송을 사용하여 전송 인증,
암호화, 호스트 검증, 키 교체, 감사 정책이 기존 SSH 설정에 유지되도록
하십시오.

## 기여

이슈와 풀 리퀘스트를 환영합니다. 자세한 내용은 [CONTRIBUTING.md](https://github.com/kerlenton/mcpsnoop/blob/HEAD/CONTRIBUTING.md)를
참조하세요.

## 라이선스

[MIT](https://github.com/kerlenton/mcpsnoop/blob/HEAD/LICENSE)