MCP est un standard ouvert permettant aux outils IA de se connecter à des services externes. Formstep expose un point de terminaison MCP hébergé auquel tout client compatible MCP peut se connecter, notamment Claude Code, Claude desktop et Cursor.
Deux types de token porteur (bearer) fonctionnent :
fb_...) — créé depuis les tokens API. Idéal pour un
usage personnel et une configuration rapide.
fbo_...) — émis par le flux OAuth. Idéal pour les applications
tierces qui se connectent au nom d’un utilisateur.
Les deux sont liés à exactement un espace de travail et atteignent les mêmes outils. Un appel d’outil qui nomme un autre espace de
travail, ou un formulaire qui s’y trouve, échoue avec FORBIDDEN. Les tokens OAuth portent aussi des portées
mcp:read, mcp:write et offline_access, mais aucun outil n’est aujourd’hui conditionné par elles —
traitez tout token comme un accès complet à l’intérieur de son espace de travail.
Les appels d’outils sont limités à 120 par minute et par token, en commun avec l’API : seul{' '}
tools/call consomme ce budget, tandis que initialize, tools/list, prompts/* et{' '}
resources/* sont gratuits. Au-delà du budget, l’appel renvoie tout de même HTTP 200 avec un résultat d’outil en échec portant{' '}
RATE_LIMITED et un retryAfterMs — sondez sur une minuterie, jamais en boucle.
> Ouvrez OAuth et clés API dans la barre latérale de votre espace de travail pour créer des tokens API et consulter les > applications OAuth connectées. Consultez les tokens API pour un guide pas à pas. >
Chaque outil est annoncé sur tools/list lorsqu’un client se connecte. Les clients qui chargent les schémas à la demande,
comme Claude Code, récupèrent le schéma complet d’un outil quand une tâche en a besoin. Le tableau ci-dessous couvre les outils principaux
par lesquels la plupart des tâches commencent ; load_tools (catalogues) et load_skill (guides métier)
documentent le reste.
D’autres variantes d’insertion — heure, téléchargement de fichier, signature, paiement, matrice/grille, classement, choix d’image, bouton
bascule, tableau, liste, ligne, champ calculé, champ masqué, variable en ligne, contenu intégré (editor_insertEmbedded pour
YouTube, Google Maps ou des intégrations iframe) et un bloc de logique conditionnelle (editor_insertLogic) — sont aussi sur{' '}
tools/list. Chargez load_skill("question-types") pour l’ensemble complet, avec le nom de l’outil et les champs
de chacun. La logique conditionnelle s’écrit avec editor_setLogic dans le catalogue{' '}
editor-actions.
Ces outils sont aussi sur tools/list. Exécutez load_tools avec un nom de catalogue pour obtenir une
documentation enrichie (introduction, schémas complets, patterns d’utilisation, cas limites) pour les outils groupés, puis appelez-les
directement.
Le catalogue request-lifecycle liste les huit outils de demandes car le chat intégré annonce un ensemble principal plus
restreint. Sur ce point de terminaison, les huit sont déjà sur tools/list, donc ce que le catalogue ajoute, c’est la
documentation.
Les compétences sont des guides intégrés que l’agent peut charger via load_skill. Elles fournissent des connaissances métier
qui aident l’agent à prendre de meilleures décisions — pas des schémas d’outils, mais des conseils de conception et la sémantique des
champs.
Une demande assigne un formulaire publié à un destinataire nommé, avec son propre lien, ses propres réponses préremplies, et son propre résultat. C’est ainsi qu’un agent demande quelque chose à une personne réelle et découvre ce qu’elle a répondu.
Commencez toujours par fields_list(formId). Cela renvoie les clés adressables de la version actuellement publiée du
formulaire, chacune avec une ligne usage indiquant dans quel argument la clé doit aller — les questions visibles vont dans{' '}
prefill, les champs cachés dans context. Ne dérivez jamais une clé à partir du titre d’une question, et relisez
après form_publish.
Le résultat contient le lien et l’horloge :
``` { "id": "kd7...", "status": "pending", "url": "https://form.formstep.io/r/rq_...", "deliveryStatus": "queued", "expiresAt": 1780000000000, "createdAt": 1747000000000, "deduplicated": false, "next": "..." } ```
delivery vaut "none" par défaut, ce qui vous donne url à livrer vous-même ; "email"{' '}
envoie l’invitation et nécessite recipient.email sur un plan Pro ou Business, ou sur l’une des 10 invitations gratuites d’un
compte Free. readonly verrouille des champs que le destinataire ne peut pas modifier, et toute clé verrouillée doit aussi
être préremplie. context n’accepte que des clés de champs cachés, tandis que metadata est un suivi opaque
renvoyé dans request_get et dans le callback. expiresAt est en millisecondes epoch, par défaut 30 jours et
plafonné à 365 jours. idempotencyKey est valable à l’échelle de l’espace de travail pendant 30 jours : la même clé avec le
même corps renvoie la demande d’origine avec deduplicated: true, et un corps différent est un conflit. Chaque réponse porte
aussi une ligne next qui indique à l’agent quoi faire ensuite.
deliveryStatus vaut not_requested jusqu’à ce qu’une invitation soit mise en file, puis queued →{' '}
sent ou failed, et bounced une fois que le fournisseur d’e-mail signale un rejet définitif ou une
plainte. Créer une demande dépense une unité de l’allocation mensuelle de l’espace de travail, que le destinataire réponde ou non ; une
fois épuisée, request_create échoue avec MONTHLY_ALLOWANCE_REACHED.
Avec une callbackUrl, Formstep envoie un POST une fois par événement terminal — complétion, expiration, annulation — signé
avec le secret de signature des demandes de l’espace de travail. Voir Callbacks et signature pour le
payload et la recette de vérification.
> Le secret de signature des demandes n’apparaît que sur la page Identifiants de votre espace de travail — il n’est jamais renvoyé via MCP
> ou l’API. Un agent qui s’exécute seul, sans humain pour mettre en place et configurer un récepteur, ne peut donc pas vérifier un
> callback. Omettez callbackUrl et sondez plutôt request_get(requestId), à l’échelle de quelques minutes plutôt
> que de quelques secondes, jusqu’à ce que status quitte "pending". expiresAt borne combien de
> temps cela vaut la peine.
>
Passez test: true pour répéter tout le circuit avant une exécution réelle. Le lien s’ouvre toujours et peut être complété, et
le callback se déclenche avec "test": true — mais rien n’est envoyé par e-mail quoi que dise delivery, la
demande reste masquée de la page Demandes et de l’entonnoir analytique, et sa soumission ne compte nulle part : pas de quota, pas
d’exports, pas d’intégrations. Les demandes de test n’apparaissent dans request_list que si vous passez{' '}
includeTest: true. Le lien se ferme dans les 24 heures, et sur Free un workspace peut créer 10 demandes de test par jour.
Pour remettre un fichier à un destinataire — un projet de contrat, son propre devis — le formulaire a besoin d’un{' '}
bloc Documents, qu’un auteur ou un agent insère avec editor_insertDocumentsBlock. fields_list{' '}
le signale comme type: "documents". Les octets ne transitent jamais par un outil :
document_create avec formId, name, contentType, et le size{' '}
exact en octets. Vous récupérez {'{ id, name, contentType, size, uploadUrl, expiresAt }'}. PDF et images uniquement (pas de
documents Office), 25 Mo par fichier, et 100 Mo de documents par demande.
PUT des octets bruts vers uploadUrl dans l’heure, avec Content-Type réglé sur le type
déclaré.
request_create : documents: [{'{ documentId, field?, name? }'}]. field est
la clé de champ du bloc Documents, optionnelle seulement quand le formulaire a exactement un bloc de ce type. name remplace
le nom d’affichage pour cette demande.
Les documents de l’auteur du bloc restent en place et les vôtres apparaissent en dessous, pour ce seul destinataire.{' '}
request_create vérifie le téléversement avant que la demande n’existe, donc DOCUMENT_NOT_UPLOADED signifie que
l’étape 2 a été sautée. Un téléversement peut être référencé par un nombre quelconque de demandes, et ses octets comptent dans le stockage
de votre espace de travail.
Passez domainId à request_create pour créer le lien sur l’un des{' '}
domaines personnalisés de l’espace de travail. Les ids viennent de{' '}
formShareLink_list, qui les renvoie sous availableCustomDomains. Si vous l’omettez, le lien prend le domaine sur
lequel le formulaire est déjà publié.
request_get renvoie la demande entière. Une fois terminée, answers contient les valeurs du destinataire indexées
par clé de champ, display les mêmes clés en texte lisible, et outcome — approbation, refus ou modifications —
est son verdict quand le formulaire a une question de décision. Un horodatage{' '}
callbackFailedAt signifie que la livraison a épuisé ses tentatives et que rien n’a atteint votre endpoint ; réparez le
récepteur, puis appelez request_replayCallback, qui renvoie l’id de l’événement d’origine pour que votre récepteur déduplique
au lieu de relancer. Une fois que la politique de rétention du formulaire a supprimé une demande, dataPurgedAt est défini et
les réponses sont perdues pour de bon.
request_list balaie plusieurs demandes à la fois, filtrées par status, outcome,{' '}
externalId, et includeTest. Paginez avec nextCursor : une page peut rarement revenir avec des{' '}
items vides et hasMore: true, ce qui ne marque pas la fin de la liste — renvoyez le curseur et continuez.
Chaque compétence et catalogue d’outils est aussi une ressource MCP à skill://<nom> — skill://requests,{' '}
skill://editor-inserts. Un client qui prend en charge resources/list peut les parcourir et les lire sans appeler{' '}
load_skill ou load_tools. Le serveur sert aussi quatre prompts sur prompts/list :{' '}
identity, capabilities, data_tools, et editor_tools.
Chaque outil porte les indices MCP readOnlyHint et destructiveHint, dérivés de son verbe. Ces outils sont
marqués comme destructifs, car les annuler nécessite un autre appel ou n’est pas possible : form_delete,{' '}
form_unpublish, workspaceFolder_delete, editor_deleteElement,{' '}
translationLanguage_delete, et request_cancel. La plupart des clients demandent une confirmation à l’utilisateur
avant de les exécuter, mais l’invite reste la décision du client — vérifiez ses paramètres d’approbation si vous avez besoin d’un blocage
strict.
http(s):// ou data:image. Un document par demande fait exception :{' '}
document_create renvoie une URL de téléversement qu’un client avec accès HTTP peut cibler avec PUT (voir{' '}
Documents par demande). Pour transformer un PDF ou une capture d’écran en formulaire, utilisez le{' '}
chat IA intégré.
load_skill) sont disponibles via MCP.
La plupart des clients se connectent avec OAuth : ajoutez l’URL sans en-tête et suivez{' '} Connecter un agent IA. Un client qui ne peut pas ouvrir de navigateur, comme un script, un job CI ou un agent headless, envoie plutôt un token API en en-tête.
Claude Code, en ligne de commande :
``` claude mcp add --transport http formstep https://api.formstep.io/api/mcp \ --header "Authorization: Bearer fb_YOUR_TOKEN" ```
Ou dans le .mcp.json d’un projet :
Cursor, dans .cursor/mcp.json ou ~/.cursor/mcp.json :
Pour vous connecter avec OAuth plutôt qu’avec un token, utilisez{' '} Ajouter à Cursor . Cela ajoute l’URL du serveur sans en-tête, et Cursor vous demande de vous connecter à Formstep.
Les autres clients prennent la même URL et le même en-tête ; consultez leur documentation pour savoir où les placer.
Une application tierce qui se connecte au nom d’un utilisateur devrait utiliser OAuth plutôt que de demander un token collé à la main.
Formstep est un serveur d’autorisation OAuth 2.1 avec PKCE obligatoire (S256) et des tokens opaques — pas de JWT, pas de grant implicite.
Claude desktop, Claude Code et le connecteur web Claude.ai découvrent tout cela depuis le point de terminaison MCP, donc coller l’URL sans
en-tête suffit : le 401 pointe vers /.well-known/oauth-protected-resource, et le client prend le relais à partir de là.
Le flux, pour un client que vous écrivez vous-même :
GET /.well-known/oauth-protected-resource, puis GET /.well-known/oauth-authorization-server pour les URLs des
points de terminaison, les portées et les méthodes d’authentification prises en charge.
POST /oauth/register avec vos redirect_uris (enregistrement de client dynamique, aucun identifiant requis).
Vous obtenez un client_id, plus un client_secret si vous avez demandé autre chose que{' '}
token_endpoint_auth_method: "none". Les URIs de redirection doivent être en HTTPS, ou en HTTP sur localhost.
L’enregistrement est plafonné à 20 par heure et par IP.
/oauth/authorize avec response_type=code, votre client_id, le{' '}
redirect_uri enregistré, scope=mcp:read mcp:write offline_access, state, et un{' '}
code_challenge avec code_challenge_method=S256. Il se connecte, choisit un espace de travail, et autorise.
POST /oauth/token avec grant_type=authorization_code et votre code_verifier,
dans les 60 secondes. Les codes sont à usage unique.
Authorization: Bearer fbo_.... Les tokens d’accès durent 1 heure ; les tokens de
rafraîchissement durent 30 jours et tournent à chaque utilisation. Réutiliser un token de rafraîchissement déjà consommé brûle toute la
chaîne, donc conservez le plus récent.
POST /oauth/revoke (RFC 7009) révoque un token d’accès ou de rafraîchissement. Un utilisateur peut aussi déconnecter toute
l’application depuis Applications connectées sur la page OAuth et clés API, ce qui tue tous les tokens qu’elle détient
pour cet espace de travail.
Si vous avez déjà un token en main, il va au même endroit qu’une clé API :
``` { "mcpServers": { "formstep": { "type": "http", "url": "https://api.formstep.io/api/mcp", "headers": { "Authorization": "Bearer fbo_USER_OAUTH_TOKEN" } } } } ```Chaque connexion OAuth est listée sous Applications connectées sur la page OAuth et clés API, avec la date de connexion et de dernière utilisation. Les connexions sont personnelles : seul l’utilisateur qui a autorisé une connexion peut la voir, et les administrateurs de l’espace de travail ne peuvent ni la consulter ni la révoquer pour un autre membre. La déconnexion prend effet immédiatement. Un utilisateur qui quitte l’espace de travail ou en est retiré perd toutes ses connexions à celui-ci.