Émettre un token MCP pour un agent IA autonome

Créez, gérez et révoquez des tokens MCP dédiés aux agents IA autonomes afin de leur accorder un accès granulaire et auditable aux ressources de votre workspace Coffrify.

Télécharger en PDF

Les tokens MCP (Model Context Protocol) sont distincts des clés API classiques : ils sont émis spécifiquement pour des agents IA autonomes (Claude Desktop, Cursor, Cline, etc.) et tracés dans la table coffrify_mcp_tokens. Ils partagent le même catalogue de scopes et les mêmes mécanismes d'expiration et de liste blanche IP que les clés API, mais leurs flux d'audit, d'activité et de révocation sont isolés pour ne pas polluer les logs de vos intégrations serveur.

GET/v1/mcp/tokensListe tous les tokens MCP actifs et révoqués du workspace, triés par date de création décroissante.POST/v1/mcp/tokensCrée un nouveau token MCP. Le secret brut est retourné une seule fois dans la réponse.

PATCH/v1/mcp/tokens/{id}Modifie un token existant (nom, description, scopes, liste IP, activation/désactivation).

DELETE/v1/mcp/tokens/{id}Révoque définitivement un token MCP avec une raison optionnelle.POST/v1/mcp/tokens/{id}/rotateRévoque le token existant après une fenêtre de grâce et émet un token de remplacement avec les mêmes paramètres.

Authentification

Toutes les opérations sur les tokens MCP requièrent le scope api_keys:manage. Transmettez votre clé API dans l'en-tête Authorization: Bearer cof_live_… ou Authorization: Bearer cof_test_…. Sans ce scope, l'API renvoie 403 scope_missing.

Corps de la requête, POST /v1/mcp/tokens

Champ	Type	Requis	Description
name	string	Oui	Nom lisible du token (ex. : "Agent fiscal Q1").
description	string	Non	Note interne libre.
scopes	string[]	Non	Liste de scopes accordés. Défaut : `["transfers:read"]`. Au moins un scope requis.
environment	string	Non	Environnement cible : `"live"` (défaut) ou `"test"`. Détermine le préfixe `cof_mcp_live_…` / `cof_mcp_test_…`.
client_hint	string	Non	Client MCP ciblé. Valeurs autorisées : `claude-desktop`, `claude`, `cursor`, `cline`, `continue`, `custom`.
expires_in_days	number	Non	Durée de validité en jours. Si absent, le token n'expire pas.
allowed_ips	string[]	Non	CIDR ou IP autorisés. Si absent, aucune restriction IP.
max_uses	number	Non	Nombre maximal d'utilisations avant invalidation automatique.

Corps de la requête, PATCH /v1/mcp/tokens/{id}

Champ	Type	Requis	Description
name	string	Non	Nouveau nom du token.
description	string \| null	Non	Nouvelle description (passer `null` pour l'effacer).
is_active	boolean	Non	Désactiver (`false`) ou réactiver (`true`) sans révoquer définitivement.
scopes	string[]	Non	Remplace la liste de scopes. Au moins un scope requis.
allowed_ips	string[]	Non	Remplace la liste blanche IP.

Exemples d'appel

# Créer un token MCP pour Claude Desktop
curl -X POST https://api.coffrify.com/v1/mcp/tokens \
  -H "Authorization: Bearer cof_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agent fiscal Q1",
    "description": "Lecture seule pour le rapprochement bancaire",
    "scopes": ["transfers:read", "documents:read"],
    "environment": "live",
    "client_hint": "claude-desktop",
    "expires_in_days": 90
  }'

Réponse

La création (POST) retourne un HTTP 201 avec le token brut dans le champ token. Ce champ n'est exposé qu'une seule fois. Seul le préfixe (ex. : cof_mcp_live_3a7f9b2c...) est conservé en base pour identification.

