🚀
Agents IA (MCP)·Avancé·10 min

Construire un agent qui crée et livre des transferts automatiquement

Apprenez à orchestrer un agent Python complet qui provisionne un token MCP, crée un transfert chiffré et diagnostique son état via l'API Coffrify.

Télécharger en PDF

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.

ChampTypeRequisDescription
namestringOuiNom lisible du token (ex. : agent-livraison-prod).
descriptionstringNonDescription libre pour l'audit.
environmentstringNon"live" (défaut) ou "test". Détermine le préfixe cof_mcp_live_* ou cof_mcp_test_*.
scopesarrayNonListe de scopes. Défaut : ["transfers:read"]. Pour cet agent : ["transfers:write", "transfers:read"].
client_hintstringNonContexte client. Valeurs acceptées : claude-desktop, claude, cursor, cline, continue, custom.
expires_in_daysintegerNonDurée de validité en jours. Passé ce délai, le token est révoqué automatiquement.
allowed_ipsarrayNonListe CIDR d'IP autorisées. Si absent, toutes les IP sont acceptées.
max_usesintegerNonNombre 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.

ChampTypeRequisDescription
filesarrayOuiTableau d'objets {name, size, mime_type}. Décrit les fichiers à uploader.
transfer_titlestringNonTitre affiché au destinataire.
expires_in_hoursintegerNonDurée de vie du transfert en heures.
max_downloadsintegerNonLimite de téléchargements. En sandbox : plafonné à 5.
passwordstringNonMot de passe d'accès. Activer is_password_protected côté API.
require_totpbooleanNonExige un code TOTP à la réception.
recipientstringNonEmail ou identifiant du destinataire pour la notification.
notify_opensbooleanNonNotifie l'expéditeur à chaque ouverture.
encryption_modestringNonMode de chiffrement. Ex. : "aes-256-gcm".
geo_allowlistarrayNonCodes pays ISO-3166-1 alpha-2 autorisés.
geo_blocklistarrayNonCodes pays ISO-3166-1 alpha-2 bloqués.
watermark_enabledbooleanNonActive le filigrane sur les fichiers téléchargés.
watermark_textstringNonTexte du filigrane (ex. : nom du destinataire).
custom_slugstringNonSlug personnalisé pour l'URL de partage.
auto_deletebooleanNonSupprime le transfert automatiquement après expiration.
scheduled_forstring (ISO 8601)NonDate 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.

import httpx
import os
 
BASE = "https://api.coffrify.com/v1"
ADMIN_KEY = os.environ["COFFRIFY_ADMIN_KEY"] # scope api_keys:manage
 
# -- Etape 1 : créer un token MCP dédié à l'agent --
with httpx.Client() as client:
r = client.post(
f"{BASE}/mcp/tokens",
headers={"Authorization": f"Bearer {ADMIN_KEY}"},
json={
"name": "agent-livraison-prod",
"description": "Token pour livraisons automatiques",
"environment": "live",
"scopes": ["transfers:write", "transfers:read"],
"client_hint": "custom",
"expires_in_days": 30,
},
)
r.raise_for_status()
token_data = r.json()
MCP_TOKEN = token_data["token"]
# Avertissement : ce token n'est visible qu'une seule fois.
# Stockez-le immédiatement dans votre secret manager.
 
# -- Etape 2 : créer un transfert --
FILE_PATH = "/tmp/rapport-2026-Q2.pdf"
file_size = os.path.getsize(FILE_PATH)
 
with httpx.Client() as client:
r = client.post(
f"{BASE}/transfers",
headers={"Authorization": f"Bearer {MCP_TOKEN}"},
json={
"files": [{"name": "rapport-2026-Q2.pdf", "size": file_size, "mime_type": "application/pdf"}],
"transfer_title": "Rapport Q2 2026 - Confidentiel",
"expires_in_hours": 72,
"max_downloads": 3,
"encryption_mode": "aes-256-gcm",
"recipient": "destinataire@example.com",
"notify_opens": True,
},
)
r.raise_for_status()
payload = r.json()
 
transfer = payload["transfer"]
upload_urls = payload["upload_urls"]
share_url = payload["share_url"]
print("Transfer ID :", transfer["id"])
print("Lien de partage :", share_url)
 
# -- Etape 3 : uploader le fichier vers l'URL présignée --
up = upload_urls[0]
with open(FILE_PATH, "rb") as f:
resp = httpx.put(up["url"], content=f.read(), headers=up["headers"])
resp.raise_for_status()
print("Fichier uploadé avec succès.")
 
