Pour l'utiliser pour de vrai, enveloppez votre serveur dans la config MCP de votre client.```json
{
  "mcpServers": {
    "my-server": {
      "command": "mcpsnoop",
      "args": ["--", "node", "build/index.js"]
    }
  }
}

`wrap` trouve `claude_desktop_config.json`, le copie vers
`claude_desktop_config.json.mcpsnoop.bak` la première fois, et réécrit uniquement
l'entrée de ce serveur, afin que votre mise en forme et tous les autres serveurs soient laissés intacts.
Dans l'entrée réécrite, les clés reviennent dans l'ordre alphabétique. `unwrap`
restaure le fichier et supprime la sauvegarde une fois qu'aucun serveur n'est plus enveloppé.
Redémarrez Claude Desktop après l'une ou l'autre opération, car les serveurs MCP sont lancés une seule fois au
démarrage.

Ensuite, utilisez votre client comme d'habitude et ouvrez l'interface.```bash
mcpsnoop

Le statut HTTP de chaque réponse apparaît dans le flux, de sorte qu'une réponse qui ne porte
aucun message JSON-RPC qui lui soit propre reste une trame visible plutôt que rien : le
défi 401, le 403 sur une Origin rejetée, le 202 qui accuse réception d'une
notification, et le 502 lorsque la cible est totalement injoignable. L'en-tête
`WWW-Authenticate` d'un 401 est conservé tel quel et affiché dans l'inspecteur, car il
nomme le schéma d'authentification et les métadonnées de ressource à consulter ensuite. Filtrez par statut
avec `status:401` dans la TUI, ou par toute erreur avec `status:err`. Un 4xx ou 5xx
est considéré comme une erreur, donc une exécution par défaut de `mcpsnoop check` échoue dessus.

Pas de serveur à vous ? [Essayez pour de vrai](https://github.com/kerlenton/mcpsnoop/blob/HEAD/docs/TRY_IT.md) contre un serveur de test
publié, piloté par votre propre client. Pour inspecter une session après coup,
voir [examiner les sessions passées à partir des journaux](https://github.com/kerlenton/mcpsnoop/blob/HEAD/docs/POST_MORTEM.md).

### Fichier de configuration

Si vous réutilisez les mêmes options shim dans un projet, placez-les dans un
fichier `.mcpsnoop.toml` dans le répertoire de travail courant.```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` est requis (il n'y a pas de valeur par défaut qui supprimerait quoi que ce soit) et
accepte un nombre de jours comme `30d` ou une durée Go comme `72h`. Les baselines d'outils ne sont pas touchées,
car une baseline est identifiée par l'étiquette du serveur plutôt que par la session.

Comme il se trouve dans le flux réel, pas sur le côté comme l'Inspector, il
voit exactement ce que votre client réel et votre serveur se disent, quel que soit
le langage dans lequel le serveur est écrit.

## Raccourcis clavier

| Touche | Action | | Touche | Action |
|---|---|---|---|---|
| `enter` | inspecter / approfondir | | `/` | filtrer |
| `esc` | retour | | `:` | commande |
| `j` / `k` | déplacer | | `r` | rejouer un appel |
| `g` / `G` | haut / bas | | `c` | capacités |
| `ctrl-f` / `ctrl-b` | page | | `s` | résumé d'outil |
| `p` | pause | | `y` | copier |
| `shift`+`<key>` | trier par colonne | | `e` | exporter |
| `ctrl-d` | supprimer la session | | `f` | suivre |
| `?` | aide | | | |

Appuyez sur `?` dans l'application pour la liste complète.

## Filtrer le flux

Appuyez sur `/` dans une session et combinez des jetons séparés par des espaces, avec ET logique. Le texte brut
correspond à la méthode, à l'outil, à l'identifiant et à la charge utile.

| Jeton | Filtre par | Exemple |
|---|---|---|
| `tool:` | nom de l'outil | `tool:search` |
| `method:` | méthode JSON-RPC | `method:tools/call` |
| `id:` | identifiant de requête, et toute nouvelle tentative qui le poursuit | `id:7` |
| `task:` | identifiant de tâche | `task:01J...` |
| `dir:` | direction (`c2s`, `s2c`) | `dir:s2c` |
| `kind:` | type de trame (`req`, `resp`, `notify`, `stderr`, `invalid`) | `kind:invalid` |
| `status:` | résultat de l'appel (`ok`, `error`, `cancel`, `late`, `cancelled`, `pending`, `bad`, `warn`, `mismatch`, ou un statut HTTP comme `401`) | `status:error` |

Empilez les jetons pour affiner.```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 | Ce que vous obtenez |
|---|---|
| `json` | appels corrélés, compteurs par outil et latence p50/p95/p99, appels les plus lents, capacités et trames brutes |
| `html` | un fichier autonome pour navigateur avec recherche et JSON repliable |
| `text` | un dump en texte brut lisible |
| `har` | une entrée par appel corrélé, ouvrable dans les devtools du navigateur et tout autre outil lisant le HAR |
| `otlp` | OTLP JSON avec une span par appel corrélé ; le contexte de trace W3C relie les traces de l'appelant, sinon une trace est utilisée par session |

