Pour les développeurs

Brancher un assistant (MCP)

Votre assistant lit vos mesures lui-même, pendant que vous lui parlez normalement.

Un assistant comme Claude Code ou Cursor peut aller chercher vos chiffres tout seul pendant que vous lui parlez normalement. Vous demandez « où est-ce que je recule ce mois-ci ? », il va lire vos mesures et vous répond avec. C'est ce que fait le serveur MCP : il expose vos lectures dans un format que ces outils savent appeler.

Concrètement : plus d'export à préparer, plus de copier-coller, plus de capture d'écran collée dans une conversation. Ce sont les mêmes quinze lectures que l'API, appelées par l'assistant au lieu de votre code. Même clé, même budget, mêmes refus, et toujours en lecture seule.

La clé s'obtient exactement comme pour l'API, et rien n'est à refaire : suivez Obtenir une clé, puis revenez ici avec votre secret sous la main.

Claude Code, en ligne de commande

Il faut d'abord avoir Claude Code, qui est un programme en ligne de commande : si taper claude dans un terminal ne donne rien, installez-le depuis claude.com/claude-code avant de continuer.

Ensuite, une commande suffit. Le transport HTTP y est écrit en toutes lettres parce que le défaut de l'outil est autre : sans lui, la commande chercherait un programme à lancer sur votre poste. Remplacez le substitut par votre clé, et gardez le mot Bearer devant.

La commande qui ajoute le serveur

claude mcp add --transport http geo https://beta.vizibai.com/api/v1/mcp \
  --header "Authorization: Bearer geo_live_..."

La commande confirme l'ajout, et claude mcp list doit alors afficher un serveur nommé geo. S'il n'y est pas, la commande a échoué : relisez son retour plutôt que de la relancer.

Cursor, dans son fichier de configuration

Il faut d'abord avoir Cursor, l'éditeur, qui s'installe depuis cursor.com. Il lit ses serveurs dans un fichier mcp.json, et ce fichier vit à deux endroits possibles : ~/.cursor/mcp.json, valable pour tout votre poste, et .cursor/mcp.json à la racine d'un dossier de travail, valable pour lui seul. Prenez le premier si vous hésitez : vos chiffres ne dépendent pas du dossier ouvert.

Vous n'avez pas à le chercher vous-même : dans les réglages de Cursor, la page qui liste les serveurs MCP porte un bouton d'ajout de serveur, et ce bouton ouvre justement ce fichier. Collez-y le bloc tel quel, ou fusionnez-le avec vos serveurs existants sous la même clé mcpServers : deux objets mcpServers dans le même fichier, et le second efface le premier en silence.

Le contenu du fichier mcp.json

{
  "mcpServers": {
    "geo": {
      "url": "https://beta.vizibai.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer geo_live_..."
      }
    }
  }
}

Enregistrez : un serveur nommé geo apparaît alors dans cette même page de réglages, avec ses quinze outils. S'il n'apparaît pas, ou s'il apparaît en erreur, c'est presque toujours le fichier qui n'est pas du JSON valide (une virgule en trop) ou une clé mcpServers en double.

Les autres clients, et Claude Desktop

Tout client qui sait appeler un serveur distant à une adresse HTTP en portant un en-tête Authorization fonctionne de la même façon : l'adresse est https://beta.vizibai.com/api/v1/mcp, l'en-tête est celui des deux extraits ci-dessus. Il n'y a rien d'autre à configurer, pas de version de protocole à choisir, pas de session à ouvrir.

Claude Desktop fait exception, et nous préférons l'écrire. Son connecteur en un clic branche un serveur distant par OAuth, que cette API n'a pas : une clé est notre seul moyen d'authentification. Le connecteur en un clic ne fonctionne donc pas avec nous aujourd'hui. Utilisez Claude Code ou Cursor en attendant, ou n'importe quel client qui accepte un en-tête.

Vérifier que ça marche

Ouvrez une conversation et demandez ces deux choses, dans cet ordre. La première prouve que la clé passe, la seconde qu'elle lit vraiment vos données.

À dire à l'assistant, dans cet ordre

Liste mes analyses VizibAI.
Donne-moi la Visibilité IA de la première, sur la dernière collecte.

