Piloter l'API depuis un agent

Ce que c'est

Le serveur MCP est un petit processus qui parle le Model Context Protocol en stdio. Il donne à un agent, ou à un script qui en tient lieu, la même surface de création de workflow que celle décrite dans Modèles, Sections et thème et Variables et données, sous forme d'outils appelables, afin que construire ou inspecter un workflow ne nécessite pas de navigateur.

Ce n'est pas une surface d'API supplémentaire. Chaque outil est une fine enveloppe autour des endpoints REST documentés sur ces pages : rien de ce qu'il renvoie ne vient d'ailleurs, et rien de ce qu'il refuse n'est refusé pour une raison que ces pages ne donnent pas déjà.

Les workflows sont en bêta privée, disponible sur demande à [email protected] ; voir Workflows.

Ce qu'il encode que l'API REST ne peut pas

Deux choses qu'un client HTTP ordinaire n'a aucun moyen de connaître à partir de la seule forme des endpoints.

L'ordre dans lequel les opérations devraient se dérouler. Rien n'empêche un appelant d'écrire le contenu d'une section avant que la variable qu'elle cite n'existe, ou avant que le thème ne soit réglé : les deux s'enregistrent proprement et échouent plus tard, silencieusement. Voir Construire un workflow de bout en bout pour cet ordre, ainsi que les étapes que l'API impose réellement et celles dont elle ne fait que déconseiller l'omission.

Les échecs qui répondent 200. Une balise supprimée, une clé de placement mal orthographiée, un token inerte, une image que le moteur de rendu ne peut pas atteindre, une valeur de thème qui se fige silencieusement : aucun de ces cas ne refuse l'écriture qui les a provoqués. Voir Les échecs qui répondent 200 pour la liste complète et la manière de repérer chacun d'eux.

Il ne détient aucun catalogue propre. Tout ce qu'un appelant a besoin de savoir sur ce qu'il peut écrire, les kind, les opérateurs, les clés de placement, les plafonds de l'organisation, provient d'un appel en direct à workflow_capabilities, exactement comme Capabilities fait foi, ce n'est pas une copie le décrit pour l'endpoint REST sous-jacent. Une copie codée en dur dans un guide, ou dans la mémoire d'un client, finirait par être fausse.

Une dernière chose à savoir avant une première écriture : tant qu'un humain détient le verrou d'édition du workflow dans le constructeur, chaque écriture via ce serveur est refusée avec 409, exactement comme en REST simple. Voir Comportement commun.

Le lancer

npm install
npm run build
DOCLIFT_API_KEY="<la clé envoyée dans X-Api-Key>" DOCLIFT_API_URL="https://app.doclift.io" node dist/index.js

La clé doit appartenir à une organisation pour laquelle les workflows sont activés, et elle porte exactement les droits qu'elle porte sur l'API REST : pas plus.

Un client déclare ce serveur comme n'importe quel autre serveur MCP, en stdio :

{
  "mcpServers": {
    "doclift-workflows": {
      "command": "node",
      "args": ["/path/to/mcp/dist/index.js"],
      "env": {
        "DOCLIFT_API_KEY": "...",
        "DOCLIFT_API_URL": "..."
      }
    }
  }
}

Les cinq guides

En plus de ses outils, le serveur expose cinq ressources en lecture seule : de la prose que la forme de l'API ne peut pas porter seule.

Tout ce qu'ils contiennent de factuel est déjà couvert par Workflows, Publier un workflow et Les échecs qui répondent 200. Lire un guide avant une écriture ne fait qu'économiser un aller-retour vers workflow_capabilities.

La génération n'est pas un mécanisme séparé

workflow_render enveloppe un unique endpoint déjà existant : POST /api/v1/document_requests, avec une seule entrée dans document_generations. Il n'ajoute aucune logique propre : il n'accepte rien que l'endpoint lui-même refuserait, donc le workflow doit toujours être publié au préalable. Voir Créer une demande de document pour la forme de la requête et de la réponse, et Modèles workflow pour ce que variables doit satisfaire avant d'appeler cet outil.

L'auto-diagnostic est une composition, pas une nouvelle logique

workflow_selfcheck appelle trois endpoints de lecture déjà documentés ailleurs et réduit leurs réponses en une liste de vérifications : POST .../validate, GET .../templates/:id, et GET .../payload_contract. Il n'ajoute aucune logique côté serveur ni aucune donnée qu'un appelant ne pourrait déjà lire directement.

Chaque ligne affiche pass, todo, ou unknown, jamais un simple pass quand la preuve en était absente d'une réponse : un auto-diagnostic qui lirait le silence comme un succès manquerait sa propre raison d'être.

La seule ligne qu'un auto-diagnostic ne peut jamais valider

Tout ce qui précède cette ligne est une lecture de l'état propre du workflow : anomalies, tokens, images, polices, horodatages. Cette dernière ligne ne l'est pas, car cette information n'existe nulle part où l'outil pourrait la lire. Que le texte, l'ordre des sections et les valeurs placées à la position des tokens correspondent à ce qui a réellement été demandé est un jugement que seul l'appelant détenant la requête d'origine peut porter : récupérez l'URL que renvoie workflow_render, et lisez le fichier.

Traitez un auto-diagnostic dont tout le reste passe comme un workflow mécaniquement sain, pas comme un workflow confirmé correct.

Suite