⚡

Créer des custom actions MCP pour automatiser un workflow

Apprenez à créer, configurer et invoquer des custom actions MCP pour brancher vos propres workflows sur l'API Coffrify.

Les custom actions MCP permettent d'enregistrer dans votre workspace des outils personnalisés exposés via le protocole MCP (Model Context Protocol). Une custom action décrit à un agent IA quels paramètres accepter, comment les mapper sur un endpoint de l'API Coffrify, et quel scope est requis pour l'invoquer. Deux runtimes sont disponibles : json (mapping déclaratif vers un endpoint existant) et typescript (code hébergé exécuté côté serveur). Une fois créée, l'action apparaît automatiquement dans la liste des outils MCP du workspace et peut être invoquée par Claude Desktop, Cursor ou tout client MCP compatible.

GET/v1/mcp/custom-actionsLister toutes les custom actions du workspace (ordre anti-chronologique).POST/v1/mcp/custom-actionsCréer une nouvelle custom action dans le workspace.PATCH/v1/mcp/custom-actions/{id}Mettre à jour une custom action existante (description, scope, is_active, mapping, code).DELETE/v1/mcp/custom-actions/{id}Supprimer définitivement une custom action (suppression physique).

Authentification

Le GET /v1/mcp/custom-actions est accessible avec n'importe quelle clé authentifiée (aucun scope supplémentaire). Les opérations d'écriture (POST, PATCH, DELETE) exigent le scope api_keys:manage. Passez votre clé dans l'en-tête Authorization: Bearer cof_live_… (ou cof_test_… en environnement de test). Toute requête sans clé valide retourne 401 invalid_api_key.

Corps de la requête POST

La création d'une custom action déclare son nom, son runtime et le mapping vers l'API Coffrify. Le tableau ci-dessous détaille les champs acceptés.

Champ	Type	Requis	Description
name	string	Oui	Identifiant snake_case minuscule, 3 à 64 caractères (regex : `^[a-z][a-z0-9_]{2,63}$`). Unique dans le workspace.
description	string	Oui	Description lisible par l'agent IA (max 500 caractères). Définit la documentation de l'outil MCP.
runtime_kind	string	Non	Valeur `json` (défaut) ou `typescript`. Détermine le mode d'exécution de l'action.
required_scope	string	Non	Scope Coffrify requis à l'invocation. Défaut : `transfers:read`. Exemples : `documents:write`, `files:read`.
endpoint_method	string	Non (json)	Méthode HTTP cible : `GET`, `POST`, `PATCH` ou `DELETE`. Ignoré si `runtime_kind=typescript`.
endpoint_path	string	Non (json)	Chemin de l'API cible, obligatoirement préfixé par `/v1/`. Max 500 caractères. Ignoré si `runtime_kind=typescript`.
input_schema	object	Non	JSON Schema (draft-07) décrivant les paramètres d'entrée de l'action. Défaut : schéma vide.
param_mapping	array	Non	Tableau de règles de mapping entre les paramètres d'entrée et les paramètres de la requête cible.
code_source	string	Oui (typescript)	Code TypeScript hébergé (max 50 Ko). Obligatoire si `runtime_kind=typescript`.

Corps de la requête PATCH

La mise à jour accepte les mêmes champs, tous optionnels : ne transmettez que ceux que vous voulez modifier. Voici les champs disponibles.

Champ	Type	Description
description	string	Nouvelle description (max 500 caractères).
required_scope	string	Nouveau scope requis à l'invocation.
is_active	boolean	Active (`true`) ou désactive (`false`) l'action sans la supprimer.
input_schema	object	Nouveau JSON Schema des paramètres d'entrée.
endpoint_method	string	Nouvelle méthode HTTP cible (`GET`, `POST`, `PATCH`, `DELETE`).
endpoint_path	string	Nouveau chemin cible, préfixé `/v1/`.
param_mapping	array	Nouveau tableau de règles de mapping.
code_source	string	Nouveau code TypeScript hébergé (runtime `typescript` uniquement).

Exemples d'appel

Les exemples ci-dessous créent une custom action puis la listent. Choisissez votre langage.

# Créer une custom action (runtime json)
curl -X POST https://api.coffrify.com/v1/mcp/custom-actions \
  -H "Authorization: Bearer cof_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_recent_transfers",
    "description": "Retourne les 20 derniers transferts du workspace pour un audit rapide.",
    "runtime_kind": "json",
    "required_scope": "transfers:read",
    "endpoint_method": "GET",
    "endpoint_path": "/v1/transfers",
    "input_schema": {
      "type": "object",
      "properties": {
        "limit": { "type": "integer", "description": "Nombre de transferts à retourner (max 100)", "default": 20 }
      },
      "required": []
    },
    "param_mapping": [
      { "from": "limit", "to": "limit", "in": "query" }
    ]
  }'

Réponse

En cas de succès, POST retourne un HTTP 201 avec l'objet créé. PATCH retourne HTTP 200 avec l'objet mis à jour. DELETE retourne HTTP 200 avec { "deleted": true }. GET retourne un objet paginé { "object": "list", "data": [...] }.

