Ce guide vous montre comment construire un agent Python autonome capable de : (1) créer un token MCP dédié avec les scopes nécessaires, (2) soumettre un transfert chiffré contenant un ou plusieurs fichiers, (3) uploader les fichiers vers les URL présignées retournées, puis (4) interroger l'endpoint de diagnostic pour vérifier que le transfert est sain avant de transmettre le lien de partage au destinataire. L'ensemble du pipeline s'exécute sans interaction humaine et est conçu pour s'intégrer dans un workflow CI/CD, un cron ou un agent IA.
POST/v1/mcp/tokensCrée un token MCP (cof_mcp_live_* ou cof_mcp_test_*) avec les scopes, l'environnement et les restrictions IP souhaités. Le token brut n'est retourné qu'une seule fois.POST/v1/transfersCrée un transfert et retourne les URL d'upload présignées pour chaque fichier. Supporte le chiffrement AES-256-GCM, les restrictions géographiques, le mot de passe, le TOTP et le filigrane.GET/v1/diagnostics/transfer/{id}Diagnostique un transfert existant : cycle de vie, expiration, quota de téléchargements, scan antivirus, protection par mot de passe et restrictions géographiques. Retourne un verdict healthy / degraded / broken avec des actions recommandées.Authentification
Toutes les requêtes doivent porter l'en-tête Authorization: Bearer <token>. Pour créer un token MCP, votre clé appelante doit posséder le scope api_keys:manage. Le token MCP créé doit lui-même posséder les scopes transfers:write (pour POST /v1/transfers) et transfers:read (pour GET /v1/diagnostics/transfer/:id). Les tokens de production portent le préfixe cof_mcp_live_, les tokens de test cof_mcp_test_. Le token brut n'est visible qu'à la création : stockez-le dans un secret manager immédiatement.
Corps de la requête : créer un token MCP (POST /v1/mcp/tokens)
Un token MCP est une clé dédiée aux agents : vous lui attribuez des scopes précis, un environnement et, si besoin, une liste d'IP autorisées. Le tableau ci-dessous détaille les champs acceptés à la création.
| Champ | Type | Requis | Description |
|---|---|---|---|
| name | string | Oui | Nom lisible du token (ex. : agent-livraison-prod). |
| description | string | Non | Description libre pour l'audit. |
| environment | string | Non | "live" (défaut) ou "test". Détermine le préfixe cof_mcp_live_* ou cof_mcp_test_*. |
| scopes | array | Non | Liste de scopes. Défaut : ["transfers:read"]. Pour cet agent : ["transfers:write", "transfers:read"]. |
| client_hint | string | Non | Contexte client. Valeurs acceptées : claude-desktop, claude, cursor, cline, continue, custom. |
| expires_in_days | integer | Non | Durée de validité en jours. Passé ce délai, le token est révoqué automatiquement. |
| allowed_ips | array | Non | Liste CIDR d'IP autorisées. Si absent, toutes les IP sont acceptées. |
| max_uses | integer | Non | Nombre maximal d'utilisations du token. |
Corps de la requête : créer un transfert (POST /v1/transfers)
La création de transfert reprend les mêmes champs que l'API standard. Pour un agent, seuls files et le contenu à envoyer sont indispensables ; les options de sécurité (mot de passe, expiration, géo-restriction) restent facultatives.
| Champ | Type | Requis | Description |
|---|---|---|---|
| files | array | Oui | Tableau d'objets {name, size, mime_type}. Décrit les fichiers à uploader. |
| transfer_title | string | Non | Titre affiché au destinataire. |
| expires_in_hours | integer | Non | Durée de vie du transfert en heures. |
| max_downloads | integer | Non | Limite de téléchargements. En sandbox : plafonné à 5. |
| password | string | Non | Mot de passe d'accès. Activer is_password_protected côté API. |
| require_totp | boolean | Non | Exige un code TOTP à la réception. |
| recipient | string | Non | Email ou identifiant du destinataire pour la notification. |
| notify_opens | boolean | Non | Notifie l'expéditeur à chaque ouverture. |
| encryption_mode | string | Non | Mode de chiffrement. Ex. : "aes-256-gcm". |
| geo_allowlist | array | Non | Codes pays ISO-3166-1 alpha-2 autorisés. |
| geo_blocklist | array | Non | Codes pays ISO-3166-1 alpha-2 bloqués. |
| watermark_enabled | boolean | Non | Active le filigrane sur les fichiers téléchargés. |
| watermark_text | string | Non | Texte du filigrane (ex. : nom du destinataire). |
| custom_slug | string | Non | Slug personnalisé pour l'URL de partage. |
| auto_delete | boolean | Non | Supprime le transfert automatiquement après expiration. |
| scheduled_for | string (ISO 8601) | Non | Date de mise en ligne différée du transfert. |
Exemple complet en quatre onglets
L'exemple complet enchaîne les trois appels dans l'ordre : créer le token MCP, créer le transfert avec ce token, puis diagnostiquer le transfert. Choisissez votre langage.
Réponse : token MCP créé (201)
Le token brut n'est renvoyé qu'une seule fois, à la création : stockez-le immédiatement dans un secret. Conservez aussi l'id du token, nécessaire pour le révoquer ou le faire tourner par la suite.
Réponse : transfert créé (201)
Comme pour un transfert standard, retenez upload_urls (à utiliser tout de suite pour téléverser) et share_url (le lien à transmettre). L'id du transfert sert ensuite au diagnostic et au suivi.
Réponse : diagnostic (200)
Le diagnostic agrège plusieurs contrôles (checks) sur le cycle de vie, l'expiration, le quota de téléchargements et le scan antivirus. C'est l'appel idéal pour qu'un agent vérifie qu'un transfert est bien livrable avant de notifier le destinataire.
Erreurs
Les erreurs ci-dessous couvrent les deux étapes (création du token MCP, puis du transfert). Un 403 scope_missing indique le plus souvent que la clé appelante n'a pas api_keys:manage, ou que le token MCP créé ne porte pas le scope transfers:write.
| HTTP | code | Quand | Résolution |
|---|---|---|---|
| 400 | validation_error | name manquant (token MCP) ou files[] vide (transfert). | Vérifiez la présence des champs obligatoires dans votre payload. |
| 400 | validation_error | client_hint invalide. | Utilisez l'une des valeurs : claude-desktop, claude, cursor, cline, continue, custom. |
| 401 | missing_api_key | Header Authorization absent. | Ajoutez Authorization: Bearer <token> à chaque requête. |
| 401 | invalid_api_key | Token inconnu, malformé ou révoqué. | Vérifiez le préfixe cof_mcp_live_* ou cof_mcp_test_* et l'état du token. |
| 401 | expired_api_key | Token expiré (expires_at dépassé). | Créez un nouveau token via POST /v1/mcp/tokens. |
| 401 | revoked_api_key | Token révoqué manuellement. | Provisionnez un nouveau token. |
| 403 | scope_missing | Le token ne possède pas le scope requis. | Ajoutez transfers:write et/ou transfers:read lors de la création du token. |
| 403 | ip_not_allowed | L'IP appelante ne figure pas dans allowed_ips. | Vérifiez la plage CIDR configurée ou retirez la restriction. |
| 404 | not_found | Transfer inexistant ou appartenant à un autre workspace. | Vérifiez l'ID et l'isolation d'environnement (sandbox vs live). |
| 422 | validation_error | Dépassement des limites sandbox (10 Mo/fichier, 10 fichiers, 25 transferts/24h). | Passez en environnement live ou réduisez la taille des fichiers. |
| 429 | rate_limited | Quota de requêtes par minute dépassé. | Respectez l'en-tête Retry-After retourné par l'API. |
| 500 | internal_error | Erreur interne Coffrify. | Réessayez avec back-off exponentiel. Si le problème persiste, contactez le support. |
Voir aussi
- Référence : MCP tokens
- Référence : Transferts
- Référence : Diagnostics
- Quickstart : Premier transfert en 5 minutes
- Quickstart : Webhooks et événements de transfert
- Guide : Chiffrement AES-256-GCM et modes de transfert