MCP ist ein offener Standard, über den KI-Tools eine Verbindung zu externen Diensten herstellen. Formstep stellt einen gehosteten MCP-Endpunkt bereit, mit dem sich jeder MCP-kompatible Client verbinden kann – darunter Claude Code, Claude Desktop und Cursor.
Zwei Arten von Bearer-Token funktionieren:
fb_...) — erstellt über API-Tokens. Ideal für den
persönlichen Gebrauch und eine schnelle Einrichtung.
fbo_...) — wird vom OAuth-Flow ausgestellt. Ideal für
Drittanbieter-Apps, die im Auftrag eines Nutzers eine Verbindung herstellen.
Beide sind an genau einen Arbeitsbereich gebunden und erreichen dieselben Tools. Ein Tool-Aufruf, der einen anderen Arbeitsbereich oder
ein Formular darin nennt, schlägt mit FORBIDDEN fehl. OAuth-Token tragen außerdem Scopes (mcp:read,{' '}
mcp:write, offline_access), aber heute ist kein Tool davon abhängig — behandle jedes Token als vollen Zugriff
innerhalb seines Arbeitsbereichs.
Tool-Aufrufe sind auf 120 pro Minute pro Token begrenzt, gemeinsam genutzt mit der API: Nur{' '}
tools/call verbraucht das Budget, während initialize, tools/list, prompts/* und{' '}
resources/* kostenlos sind. Bei Überschreitung liefert der Aufruf trotzdem HTTP 200 mit einem fehlgeschlagenen Tool-Ergebnis,
das RATE_LIMITED und ein retryAfterMs trägt — polle mit einem Timer, nie in einer Schleife.
> Öffne OAuth und API-Schlüssel in der Seitenleiste deines Arbeitsbereichs, um API-Tokens zu erstellen und verbundene > OAuth-Apps anzuzeigen. Weitere Informationen findest du unter API-Tokens. >
Jedes Tool wird über tools/list angezeigt, wenn sich ein Client verbindet. Clients, die Schemas bei Bedarf laden, etwa Claude
Code, rufen das vollständige Schema eines Tools ab, sobald eine Aufgabe es braucht. Die folgende Tabelle deckt die Kern-Tools ab, mit
denen die meisten Aufgaben beginnen; load_tools (Kataloge) und load_skill (Domänenleitfäden) dokumentieren den
Rest.
Weitere Insert-Varianten — Uhrzeit, Dateiupload, Unterschrift, Zahlung, Matrix/Raster, Rangordnung, Bildauswahl, Umschalter, Tabelle,
Liste, Zeile, berechnetes Feld, verstecktes Feld, Inline-Variable, eingebettete Inhalte (editor_insertEmbedded für YouTube,
Google Maps oder iframe-Einbettungen) und ein Block für bedingte Logik (editor_insertLogic) — stehen ebenfalls auf{' '}
tools/list. Lade load_skill("question-types") für den vollständigen Satz, jeweils mit Tool-Name und Feldern.
Bedingte Logik wird mit editor_setLogic im editor-actions-Katalog erstellt.
Auch diese Tools stehen auf tools/list. Führe load_tools mit einem Katalognamen aus, um erweiterte Dokumentation
(Einführung, vollständige Schemas, Verwendungsmuster, Grenzfälle) für die gruppierten Tools zu erhalten, und rufe sie dann direkt auf.
Der Katalog request-lifecycle listet alle acht Request-Tools auf, weil der In-App-Chat ein kleineres Kern-Set anzeigt. Über
diesen Endpunkt sind bereits alle acht über tools/list verfügbar, sodass der Katalog nur Dokumentation hinzufügt.
Skills sind integrierte Leitfäden, die der Agent über load_skill laden kann. Sie liefern Domänenwissen, das dem Agenten
hilft, bessere Entscheidungen zu treffen – keine Tool-Schemas, sondern Designhinweise und Feldsemantik.
Ein Request weist ein veröffentlichtes Formular einer namentlich bekannten empfangenden Person zu, mit eigenem Link, eigenen vorausgefüllten Antworten und eigenem Ergebnis. So bittet ein Agent eine echte Person um etwas und erfährt, was sie geantwortet hat.
Starte immer mit fields_list(formId). Es liefert die ansprechbaren Schlüssel der aktuell veröffentlichten Version des
Formulars, jeweils mit einer usage-Zeile, die sagt, in welches Argument der Schlüssel gehört — sichtbare Fragen gehören in{' '}
prefill, versteckte Felder in context. Leite einen Schlüssel niemals aus einem Fragetitel ab, und lies nach{' '}
form_publish erneut ein.
Das Ergebnis liefert den Link und die Uhr:
``` { "id": "kd7...", "status": "pending", "url": "https://form.formstep.io/r/rq_...", "deliveryStatus": "queued", "expiresAt": 1780000000000, "createdAt": 1747000000000, "deduplicated": false, "next": "..." } ```
delivery ist standardmäßig "none", wodurch du url zur eigenen Zustellung erhältst;{' '}
"email" versendet die Einladung und braucht recipient.email auf einem Pro- oder Business-Plan, oder eine der 10
kostenlosen Einladungen eines Free-Kontos. readonly sperrt Felder, die die empfangende Person nicht bearbeiten darf, und
jeder gesperrte Schlüssel muss auch vorausgefüllt sein. context nimmt nur Schlüssel versteckter Felder an, während{' '}
metadata undurchsichtige Buchhaltung ist, die bei request_get und im Callback zurückgespiegelt wird.{' '}
expiresAt sind Epoch-Millisekunden, standardmäßig 30 Tage im Voraus und maximal 365 Tage. idempotencyKey ist 30
Tage lang arbeitsbereichsweit gültig: derselbe Schlüssel mit demselben Body liefert den ursprünglichen Request mit{' '}
deduplicated: true zurück, ein abweichender Body ist ein Konflikt. Jede Antwort trägt außerdem eine next-Zeile,
die dem Agenten sagt, was von hier aus zu tun ist.
deliveryStatus ist not_requested, bis eine Einladung eingereiht wird, dann queued →{' '}
sent oder failed, und bounced, sobald der Mail-Anbieter einen Hard Bounce oder eine Beschwerde
meldet. Einen Request zu erstellen verbraucht eine Einheit des monatlichen Kontingents des Arbeitsbereichs, egal ob die empfangende Person
je antwortet; ist es aufgebraucht, schlägt request_create mit MONTHLY_ALLOWANCE_REACHED fehl.
Mit einer callbackUrl sendet Formstep einmal pro Endzustand — Abschluss, Ablauf, Stornierung — einen POST, signiert mit dem
Request-Signaturgeheimnis des Arbeitsbereichs. Siehe Callbacks und Signierung für die Payload und das
Verifizierungsrezept.
> Das Request-Signaturgeheimnis erscheint ausschließlich auf der Credentials-Seite deines Arbeitsbereichs — es wird niemals über MCP oder
> die API zurückgegeben. Ein Agent, der eigenständig läuft, ohne dass ein Mensch einen Empfänger aufsetzt und konfiguriert, kann einen
> Callback daher nicht verifizieren. Lass callbackUrl weg und polle stattdessen request_get(requestId), eher im
> Minuten- als im Sekundentakt, bis status "pending" verlässt. expiresAt begrenzt, wie lange sich
> das lohnt.
>
Übergib test: true, um die gesamte Verkabelung vor einem echten Lauf durchzuspielen. Der Link öffnet sich weiterhin und lässt
sich abschließen, und der Callback feuert mit "test": true — aber es wird nichts per E-Mail versendet, egal was{' '}
delivery sagt, der Request bleibt auf der Requests-Seite und im Analytics-Funnel verborgen, und seine Einreichung zählt
nirgends: kein Kontingent, keine Exporte, keine Integrationen. Testanfragen erscheinen in request_list nur, wenn du{' '}
includeTest: true übergibst. Der Link schließt sich innerhalb von 24 Stunden, und auf Free darf ein Workspace 10 Testanfragen
pro Tag erstellen.
Um einer empfangenden Person eine Datei zu übergeben — einen Vertragsentwurf, ihr eigenes Angebot — braucht das Formular einen{' '}
Dokumente-Block, den ein Autor oder ein Agent mit editor_insertDocumentsBlock einfügt.{' '}
fields_list meldet ihn als type: "documents". Die Bytes wandern nie durch ein Tool:
document_create auf mit formId, name, contentType und der exakten{' '}
size in Bytes. Du bekommst {'{ id, name, contentType, size, uploadUrl, expiresAt }'} zurück. Nur PDF und
Bilder (keine Office-Dokumente), 25 MB pro Datei und 100 MB Dokumente pro Request.
PUTe die rohen Bytes innerhalb einer Stunde an uploadUrl, mit Content-Type auf den deklarierten
Typ gesetzt.
request_create aus: documents: [{'{ documentId, field?, name? }'}]. field{' '}
ist der Feldschlüssel des Dokumente-Blocks, nur optional, wenn das Formular genau einen solchen Block hat. name{' '}
überschreibt den Anzeigenamen für diesen Request.
Die vom Autor hinterlegten Dokumente bleiben unverändert, und deine erscheinen darunter, nur für diese empfangende Person.{' '}
request_create prüft den Upload, bevor der Request existiert, sodass DOCUMENT_NOT_UPLOADED bedeutet, dass
Schritt 2 übersprungen wurde. Ein Upload kann von beliebig vielen Requests referenziert werden, und seine Bytes zählen gegen deinen
Workspace-Speicher.
Übergib domainId an request_create, um den Link auf einer der{' '}
benutzerdefinierten Domains des Arbeitsbereichs zu erstellen. Die IDs kommen von{' '}
formShareLink_list, das sie als availableCustomDomains zurückgibt. Lässt du sie weg, nimmt der Link die Domain,
unter der das Formular bereits veröffentlicht ist.
request_get liefert den gesamten Request. Sobald er abgeschlossen ist, enthält answers die Werte der
empfangenden Person, indiziert nach Feldschlüssel, display dieselben Schlüssel als lesbarer Text, und outcome —
Zustimmung, Ablehnung oder Änderungswunsch — ist ihr Urteil, wenn das Formular eine Entscheidungsfrage{' '}
hat. Ein callbackFailedAt-Zeitstempel bedeutet, dass die Zustellung keine Versuche mehr übrig hatte und nichts bei deinem
Endpunkt ankam; behebe das Problem beim Empfänger und rufe dann request_replayCallback auf, das die ursprüngliche Event-ID
erneut sendet, sodass dein Empfänger dedupliziert, statt erneut zu laufen. Nachdem die Aufbewahrungsrichtlinie des Formulars einen Request
entfernt hat, ist dataPurgedAt gesetzt und die Antworten sind endgültig verloren.
request_list fasst viele auf einmal zusammen, gefiltert nach status, outcome,{' '}
externalId und includeTest. Blättere mit nextCursor: eine Seite kann selten mit leeren{' '}
items und hasMore: true zurückkommen — das ist nicht das Ende der Liste, gib den Cursor zurück und mach weiter.
Jeder Skill und Tool-Katalog ist außerdem eine MCP-Ressource unter skill://<name> — skill://requests,{' '}
skill://editor-inserts. Ein Client, der resources/list unterstützt, kann sie durchsuchen und lesen, ohne{' '}
load_skill oder load_tools aufzurufen. Der Server liefert außerdem vier Prompts über prompts/list:{' '}
identity, capabilities, data_tools und editor_tools.
Jedes Tool trägt die MCP-Hinweise readOnlyHint und destructiveHint, abgeleitet von seinem Verb. Diese Tools sind
als destruktiv markiert, weil sie sich nur mit einem weiteren Aufruf rückgängig machen lassen oder gar nicht: form_delete,{' '}
form_unpublish, workspaceFolder_delete, editor_deleteElement,{' '}
translationLanguage_delete und request_cancel. Die meisten Clients fragen die Person, bevor sie diese ausführen,
aber die Nachfrage ist die Entscheidung des Clients — prüfe also dessen Genehmigungseinstellungen, wenn du einen harten Stopp brauchst.
http(s)://- oder data:image-URIs. Ein Dokument pro Request ist die Ausnahme: document_create{' '}
liefert eine Upload-URL zurück, an die ein Client mit HTTP-Zugriff die Datei per PUT senden kann (siehe{' '}
Dokumente pro Request). Um ein PDF oder einen Screenshot in ein Formular zu verwandeln, nutze den{' '}
integrierten KI-Chat.
load_skill) sind über MCP verfügbar.
Die meisten Clients melden sich per OAuth an: Füge die URL ohne Header hinzu und folge{' '} Einen KI-Agenten verbinden. Ein Client, der keinen Browser öffnen kann — etwa ein Skript, ein CI-Job oder ein headless Agent — sendet stattdessen ein API-Token als Header.
Claude Code, über die Kommandozeile:
``` claude mcp add --transport http formstep https://api.formstep.io/api/mcp \ --header "Authorization: Bearer fb_YOUR_TOKEN" ```
Oder in der .mcp.json eines Projekts:
Cursor, in .cursor/mcp.json oder ~/.cursor/mcp.json:
Um dich statt mit einem Token per OAuth anzumelden, nutze{' '} Zu Cursor hinzufügen . Es fügt die Server-URL ohne Header hinzu, und Cursor fordert dich auf, dich bei Formstep anzumelden.
Andere Clients nehmen dieselbe URL und denselben Header; ihre eigene Dokumentation zeigt, wo.
Eine Drittanbieter-App, die im Auftrag einer Person eine Verbindung herstellt, sollte OAuth verwenden, statt nach einem eingefügten Token
zu fragen. Formstep ist ein OAuth-2.1-Autorisierungsserver mit verpflichtendem PKCE (S256) und undurchsichtigen Token — keine JWTs, kein
Implicit Grant. Claude Desktop, Claude Code und der Claude.ai-Web-Connector entdecken das alles selbst über den MCP-Endpunkt, sodass es
reicht, nur die URL ohne Header einzufügen: Der 401 verweist auf /.well-known/oauth-protected-resource, und der Client
übernimmt von dort.
Der Ablauf, für einen Client, den du selbst schreibst:
GET /.well-known/oauth-protected-resource, dann GET /.well-known/oauth-authorization-server für die
Endpunkt-URLs, Scopes und unterstützten Auth-Methoden.
POST /oauth/register mit deinen redirect_uris (dynamische Client-Registrierung, keine Zugangsdaten nötig). Du
bekommst eine client_id, plus ein client_secret, falls du etwas anderes als{' '}
token_endpoint_auth_method: "none" angefordert hast. Redirect-URIs müssen HTTPS sein, oder HTTP auf localhost.
Die Registrierung ist auf 20 pro Stunde pro IP begrenzt.
/oauth/authorize mit response_type=code, deiner client_id, der
registrierten redirect_uri, scope=mcp:read mcp:write offline_access, state und einem{' '}
code_challenge mit code_challenge_method=S256. Sie meldet sich an, wählt einen Arbeitsbereich und autorisiert.
POST /oauth/token mit grant_type=authorization_code und deinem code_verifier{' '}
ein, innerhalb von 60 Sekunden. Codes sind nur einmal verwendbar.
Authorization: Bearer fbo_... auf. Zugriffstoken sind 1 Stunde gültig; Refresh-Token sind 30 Tage
gültig und rotieren bei jeder Verwendung. Einen bereits verwendeten Refresh-Token erneut zu nutzen, verbrennt die gesamte Kette —
speichere also immer den neuesten.
POST /oauth/revoke (RFC 7009) widerruft ein Zugriffs- oder Refresh-Token. Eine Person kann außerdem die ganze App unter{' '}
Verbundene Apps auf der Seite OAuth und API-Schlüssel trennen, was jedes Token beendet, das sie für diesen Arbeitsbereich
hält.
Falls du bereits ein Token in der Hand hast, gehört es an denselben Platz wie ein API-Schlüssel:
``` { "mcpServers": { "formstep": { "type": "http", "url": "https://api.formstep.io/api/mcp", "headers": { "Authorization": "Bearer fbo_USER_OAUTH_TOKEN" } } } } ```Jede OAuth-Verbindung wird unter Verbundene Apps auf der Seite OAuth und API-Schlüssel aufgelistet, mit Angabe, wann sie verbunden und zuletzt verwendet wurde. Verbindungen sind persönlich: Nur die Person, die eine Verbindung autorisiert hat, sieht sie, und Workspace-Admins können die Verbindung eines anderen Mitglieds weder einsehen noch widerrufen. Das Trennen wirkt sofort. Eine Person, die den Arbeitsbereich verlässt oder daraus entfernt wird, verliert alle ihre Verbindungen zu ihm.