MCP n'est pas HTTP, donc l'URL, le code de statut et les durées d'une entrée HAR sont un mapping
volontaire de chaque appel plutôt qu'une transcription sur le fil.

Pour OTLP, le `_meta.traceparent` d'une requête fournit la trace de cet appel et les IDs de span
parente, et `_meta.tracestate` accompagne la span. Lorsque le traceparent est
absent ou invalide, mcpsnoop conserve la trace dérivée de la session et ne transporte aucun état.
mcpsnoop observe plutôt qu'il ne participe, donc il n'ajoute aucune entrée fournisseur propre
et transmet l'état de l'appelant sans modification.```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

Ces drapeaux réécrivent le fichier exporté ou la vue TUI en mémoire, jamais le JSONL source. `export` refuse une sortie qui nomme le même fichier que son entrée, et écrit via un fichier temporaire renommé en place, si bien qu'une exécution qui échoue laisse le fichier précédent intact.

Les `inputSchema` et `outputSchema` d'un outil, tels qu'annoncés dans un résultat `tools/list`, ne sont pas touchés par `--redact-key` et `--redact-secrets`. Un nom dans un schéma est une déclaration de type plutôt qu'une valeur ; le nom lui-même reste de toute façon dans le journal, et masquer le sous-schéma sous une propriété appelée `token` emporterait avec lui les propres vérifications de l'outil. L'exemption ne vaut que pour cette position, donc un argument qui s'appelle par hasard `inputSchema` est masqué comme n'importe quel autre, et cela s'arrête à `default`, `const`, `examples` et `enum`, qui contiennent des données plutôt que de la structure. Utilisez `--redact-path` pour nommer quelque chose dans un schéma, ou `--redact-value`, qui correspond au texte où qu'il se trouve, sauf dans les deux mots-clés que mcpsnoop analyse, `type` et `x-mcp-header`.

Ce que chaque drapeau atteint diffère, donc vérifiez le résultat plutôt que de supposer. Les quatre masquent les charges utiles JSON-RPC, et `--redact-key`, `--redact-path` et `--redact-secrets` n'atteignent que celles-ci. Seul `--redact-value` masque aussi stderr, les autres textes non JSON et l'intérieur d'une chaîne. Un en-tête `Mcp-Param-*` est masqué en même temps que la valeur du corps qu'il reflète ; les autres métadonnées d'enveloppe, les étiquettes de serveur, `Mcp-Name`, `Mcp-Method` et le statut HTTP restent tels que capturés. Le masquage est effectué dans la mesure du possible, utilisez donc un chemin de sortie séparé et lisez le résultat avant de le partager.

### Diffuser les appels terminés vers un collecteur OTLP

Envoyez des spans pendant que le proxy est en cours d'exécution en le pointant vers un point de terminaison de traces JSON OTLP/HTTP. Répétez `--otlp-header` pour l'authentification du collecteur ou les en-têtes de locataire.```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

Le rapport montre les outils ajoutés ou supprimés, les modifications de description
et de `inputSchema`, les appels d'outils correspondants dont le statut a changé, et
les changements notables de durée. Les appels sont appariés par nom d'outil et par
arguments, donc les appels réordonnés se comparent toujours correctement.
Par défaut, les changements de durée doivent différer d'au moins 100 ms et d'un
facteur 2 ; utilisez `--duration-threshold` et `--duration-ratio` pour ajuster ces
seuils.

Passez `--exit-code` pour faire échouer la CI en cas de régressions : elle se termine
avec un code non nul lorsque la session « après » supprime un outil, modifie la
description d'un outil, le titre, le schéma d'entrée, le schéma de sortie ou les
annotations, contient un appel dont le statut s'est dégradé, ou ralentit. Les
améliorations (outils ajoutés, appels corrigés, accélérations) se terminent toujours
par zéro, de même qu'un changement d'icône, qui modifie l'apparence d'un outil sans
changer ce qu'il fait.