// POST 201, objet créé
{
  "id": "ca_01hwx3k9p2f8bnmqvrt5zd6yej",
  "name": "get_recent_transfers",
  "description": "Retourne les 20 derniers transferts du workspace pour un audit rapide.",
  "required_scope": "transfers:read",
  "input_schema": {
    "type": "object",
    "properties": {
      "limit": { "type": "integer", "description": "Nombre de transferts à retourner (max 100)", "default": 20 }
    },
    "required": []
  },
  "endpoint_method": "GET",
  "endpoint_path": "/v1/transfers",
  "param_mapping": [
    { "from": "limit", "to": "limit", "in": "query" }
  ],
  "runtime_kind": "json",
  "is_active": true,
  "created_at": "2026-06-06T09:14:32.000Z"
}

// GET 200, liste des actions
{
  "object": "list",
  "data": [
    {
      "id": "ca_01hwx3k9p2f8bnmqvrt5zd6yej",
      "name": "get_recent_transfers",
      "description": "Retourne les 20 derniers transferts du workspace pour un audit rapide.",
      "required_scope": "transfers:read",
      "input_schema": { "type": "object", "properties": {}, "required": [] },
      "endpoint_method": "GET",
      "endpoint_path": "/v1/transfers",
      "param_mapping": [],
      "runtime_kind": "json",
      "code_source": null,
      "is_active": true,
      "invocation_count": 47,
      "last_invoked_at": "2026-06-06T08:55:11.000Z",
      "created_at": "2026-06-01T10:00:00.000Z",
      "updated_at": "2026-06-05T16:22:00.000Z"
    }
  ]
}

Erreurs

Les erreurs portent sur un mapping invalide, un scope insuffisant ou une action introuvable. Le tableau ci-dessous indique la résolution.

HTTP	Code	Quand	Résolution
400	`validation_error`	`name` absent, format invalide (snake_case 3-64 chars) ou `description` dépasse 500 caractères.	Vérifiez le format du champ `name` : minuscules, chiffres et underscores, commençant par une lettre.
400	`validation_error`	`endpoint_path` ne commence pas par `/v1/` ou contient des caractères CRLF.	Préfixez le chemin avec `/v1/` et supprimez tout retour chariot.
400	`validation_error`	`endpoint_method` n'est pas `GET`, `POST`, `PATCH` ou `DELETE`.	Utilisez exclusivement l'une des quatre valeurs autorisées.
400	`validation_error`	`code_source` absent alors que `runtime_kind=typescript`, ou dépasse 50 Ko.	Fournissez un code TypeScript valide de moins de 50 000 caractères.
400	`validation_error`	Aucun champ valide fourni dans un `PATCH`.	Incluez au moins un champ modifiable dans le corps de la requête.
401	`invalid_api_key`	Clé absente, malformée ou révoquée.	Vérifiez que l'en-tête `Authorization: Bearer cof_live_…` est bien présent et actif.
403	`scope_missing`	La clé ne possède pas le scope `api_keys:manage` (POST, PATCH, DELETE).	Régénérez la clé avec le scope `api_keys:manage` dans la console Coffrify.
404	`not_found`	L'`id` fourni n'existe pas dans ce workspace.	Vérifiez l'identifiant via `GET /v1/mcp/custom-actions`.
409	`validation_error`	Une action portant ce `name` existe déjà dans le workspace.	Choisissez un nom unique ou mettez à jour l'action existante via `PATCH`.
429	`rate_limited`	Quota de requêtes dépassé (écriture).	Respectez le quota indiqué dans `X-RateLimit-Limit` et attendez `Retry-After` secondes.
500	`internal_error`	Erreur interne inattendue.	Réessayez en utilisant le `X-Request-Id` retourné pour contacter le support.

Bonnes pratiques

Bonnes pratiques pour les custom actions MCP

Privilégiez le runtime json pour les actions de lecture simple : il ne nécessite pas de déploiement de code et bénéficie automatiquement du rate-limiting et de l'audit log. Utilisez runtime_kind=typescript uniquement lorsque vous avez besoin de logique de transformation ou d'agrégation entre plusieurs endpoints. Renseignez toujours un input_schema précis avec les descriptions de chaque propriété : l'agent IA s'en sert pour comprendre quels paramètres passer. Choisissez le required_scope le moins permissif possible (ex. transfers:read plutôt que transfers:write pour une action de consultation). Désactivez une action via PATCH { "is_active": false } plutôt que de la supprimer : vous conservez ainsi l'historique d'invocations (invocation_count, last_invoked_at). Stockez vos clés dans des variables d'environnement et n'utilisez jamais une clé cof_live_… dans le code source versionnés : utilisez cof_test_… ou cof_sandbox_… dans vos environnements de développement.

Voir aussi

Authentification et clés API
Tokens MCP : créer et faire pivoter
Outils MCP disponibles dans le workspace
Scopes et permissions
Rate limiting et quotas
Référence complète MCP custom actions

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→