GUIDE

Brancher vos API à vos agents IA (MCP)

MCP (Model Context Protocol) est le standard par lequel les agents IA découvrent et utilisent des outils externes. Une API Amphybi publiée devient un outil : l'agent voit son nom, sa description et ses entrées attendues, puis décide tout seul quand l'appeler.

Trois façons de brancher

Façon	Adresse	Clé	Quand l'utiliser
Une API précise	`/mcp/{espace}/{id}`	la clé de l'API	exposer une seule automatisation
Le compte entier	`/mcp/{espace}`	clé `amk_…` ou OAuth	toutes vos API en une URL, les nouvelles incluses
La démonstration	`/mcp/demo`	aucune	essayer dans votre agent, sans compte

Dans les trois cas, les tâches s'exécutent dans votre navigateur (ou dans le cloud si l'API est en mode 24/7), et chaque appel consomme 1 unité de votre quota mensuel.

1. L'adresse MCP d'une API

À la publication, l'extension affiche une adresse MCP par API. Copiez-la avec sa clé, puis ajoutez un serveur MCP de type « HTTP » dans votre agent :

Configuration MCP (exemple)

{
  "mcpServers": {
    "statut-dossier": {
      "type": "http",
      "url": "https://VOTRE-RELAIS/mcp/ESPACE/ID",
      "headers": { "Authorization": "Bearer kp_live_…" }
    }
  }
}

Le nom et la description de votre automatisation deviennent ceux de l'outil : choisissez-les clairs (« Statut d'un dossier client », pas « Test 2 »), c'est ce que l'agent lit pour décider de s'en servir.

2. Le serveur MCP du compte — une URL, toutes vos API

La console (onglet Accueil → carte « Serveur MCP ») affiche une seule adresse et une clé amk_… qui exposent toutes vos API publiées. Publiez une nouvelle API : elle apparaît automatiquement dans les agents déjà branchés.

Serveur MCP du compte

{
  "mcpServers": {
    "amphybi": {
      "type": "http",
      "url": "https://VOTRE-RELAIS/mcp/ESPACE",
      "headers": { "Authorization": "Bearer amk_…" }
    }
  }
}

Rotation : le bouton ↻ génère une nouvelle clé et révoque immédiatement l'ancienne — les agents branchés cesseront de fonctionner jusqu'à mise à jour. C'est aussi ainsi qu'on coupe un accès.
Homonymes : deux API du même nom reçoivent un suffixe automatique — les noms d'outils restent uniques.
La clé du compte donne accès à toutes vos API publiées : partagez-la avec discernement ; préférez l'adresse par API pour un partage ciblé.

3. OAuth : Claude web, ChatGPT et les connecteurs qui l'exigent

Les connecteurs personnalisés de Claude (claude.ai) et les connecteurs ChatGPT refusent une clé collée à la main : ils exigent la connexion OAuth. C'est prévu, sans aucune configuration :

dans le connecteur, donnez seulement l'URL du serveur de compte : https://VOTRE-RELAIS/mcp/{votre-espace} ;
le client découvre tout seul le serveur d'autorisation (/.well-known/oauth-authorization-server), s'enregistre, puis ouvre une page Amphybi ;
connectez-vous avec votre code à 6 chiffres par e-mail, vérifiez le nom du client, cliquez sur Autoriser l'accès ;
le connecteur reçoit ses jetons et vos outils apparaissent dans l'agent.

Côté technique : jetons opaques (accès 30 jours, rafraîchissement 180 jours avec rotation), PKCE obligatoire, redirect_uri restreints à ceux déclarés par le client, révocation via POST /oauth/revoke. Pour couper un client immédiatement : régénérez la clé MCP dans la console.

4. La démonstration publique — essayez sans compte

Ajoutez https://VOTRE-RELAIS/mcp/demo comme serveur MCP dans votre agent, sans aucune clé : quelques API en lecture seule de l'équipe Amphybi. Demandez-lui le statut d'une commande de la démo et regardez-le appeler l'outil tout seul.

Garde-fous : 10 appels par minute et par adresse IP, 10 outils maximum, et chaque appel consomme le quota du compte de démonstration (pas le vôtre).

Sécurité, quotas et limites

Sujet	Règle
Où s'exécutent les tâches	Dans votre navigateur — ou en cloud 24/7 si l'API est publiée ainsi (les sites à connexion passent par le coffre de sessions).
Quota	Chaque appel MCP consomme 1 unité du quota mensuel du compte, comme un appel REST.
Actions sensibles	Envoyer, payer, valider, supprimer restent bloqués, sauf si la case était cochée à la publication.
Limites de débit	30 appels/min par API · 90 appels/min par compte et par IP · 10 appels/min par IP (démo).
Révocation	Clé : bouton ↻ dans la console. Jeton OAuth : `POST /oauth/revoke`, ou expiration (30 j).

Règle d'or : automatisez uniquement des sites auxquels vous avez légitimement accès, dans le respect de leurs conditions et de la protection des données. Commencez par des tâches en lecture.

Dépannage

Ce que vous voyez	Pourquoi	Que faire
`401 UNAUTHORIZED`	Clé manquante, fausse ou régénérée.	Recopiez la clé depuis la console ; clients OAuth : relancez la connexion du connecteur.
`429 RATE_LIMITED`	Limite de débit atteinte.	Attendez une minute ; évitez les appels en boucle côté agent.
`BROWSER_OFFLINE`	Chrome est fermé ou en veille.	Ouvrez Chrome avec l'extension connectée (ou activez le cloud 24/7).
`QUOTA_EXCEEDED` / `PAYMENT_REQUIRED`	Quota atteint / essai terminé.	Passez à l'offre supérieure ou attendez le mois suivant.
« Outil inconnu » côté agent	L'API a été dépubliée.	Republiez l'automatisation ; l'outil reparaît au prochain `tools/list`.
L'agent ne voit aucun outil	Aucune API publiée.	Publiez au moins une automatisation.
Claude web / ChatGPT boucle sur la connexion	`redirect_uri` non déclaré ou jeton expiré.	Relancez l'ajout du connecteur : tout se refait automatiquement.