Serveur MCP

Sarutobi expose ses mesures aux agents — Claude Code, un job de CI — via le Model Context Protocol. Un agent connecté répond aux questions du dashboard sans ouvrir le dashboard, et chaque réponse porte le lien de l'écran qui montre le même chiffre.

1. Donner l'adresse

Il n'y a rien à créer avant. Donnez l'adresse du serveur à votre client : il découvre le reste, s'enregistre seul et ouvre votre navigateur sur un écran qui demande ce que vous accordez — organisation et permissions, l'écriture décochée.

claude mcp add --transport http sarutobi https://sarutobi.ascencia.re/api/mcp

Ce mécanisme n'a rien de propre à Claude : c'est OAuth 2.1, tel que le protocole MCP le définit. Tout client qui l'implémente y a droit — Codex ouvre la même page avec codex mcp login, et les autres ont chacun leur commande. Le catalogue des clients les liste.

2. Le jeton, pour ce qui n'a pas de navigateur

Un job de CI ne peut pas afficher un écran de consentement. Il lui faut donc un jeton créé à la main depuis Mon compte → Agents. Le secret st_mcp_… n'est affiché qu'une fois : la base n'en garde qu'une empreinte.

Comme un jeton obtenu par OAuth, il porte une organisation et l'identité de son créateur. Son rôle est relu à chaque appel, donc être retiré de l'organisation coupe ses jetons immédiatement — des deux côtés, il n'y a pas de révocation à penser.

claude mcp add --transport http sarutobi \
  https://sarutobi.ascencia.re/api/mcp \
  --header "Authorization: Bearer st_mcp_..."

{
  "mcpServers": {
    "sarutobi": {
      "type": "http",
      "url": "https://sarutobi.ascencia.re/api/mcp",
      "headers": { "Authorization": "Bearer st_mcp_..." }
    }
  }
}

Scopes

Deux barrières indépendantes s'appliquent à chaque appel : le scope dit ce que le jeton a le droit de demander, le rôle dit ce que la personne a le droit de faire. Un jeton d'écriture détenu par un compte en lecture seule n'écrit rien.

• site:read — lister les sites et lire leurs réglages.
• analytics:read — mesures agrégées, courbes, découpages, erreurs, vitals.
• person:read — personnes et sessions, propriétés masquées.
• person:properties:read — propriétés de personne en clair.

Par où commencer

L'agent découvre les outils tout seul, mais l'ordre compte. Lui demander d' appeler list_sites puis list_event_names avant de mesurer évite la réponse fausse la plus fréquente : un nom d'événement inventé renvoie zéro sans erreur, ce qui se lit « personne ne le fait » alors que c'est « ce nom n'existe pas ».

La ressource sarutobi://glossary porte le vocabulaire qui évite les autres : visite, session et personne sont trois choses distinctes ; le temps réel lit les visites brutes quand les vues agrégées lisent les rollups ; et les visiteurs uniques ne s'additionnent pas d'un jour à l'autre.

Donner la documentation à l'agent

Le serveur MCP donne les mesures. Il ne dit rien de la façon d'installer la librairie, de nommer un événement ou de brancher un consentement — et c'est là que se trompe un agent à qui on demande d'instrumenter un site. Deux fichiers couvrent ce manque, servis à la racine du domaine, sans authentification.

• /llms.txt — le sommaire, au format llms.txt : ce qu'est Sarutobi, les repères d'intégration qui évitent les erreurs les plus fréquentes, et l'adresse de chaque page.
• /llms-full.txt — la même documentation en entier, dans un seul fichier, pour un agent qui ne peut pas naviguer ou dont on remplit le contexte à l'avance.

Ce que le serveur ne fait pas

La question posée pour chaque outil n'est pas « un agent en aurait-il besoin » mais « que se passe-t-il quand il se trompe ».

Écriture

Quatre scopes ouvrent l'écriture, et ils sont refusés par défaut. Le plus utile est annotation:write : un job de déploiement pose le repère au moment du déploiement, et les courbes portent ensuite « ce pic date de la 2026.07.1 » sans que personne ne l'ait saisi.

• annotation:write — poser un repère de release ou une note. Idempotent sur le libellé : rejouer un déploiement ne pose pas un second repère.
• error:write — marquer un groupe d'erreurs résolu. Le groupe réapparaît de lui-même si l'erreur se reproduit : c'est une affirmation datée, pas un masquage.
• insight:write — enregistrer une définition de mesure ou un entonnoir.
• site:write — modifier les réglages d'un site.

Rien ne supprime, ne purge, n'exporte en masse ni ne modifie les accès d'une organisation. Chaque écriture laisse une trace consultable depuis l'écran des jetons : outil appelé, site, résultat, et les clés des arguments — jamais leurs valeurs.