Se connecterCommencer gratuitement
Référence APICréer une action personnalisée MCP
POST/v1/mcp/custom-actions

Créer une action personnalisée MCP

Crée une action personnalisée MCP (relais d'endpoint JSON ou code TypeScript) dans le workspace courant.

2 min de lectureTélécharger en PDF

Requête exemple

{
  "name": "approve_pending_transfer",
  "description": "Approuve un transfert en attente et notifie le destinataire.",
  "input_schema": {
    "type": "object",
    "required": [
      "transfer_id"
    ],
    "properties": {
      "transfer_id": {
        "type": "string"
      }
    }
  },
  "runtime_kind": "json",
  "endpoint_path": "/v1/transfers/{transfer_id}/approve",
  "param_mapping": [
    {
      "to": "path.transfer_id",
      "from": "transfer_id"
    }
  ],
  "required_scope": "transfers:write",
  "endpoint_method": "POST"
}

Réponse exemple

{
  "id": "mca_8f1c2d3e4b5a6789",
  "name": "approve_pending_transfer",
  "is_active": true,
  "created_at": "2026-06-05T10:22:00.000Z",
  "description": "Approuve un transfert en attente et notifie le destinataire.",
  "input_schema": {
    "type": "object",
    "required": [
      "transfer_id"
    ],
    "properties": {
      "transfer_id": {
        "type": "string"
      }
    }
  },
  "runtime_kind": "json",
  "endpoint_path": "/v1/transfers/{transfer_id}/approve",
  "param_mapping": [
    {
      "to": "path.transfer_id",
      "from": "transfer_id"
    }
  ],
  "required_scope": "transfers:write",
  "endpoint_method": "POST"
}
POST/v1/mcp/custom-actionsCrée une action personnalisée MCP dans le workspace courant et renvoie l'objet créé avec un statut 201.

Cette route crée une nouvelle action personnalisée MCP exposée aux clients MCP du workspace. Deux modes d'exécution (runtime_kind) sont pris en charge : json, qui relaie un appel vers un endpoint de l'API Coffrify (endpoint_method + endpoint_path requis), et typescript, qui exécute du code fourni dans code_source. L'action est créée active (is_active = true) et rattachée au workspace et à l'utilisateur du jeton. En cas de succès, l'API renvoie un statut 201 avec l'objet créé.

Comportement notable : le nom doit être en snake_case minuscule et unique dans le workspace ; une collision renvoie une erreur 409. Le endpoint_path (mode json) est validé pour empêcher toute évasion hors de la surface API Coffrify (il doit commencer par /v1/, sans caractères CR/LF, et ne pas dépasser 500 caractères).

Authentification

Cet endpoint requiert le scope api_keys:manage. Un jeton qui ne porte pas ce scope reçoit une erreur scope_missing (403). Fournissez le jeton via Authorization: Bearer cof_live_....

Corps de la requête

ChampTypeRequisDescription
namestringOuiNom technique de l'action, snake_case minuscule, 3-64 caractères (motif ^[a-z][a-z0-9_]{2,63}$). Unique par workspace.
descriptionstringOuiDescription lisible (max 500 caractères) présentée à l'agent MCP.
required_scopestringNonScope requis pour invoquer l'action via MCP. Défaut : transfers:read.
runtime_kindstringNonjson (relais d'endpoint, défaut) ou typescript (code). Toute autre valeur est ramenée à json.
code_sourcestringConditionnelCode TypeScript. Requis et non vide si runtime_kind=typescript, max 50 000 caractères. Ignoré (mis à null) en mode json.
endpoint_methodstringConditionnelMéthode HTTP cible : GET (défaut), POST, PATCH ou DELETE. Validée en mode json.
endpoint_pathstringConditionnelChemin cible de l'API Coffrify. Requis et validé en mode json : doit commencer par /v1/, sans CR/LF, max 500 caractères. Défaut /v1/me en stockage.
input_schemaobjectNonSchéma JSON des paramètres d'entrée. Défaut : {type:"object", properties:{}, required:[]}.
param_mappingarrayNonTableau de règles de mappage des paramètres d'entrée vers la requête cible. Défaut : [].

Réponse

En cas de succès, la réponse a un statut 201 et contient l'objet action créé : id, name, description, required_scope, input_schema, endpoint_method, endpoint_path, param_mapping, runtime_kind, is_active et created_at. Notez que code_source n'est pas renvoyé dans la réponse de création.

Erreurs

CodeQuandRésolution
validation_error (400)name manquant ou hors motif, description manquante ou >500 caractères, runtime_kind=typescript sans code_source (ou >50KB), endpoint_method invalide, ou endpoint_path invalide (sans /v1/, CR/LF, >500).Corrigez le champ signalé dans le message avant de réessayer.
scope_missing (403)Le jeton ne porte pas le scope api_keys:manage.Émettez ou utilisez une clé disposant du scope api_keys:manage.
conflict (409)Une action portant le même name existe déjà dans le workspace.Choisissez un nom unique ou mettez à jour l'action existante.
missing_api_key (401)Aucun en-tête Authorization fourni.Ajoutez l'en-tête Authorization: Bearer cof_live_....
rate_limited (429)Quota de requêtes en écriture du workspace dépassé.Respectez l'en-tête Retry-After et réessayez.
internal_error (500)Erreur d'insertion en base non liée à un doublon.Réessayez ; fournissez le request_id au support si le problème persiste.

Voir aussi