# -- Etape 4 : diagnostiquer le transfert --
with httpx.Client() as client:
r = client.get(
f"{BASE}/diagnostics/transfer/{transfer['id']}",
headers={"Authorization": f"Bearer {MCP_TOKEN}"},
)
r.raise_for_status()
diag = r.json()
 
print("Verdict :", diag["verdict"])
for check in diag["checks"]:
print(f" [{check['status'].upper()}] {check['check']} : {check['detail']}")
if diag["recommended_actions"]:
print("Actions recommandées :")
for action in diag["recommended_actions"]:
print(f" - {action}")
 

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.

{
"id": "mcp_01HZ3K7V2Q9WXY4ABCDE",
"name": "agent-livraison-prod",
"description": "Token pour livraisons automatiques",
"token_prefix": "cof_mcp_live_3f2a9c7b...",
"scopes": ["transfers:write", "transfers:read"],
"environment": "live",
"client_hint": "custom",
"allowed_ips": null,
"expires_at": "2026-07-06T12:00:00.000Z",
"max_uses": null,
"created_at": "2026-06-06T12:00:00.000Z",
"token": "cof_mcp_live_3f2a9c7b1e4d5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a",
"warning": "Save this token now - it will not be shown again."
}

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.

{
"transfer": {
"id": "txfr_01HZ3K7V2Q9WXY4FGHIJ",
"short_code": "rq2-2026",
"transfer_title": "Rapport Q2 2026 - Confidentiel",
"status": "active",
"expires_at": "2026-06-09T12:00:00.000Z",
"max_downloads": 3,
"total_downloads": 0,
"scan_status": null,
"encryption_mode": "aes-256-gcm",
"created_at": "2026-06-06T12:00:00.000Z"
},
"upload_urls": [
{
"file_id": "rapport-2026-Q2.pdf",
"url": "https://storage.coffrify.com/uploads/txfr_01HZ3K7V2Q9WXY4FGHIJ/rapport-2026-Q2.pdf?X-Amz-Signature=abc123...",
"headers": {
"Content-Type": "application/pdf"
}
}
],
"share_url": "https://files.coffrify.com/rq2-2026",
"totp_secret": null
}

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.

{
"transfer_id": "txfr_01HZ3K7V2Q9WXY4FGHIJ",
"checks": [
{ "check": "lifecycle_status", "status": "ok", "detail": "status = active" },
{ "check": "expiration", "status": "ok", "detail": "expires 2026-06-09T12:00:00.000Z" },
{ "check": "max_downloads", "status": "ok", "detail": "0/3 downloads used" },
{ "check": "scan_status", "status": "ok", "detail": "scan_status = pending/null" }
],
"verdict": "healthy",
"recommended_actions": []
}

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.

HTTPcodeQuandRésolution
400validation_errorname manquant (token MCP) ou files[] vide (transfert).Vérifiez la présence des champs obligatoires dans votre payload.
400validation_errorclient_hint invalide.Utilisez l'une des valeurs : claude-desktop, claude, cursor, cline, continue, custom.
401missing_api_keyHeader Authorization absent.Ajoutez Authorization: Bearer <token> à chaque requête.
401invalid_api_keyToken inconnu, malformé ou révoqué.Vérifiez le préfixe cof_mcp_live_* ou cof_mcp_test_* et l'état du token.
401expired_api_keyToken expiré (expires_at dépassé).Créez un nouveau token via POST /v1/mcp/tokens.
401revoked_api_keyToken révoqué manuellement.Provisionnez un nouveau token.
403scope_missingLe token ne possède pas le scope requis.Ajoutez transfers:write et/ou transfers:read lors de la création du token.
403ip_not_allowedL'IP appelante ne figure pas dans allowed_ips.Vérifiez la plage CIDR configurée ou retirez la restriction.
404not_foundTransfer inexistant ou appartenant à un autre workspace.Vérifiez l'ID et l'isolation d'environnement (sandbox vs live).
422validation_errorDépassement des limites sandbox (10 Mo/fichier, 10 fichiers, 25 transferts/24h).Passez en environnement live ou réduisez la taille des fichiers.
429rate_limitedQuota de requêtes par minute dépassé.Respectez l'en-tête Retry-After retourné par l'API.
500internal_errorErreur 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
Continuer

Autres tutoriels à suivre