## Vérification des sessions dans la CI

Bloquez une session d'agent enregistrée en cas d'erreurs, de corruption du flux,
d'avertissements de protocole, d'incohérences d'en-tête de routage, d'appels sans
réponse, de trames perdues laissant la capture incomplète, de dérive des définitions
d'outils ou d'utilisation de fonctionnalités de protocole obsolètes.```bash
mcpsnoop check [--format text|junit|sarif] [--fail-on error,invalid,warn,mismatch,pending,late-result,drift,deprecated,incomplete,schema] [session-id|log.jsonl|-]

Le nombre de trames perdues voyage aussi avec les artefacts, de sorte qu'une capture qui
se sous-estime le dit partout où elle est ouverte : `missing_frames` dans l'export JSON,
`log.comment` dans HAR, et l'attribut de ressource `mcpsnoop.session.missing_frames`
dans OTLP.```bash
mcpsnoop check build-agent
mcpsnoop check --fail-on error,invalid artifacts/session.jsonl
mcpsnoop check --fail-on mismatch gateway-run.jsonl

### Signalez-le là où la CI cherche déjà

`--format junit` écrit un `<testcase>` par signal et par session, et ses échecs
suivent la même sélection `--fail-on` que la sortie texte.```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

### Détecter un en-tête de routage en désaccord avec le corps

Sur le transport HTTP streamable, une passerelle route en fonction de `Mcp-Method` et `Mcp-Name` pendant que le serveur lit le corps ; un en-tête en désaccord avec le corps signifie donc que les deux regardent deux requêtes différentes. Le signal `mismatch` couvre ce cas, ainsi qu'un en-tête porté par un lot qu'il ne peut pas adresser et un en-tête obligatoire entièrement absent.

Dans la révision 2026-07-28, un en-tête de routage manquant est une erreur de validation, et un serveur conforme rejette la requête avec `400` et `-32020`. mcpsnoop ne le signale que lorsque la session est connue pour parler cette révision ou une révision ultérieure, car les révisions antérieures ne définissent pas du tout ces en-têtes et les omettre y est correct. Le rejet `-32020` émis par un serveur compte comme le même signal.

Un nom ou un URI de ressource qui ne tient pas dans une valeur de champ HTTP transite en Base64 dans une sentinelle `=?base64?…?=`, qui est décodée avant la comparaison, de sorte qu'un client qui encode correctement n'est jamais signalé.

Sur les requêtes HTTP `tools/call`, mcpsnoop affiche également chaque en-tête `Mcp-Param-{Name}` et, lorsque la définition d'outil annoncée correspondante est connue, la compare au chemin d'argument annoté. Les propriétés imbriquées, la sentinelle Base64, les booléens et les entiers sûrs équivalents numériquement sont traités sans faux positifs de comparaison de chaînes. Les en-têtes de paramètres inconnus et les sessions sans définition d'outil correspondante restent observationnels. La rédaction par clé et par valeur s'applique aux valeurs d'en-têtes de paramètres capturées avant qu'elles n'atteignent un puits, et une valeur que mcpsnoop a lui-même masquée n'est jamais signalée comme un désaccord.

### Détecter la dérive des définitions d'outils

Le premier `tools/list` complet observé pour un label de serveur devient sa référence de confiance. Les sessions ultérieures comparent cette référence champ par champ : la description, le titre, les schémas d'entrée et de sortie, les annotations et les icônes, ainsi que les outils ajoutés ou supprimés. Les annotations sont ce qui compte le plus, car un outil approuvé avec `readOnlyHint` qui se déclare ensuite destructif est le piège que ce contrôle existe pour démasquer, et la spécification demande aux clients de traiter les annotations comme non fiables. Le titre et les icônes sont suivis parce que ce sont eux que l'utilisateur voit, et la spécification classe le `title` d'un outil au-dessus de `annotations.title` et de son nom. La table des sessions et le résumé des outils signalent la dérive sans bloquer ni modifier le trafic MCP.

Les annotations sont comparées via leurs valeurs par défaut de la spécification, de sorte qu'un serveur qui commence à expliciter une indication sur laquelle il s'appuyait déjà n'est pas signalé. Une référence enregistrée avant que mcpsnoop ne suive un champ continue de fonctionner pour les champs qu'elle enregistre et indique ceux auxquels elle ne peut pas répondre ; réenregistrez avec `mcpsnoop baseline --accept` une fois que vous faites confiance aux définitions actuelles.

Modifier ce que la rédaction enregistre change ce que la dérive compare. Une référence prise sans `--redact-value` puis vérifiée contre une capture prise avec cette option signale les champs masqués comme modifiés, ce qui est correct, puisque la définition enregistrée a réellement changé. Réenregistrez avec `--accept` après avoir modifié les paramètres de rédaction.

Utilisez un `--label` stable et unique pour chaque serveur dont le nom de commande ou l'hôte cible entrerait sinon en collision. Les références sont stockées dans le répertoire d'état habituel de mcpsnoop, donc `MCPSNOOP_HOME` et `XDG_STATE_HOME` s'appliquent.```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` est en option pour `check` ; le filtre par défaut `error,invalid,warn` reste inchangé.

### Signaler les fonctionnalités de protocole dépréciées

La révision du 2026-07-28 déprécie Roots, Sampling et Logging. Elles continuent de fonctionner
pendant au moins un an, donc mcpsnoop les signale plutôt que de les traiter comme des erreurs.
Le flux, l'inspecteur de capacités et l'exportation les signalent tous, et chaque marqueur
indique le remplacement.

Deux des trois ne sont désormais accessibles que via une requête multi-allers-retours, où
le nom de la méthode se trouve dans la map `inputRequests` du serveur plutôt que sur la
trame elle-même. Ces deux-là sont également signalés, afin qu'un serveur ayant adopté le
nouveau modèle ne cesse pas silencieusement de signaler.```bash
mcpsnoop check --fail-on deprecated session.jsonl