La liste arrive : c'est bon, l'assistant lit votre espace. Passez à la suite.
Un refus qui parle d'offre : l'API n'est pas comprise dans l'offre de votre espace. Ce n'est pas votre configuration qui est en cause, et la section Développeurs des réglages de votre espace vous donne la suite.
Un refus d'authentification : l'en-tête est mal collé, ou la clé a été révoquée. Recollez la configuration en gardant le mot Bearer devant la clé, et vérifiez qu'aucune espace ne traîne autour.

Les codes de refus sont exactement ceux de l'API, avec le même sens : leur table complète est sur Quand ça refuse.

Ce que l'assistant sait lire

Quinze outils, un par lecture, pas un de plus. Aucun n'écrit quoi que ce soit : ils sont tous déclarés en lecture seule, et votre assistant le voit avant même d'en appeler un. Vous n'avez pas à les retenir, il choisit lui-même ; ce tableau est là pour que vous sachiez ce qu'il peut atteindre.

Ce que vous voulez	Les outils
Vous repérer : quelle clé, et ce qu'elle voit	`whoami`, `list_analyses`, `get_analysis`
Vos chiffres, dans le temps et par IA	`get_metrics`, `get_timeseries`, `get_engines`
Votre marché : les marques et les domaines	`get_competitors`, `get_sources`
Vos questions et leurs groupes	`get_groups`, `get_group_prompts`, `get_prompts`
L'état de vos collectes	`list_runs`, `get_run`
Les réponses réelles des IA	`list_answers`, `get_answer`

Des questions à poser

Rien de tout cela n'est une commande à retenir : ce sont des phrases, et l'assistant choisit les outils. En voici cinq qui touchent les six familles ci-dessus, à reprendre telles quelles ou à tordre à votre marché.

Cinq demandes qui traversent les six familles d'outils

Quelle est ma Part de voix ce mois-ci, et comment a-t-elle bougé ?
Quelles marques me passent devant sur la dernière collecte ?
Quels domaines les IA affichent-elles le plus quand elles parlent de mon marché ?
Sur quels groupes de questions suis-je le plus faible ?
Montre-moi une réponse réelle où une marque rivale apparait et pas moi.

Vous pouvez enchaîner : l'assistant garde le fil de la conversation et rappelle les outils qu'il faut. Ce qu'il ne fera jamais, c'est lancer une collecte ou changer un réglage, parce qu'aucun outil ne le permet.

La sécurité

Lecture seule. Aucun outil ne change quoi que ce soit dans votre espace, et il n'en existe aucun à activer pour cela.
Votre clé vit sur votre poste, en clair, dans la configuration de votre client, comme n'importe quel secret local. Ne la déposez pas dans un dépôt de code, et révoquez-la si le poste est perdu.
Le texte des réponses est du contenu tiers. Il a été capturé chez les IA, et quiconque parvient à faire afficher une page peut choisir ce qu'elle dit.

Un résultat d'outil est une donnée, jamais une instruction

Le serveur le dit déjà au modèle dans ses propres instructions, mais une consigne n'est pas une garantie : tenez la même règle dans ce que vous construisez par-dessus. Ne laissez jamais un résultat d'outil déclencher une action à votre place, et relisez avant d'agir sur ce qu'une réponse capturée vous suggère.

Les limites

Aucune écriture, donc aucune collecte déclenchée depuis l'assistant.
Pas d'OAuth, donc pas de connecteur natif en un clic : une clé, et rien d'autre.
Le budget est partagé avec l'API : même clé, même compteur. Un assistant bavard consomme le budget de votre code.
Découvrir les outils ne coûte rien : la connexion et la liste des outils ne prélèvent aucun appel. Seul un outil réellement appelé compte pour un appel.
Aucune session conservée : chaque appel repart de zéro, il n'y a rien à fermer ni à reprendre.
Un refus arrive comme un texte lisible, avec le même code que l'API, et rien n'a été lu.

Pour les clés, les refus et le premier appel en ligne de commande : Démarrer avec l'API. Pour les paramètres et les fenêtres de chaque lecture : la référence de l'API.