Serveur MCP

PostShip expose un serveur MCP (Model Context Protocol, le protocole par lequel un éditeur donne des outils à un agent) en lecture, plus une seule action : relancer une vérification. C'est ce qu'un agent dans un éditeur a besoin de savoir après avoir modifié du code — « est-ce que j'ai cassé quelque chose ? » — et rien de plus. Aucun outil destructif n'est exposé, et ce n'est pas une omission qu'on comblera : un delete_project au bout d'un agent est une suppression de projet à un malentendu de distance.

Ce que le serveur expose

Six outils, chacun limité à ce que le propriétaire du jeton a le droit de lire — ses projets, et ceux où il est membre accepté. L'identifiant de l'utilisateur ne vient jamais des arguments : un agent qui invente un identifiant de projet ne lit rien de plus.

Le verdict, fait pour un agent

last_ship rend une note et une phrase ; open_incidents rend des URL et un état. Ni l'un ni l'autre ne dit quoi corriger. deploy_verdict transforme le dernier déploiement et les vérifications qui l'ont suivi en une liste de choses cassées, chacune avec son adresse, sa nature et la phrase qui dit ce qui manque — le vocabulaire des alertes et des écrans, pas un second vocabulaire qui aurait divergé en trois mois. Quatre verdicts : pass, fail (la liste casse dit quoi), en_cours (la vérification n'est pas finie — sans cette distinction, un agent lirait « rien de cassé » sur un déploiement qu'on n'a pas encore regardé), aucun_deploiement. Une phrase resume résume tout, parce que les modèles résument et que la première ligne est celle qui survit au résumé.

wait_for_verdict rend la main dès qu'il tient une réponse ferme : fail dès qu'une casse est connue, sans attendre la fin ; pass seulement une fois les reprises T+2 et T+8 sorties de la file. L'attente est bornée à 45 secondes ; si le verdict n'est pas prêt, l'agent rappelle. Ces deux outils existent pour refermer la boucle : votre agent déploie, demande le verdict, corrige. Sans eux, il faut redéployer pour savoir.

Brancher un client

Le jeton est celui de l'API (Paramètres → API & tokens). Il va dans le fichier de configuration MCP de votre outil, jamais sur une ligne de commande — un argument se lit dans la liste des processus de la machine et reste dans l'historique du shell.

{
  "mcpServers": {
    "postship": {
      "url": "https://postship.fr/api/mcp",
      "headers": { "Authorization": "Bearer psk_…" }
    }
  }
}

Claude Code remplace ${POSTSHIP_TOKEN} par la variable d'environnement au chargement, ce qui évite d'écrire le jeton dans un fichier versionné. Si vous préférez coller le jeton en clair, mettez le fichier hors du dépôt (la configuration utilisateur) ou dans .gitignore.

Le transport est HTTP : un POST JSON-RPC 2.0 sur https://postship.fr/api/mcp, avec les méthodes initialize, tools/list et tools/call. La négociation initialize répond avant l'authentification — un client qui recevrait 401 à ce stade abandonnerait sans jamais montrer le message qui explique pourquoi.

Ce qui déclenche une alerte

Rien : le serveur lit, et run_check vérifie sans écrire dans un projet. Un run_check ne crée ni cible, ni incident, ni alerte.

Limites et plans

Hors plan Team, le serveur répond « L'accès MCP fait partie du plan Team. » (403). Un agent qui interroge le compte est très exactement le genre d'usage qui a une équipe derrière. Voir les plans.

Dépannage

Pourquoi mon éditeur affiche-t-il « Jeton d'API PostShip invalide ou révoqué » ?

L'en-tête n'est pas arrivé entier : vérifiez Authorization: Bearer psk_… dans le fichier de configuration, et que la variable d'environnement est bien définie dans l'environnement qui lance l'éditeur — pas seulement dans un terminal.

Pourquoi wait_for_verdict rend-il en_cours plusieurs fois ?

Les reprises T+2 et T+8 durent huit minutes après le déploiement ; l'outil attend 45 secondes par appel. L'agent doit rappeler jusqu'à pass ou fail. Un fail arrive dès la première casse connue, sans attendre.

Pourquoi run_check échoue-t-il avec « Quota mensuel atteint » ?

Le quota est celui des vérifications de CI, partagé avec POST /api/v1/check et tous les jetons du compte. Le compteur se lit dans Paramètres → API & tokens.