La colonne porte la couleur d'avertissement et jamais le rouge de la colonne ERR, et
mcpsnoop ne change toujours rien au trafic qu'il relaie.

Rien n'est résolu ni récupéré. Un `$ref` externe est reconnu par sa seule forme,
et le schéma vers lequel il pointe n'est jamais lu.

### Voyez ce que le serveur vous coûte en contexte

Les définitions d'outils entrent dans le contexte du modèle à chaque conversation, et les
résultats d'outils à chaque appel. Le résumé d'outil (`s`) mesure les deux à partir de la session
que vous avez réellement capturée.

La ligne `definitions` est le coût fixe : ce que pèse le `tools/list` de ce serveur
avant qu'un seul appel ne soit effectué. La colonne `DEF` détaille cela par
outil et `RESULT` correspond à ce que les réponses de chaque outil ont coûté jusqu'à présent. Le tableau reste
trié par erreurs et latence, alors parcourez `DEF` pour trouver les définitions coûteuses ;
l'export les classe des plus lourdes aux plus légères. Une ligne sous le tableau désigne le résultat
le plus lourd, qu'un total masque.

Les chiffres de définition correspondent au JSON dont les espaces blancs insignifiants ont été supprimés, donc un
serveur qui met en forme son `tools/list` de manière lisible n'est pas compté comme plus coûteux qu'un
serveur qui ne le fait pas, et le même serveur mesure la même chose d'une capture à l'autre.
`RESULT` correspond aux octets tels qu'ils sont arrivés : un résultat est une charge utile ponctuelle plutôt
qu'un contrat qui mérite d'être normalisé.```bash
mcpsnoop export -T json | jq '.summary.definitions'

Le socket se trouve dans le répertoire d'état du distant, résolu comme `MCPSNOOP_HOME`,
sinon `XDG_STATE_HOME/mcpsnoop`, sinon `~/.local/state/mcpsnoop`. Par défaut, mcpsnoop
suppose le home Linux `/home/<user>` à partir de votre `user@host` et affiche un rappel
sur stderr chaque fois qu'il retombe sur cette supposition. Si le distant se résout ailleurs,
indiquez le seul élément non défini par défaut.```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

Pour conserver plutôt une copie locale, scp les journaux dans votre répertoire de sessions et lancez
la TUI normalement.```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

Pour les workflows à distance, utilisez le tunnel SSH ou le transfert de fichiers SSH afin que l'authentification du transport,
le chiffrement, la vérification de l'hôte, la rotation des clés et la politique d'audit restent dans votre
configuration SSH existante.

## Contribution

Les issues et les pull requests sont les bienvenues. Consultez [CONTRIBUTING.md](https://github.com/kerlenton/mcpsnoop/blob/HEAD/CONTRIBUTING.md) pour
les détails.

## Licence

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