Skills

Installation de la compétence Showly

Ajout de la compétence officielle Showly à Claude Code ou Codex.

La compétence Showly enveloppe le serveur MCP avec des invites déclenchées par l'intention et un modèle de refus prenant en compte la boucle de publication. Cette page explique son installation sur Claude Code, Codex et tout autre agent compatible MCP.

Comment fonctionne l'autorisation

Vous ne collez pas de jeton. Le serveur MCP de Showly est un serveur HTTP distant en https://mcp.showly.ai, et il utilise la poignée de main d'autorisation standard MCP (OAuth 2.1 + PKCE). La première fois que votre agent appelle un outil Showly :

  1. L'agent se connecte, obtient un 401 et découvre automatiquement le serveur d'autorisation de Showly.
  2. Il ouvre un onglet de navigateur sur showly.ai où vous vous connectez et approuvez les étendues demandées.
  3. Showly émet un jeton court et étendu directement à l'agent. Vous ne le voyez ni ne le copiez jamais.

Le seul travail de l'installateur consiste donc à enregistrer l'URL du serveur auprès de votre agent. La connexion s'effectue dans votre navigateur lors de la première utilisation.

Prérequis

  • Un espace de travail Showly et au moins un site connecté.
  • Autorisation d'approuver l'accès des agents. L'étape d'approbation nécessite un rôle avec au moins site:write (propriétaire, administrateur, développeur ou membre). L'approbation à partir d'un compte moins privilégié créera un jeton limité aux portées que vous détenez réellement.

Claude Code

L'installateur canonique est le package @showly/mcp-server (bin showly-mcp). Exécutez-le avec la cible claude-code :

npx @showly/mcp-server install --to claude-code

Cela écrit le bloc serveur Showly MCP dans votre configuration Claude Code. Pas de jeton, pas de commande de connexion distincte. La prochaine fois que vous appellerez un outil Showly, l'agent exécute la connexion au navigateur décrite ci-dessus.

Testez la connexion depuis l'intérieur de Claude Code :

Showly, lister mes sites.

Le premier appel ouvre un onglet de navigateur pour approuver l'accès ; après avoir approuvé, vous devriez voir vos sites répertoriés, provenant de mcp__showly__list_sites.

Codex

Utilisez le même programme d'installation avec la cible codex. Il écrit le serveur Showly dans votre ~/.codex/config.toml pour vous :

npx @showly/mcp-server install --to codex

Redémarrez Codex pour récupérer le nouveau serveur, puis invoquez un outil Showly pour déclencher la connexion au navigateur.

Tout autre hôte MCP

Pour inspecter la configuration que le programme d'installation écrirait sans l'appliquer, ciblez stdout :

npx @showly/mcp-server install --to stdout

Copiez le bloc serveur MCP imprimé dans la configuration de votre hôte. Tout client MCP qui prend en charge le flux d'autorisation standard (WWW-Authenticate découverte → consentement du navigateur) se connecte à https://mcp.showly.ai sans jeton manuel. Si la machine qui exécute votre agent n’a pas de navigateur, ou si la personne qui autorise se trouve ailleurs, utilisez la connexion sans interface décrite ci-dessous.

Connexion sans interface (flux de l’appareil)

Lorsque la machine de l’agent n’a pas de navigateur (un serveur, un conteneur, une CI, un shell distant) ou que la personne qui autorise tient un téléphone plutôt que d’être devant cette machine, exécutez npx @showly/mcp-server login --to claude-code. La commande affiche l’adresse de la page et un code court, attend pendant que vous autorisez depuis n’importe quel appareil, puis écrit l’identifiant dans la configuration de votre hôte. --to codex écrit ~/.codex/config.toml, dont l’entrée lit l’identifiant depuis la variable d’environnement SHOWLY_TOKEN et non depuis le fichier : la commande affiche la ligne export SHOWLY_TOKEN=… correspondante, et Codex ne peut pas s’authentifier tant qu’elle n’est pas définie là où il démarre. --to stdout n’écrit rien et se contente d’afficher un extrait, et --print-token n’affiche que le jeton afin que la CI puisse le récupérer sans qu’il atterrisse dans un fichier.

N’autorisez que si le code de la page correspond à celui de votre terminal. L’écran de consentement vous demande de le confirmer explicitement, car le nom affiché par un client est celui qu’il s’est donné : le code est la seule partie vérifiable. Un code reste valable 15 minutes, et ouvrir la page vous accorde 10 minutes de plus pour vous connecter et autoriser ; s’il expire, relancez la commande.

Ce n’est pas un chemin que votre client découvre seul. Les clients MCP ne démarrent pas de flux d’appareil, donc login est la seule entrée. L’identifiant écrit expire au bout de 90 jours et Showly n’émet aucun jeton de rafraîchissement : relancez login à ce moment-là.

Dépannage

tool not found: mcp__showly__list_sites — La Skill est installée mais le serveur MCP n'est pas encore connecté. Dans Claude Code, exécutez claude mcp list et vérifiez l'entrée showly ; invoquez une fois un outil Showly pour déclencher la connexion.

La connexion au navigateur n'apparaît pas / "non autorisée" — Votre agent peut ne pas prendre en charge le flux d'autorisation standard MCP. Confirmez qu'il s'agit d'une version récente, puis réessayez ; l'agent doit être capable de suivre la découverte 401 → WWW-Authenticate pour ouvrir la page de consentement.

"Vous n'êtes pas autorisé à approuver" — Le compte approbateur a besoin d'au moins site:write. Connectez-vous avec un compte propriétaire/administrateur/développeur/membre, ou demandez à un coéquipier ayant ce rôle d'approuver.

"site introuvable" : les étendues approuvées ou la liste autorisée des sites ne couvrent pas le site pour lequel vous avez posé la question. Réexécutez la connexion et approuvez les étendues nécessaires, ou élargissez l'accès depuis la page Mon agent (/app/integrations).

Les appels d'outils se bloquent — Le serveur MCP ne peut pas atteindre le API de Showly. Vérifiez votre réseau ; si vous avez remplacé le point de terminaison, confirmez que SHOWLY_MCP_URL (l'URL du serveur MCP) et SHOWLY_API_URL (la base API) ne pointent pas vers un endroit obsolète.

Révocation de l'accès

Pour révoquer l'accès d'un agent, ouvrez la page Mon agent (/app/integrations), recherchez l'agent et déconnectez-le. La révocation prend effet immédiatement ; l'agent sera invité à se reconnecter lors de son prochain appel. Il n’y a pas de jeton à faire tourner manuellement : l’agent en obtient un nouveau via le flux du navigateur. S’il n’y a pas de navigateur, il l’obtient avec npx @showly/mcp-server login. Les identifiants issus de la connexion sans interface expirent au bout de 90 jours.