{
  "id": "tmcp_01HXYZ4K9QW2NBVR3D7GFPC8A1",
  "name": "Agent fiscal Q1",
  "description": "Lecture seule pour le rapprochement bancaire",
  "token_prefix": "cof_mcp_live_3a7f9b2c...",
  "token": "cof_mcp_live_3a7f9b2ce4d1f08a6b5c9e3d7a2f1b4c8e6d0f9a3b2c1d5e7f4a0b8c2d3e6f1",
  "scopes": ["transfers:read", "documents:read"],
  "environment": "live",
  "client_hint": "claude-desktop",
  "allowed_ips": null,
  "expires_at": "2026-09-04T14:30:00.000Z",
  "max_uses": null,
  "created_at": "2026-06-06T14:30:00.000Z",
  "warning": "Save this token now - it will not be shown again."
}

La rotation (POST /v1/mcp/tokens/{id}/rotate) retourne également un HTTP 201 avec la structure suivante :

{
  "new_token": "cof_mcp_live_b8d2e1f4a7c3b9e5d0f2a6c1b3d7e9f0a2c4b6d8e1f3a5c7b9d2e4f6a8c0b2",
  "new_prefix": "cof_mcp_live_b8d2e1f4...",
  "old_id": "tmcp_01HXYZ4K9QW2NBVR3D7GFPC8A1",
  "new_id": "tmcp_01HYGQ8M3RT5NCWS4E9HGPD2B7",
  "grace_expires_at": "2026-06-13T14:30:00.000Z",
  "warning": "Save this token now - it will not be shown again."
}

Erreurs

HTTP	Code	Quand	Résolution
400	`validation_error`	`name` absent au POST, `scopes` vide, `client_hint` invalide, `reason` de révocation dépassant 200 caractères, PATCH sans champ valide.	Vérifiez la présence du champ `name`, que `scopes` contient au moins un élément et que `client_hint` appartient aux valeurs autorisées.
401	`missing_api_key` / `invalid_api_key`	En-tête `Authorization` absent ou clé inconnue.	Passez votre clé API dans `Authorization: Bearer cof_live_…`.
403	`scope_missing`	La clé appelante ne possède pas le scope `api_keys:manage`.	Émettez une clé disposant du scope `api_keys:manage`.
404	`not_found`	L'`id` du token ne correspond à aucun enregistrement dans le workspace.	Vérifiez l'`id` retourné lors de la création.
422	`validation_error`	Tentative de rotation sur un token déjà révoqué.	Créez directement un nouveau token via POST.
500	`internal_error`	Erreur base de données inattendue.	Réessayez ; si l'erreur persiste, contactez le support Coffrify.

Bonnes pratiques

Bonnes pratiques pour vos tokens MCP

1. Stockez le token brut immédiatement après sa création : Coffrify ne conserve que son hash SHA-256 et ne peut pas le régénérer. 2. Appliquez le principe de moindre privilège : accordez uniquement les scopes nécessaires à l'agent (ex. transfers:read pour un agent de lecture). 3. Fixez toujours une expiration (expires_in_days) et une liste blanche IP (allowed_ips) en production. 4. Utilisez client_hint pour identifier le client MCP : les valeurs autorisées sont claude-desktop, claude, cursor, cline, continue, custom. 5. Faites tourner les tokens tous les 90 jours via POST /v1/mcp/tokens/{id}/rotate avec grace_days pour éviter toute interruption de service. 6. Préférez la raison compromised en cas de suspicion d'exposition : elle déclenche un événement api_key.revoked dans l'audit du workspace. 7. En environnement de développement, utilisez environment: test pour obtenir un token préfixé cof_mcp_test_… sans impact sur les données de production.

Voir aussi

Créer une clé API
Comprendre les scopes de l'API Coffrify
Configurer un serveur MCP Coffrify
Révoquer une clé API
Événements webhook liés aux clés

Continuer

Autres tutoriels à suivre

📥Recevoir des fichiers en 5 min (no-code)→🚀Construire un agent qui crée et livre des transferts automatiquement→✅Implémenter un workflow d'approbation de transfert→