MCP-Server

Was es ist

MCP ist ein offener Standard, über den KI-Tools eine Verbindung zu externen Diensten herstellen. formbase stellt einen gehosteten MCP-Endpunkt bereit, mit dem sich jeder MCP-kompatible Client verbinden kann – darunter Claude Code, Claude Desktop und Cursor.

Verbindung

URL:  https://api.formbase.so/api/mcp   (POST, streamable HTTP)
Auth: Bearer <token>

Zwei Arten von Bearer-Token funktionieren:

• API-Token (fb_…) — erstellt über API-Tokens. Ideal für den persönlichen Gebrauch und eine schnelle Einrichtung.

• OAuth-Zugriffstoken (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.

Kern-Tools

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.

Tool-Kataloge

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 (Domänenwissen)

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.

Requests

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.

Einen Request erstellen

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.

{
  "formId": "j57...",
  "recipient": { "email": "ada@acme.com", "name": "Ada" },
  "prefill": { "company_name": "Acme", "plan": "pro" },
  "readonly": ["company_name"],
  "context": { "crm_id": "A-42" },
  "metadata": { "run_id": "exec_918" },
  "delivery": "email",
  "expiresAt": 1780000000000,
  "callbackUrl": "https://hooks.acme.com/formbase",
  "idempotencyKey": "po-42"
}

Das Ergebnis liefert den Link und die Uhr:

{
  "id": "kd7...",
  "status": "pending",
  "url": "https://form.formbase.so/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.

Callbacks oder Polling

Mit einer callbackUrl sendet formbase 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.

Testmodus

Ü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.

Dokumente pro Request

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:

1. Rufe 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.

2. PUTe die rohen Bytes innerhalb einer Stunde an uploadUrl, mit Content-Type auf den deklarierten Typ gesetzt.

3. Referenziere sie von 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.

Benutzerdefinierte Domains

Ü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.

Ergebnisse lesen

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.

Ressourcen und Prompts

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.

Tools, die erst nachfragen

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.

Einschränkungen

• Keine Binär-Uploads über einen Tool-Aufruf. Bilder werden per URL gesetzt: Cover, Logos und Bild-Blöcke akzeptieren 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.

• Keine Workspace-KI-Skills. In formbase geschriebene Skills sind nur im integrierten KI-Chat verfügbar. Die eigenen Skills des Servers (load_skill) sind über MCP verfügbar.

Mit einem API-Token verbinden

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 formbase https://api.formbase.so/api/mcp \
  --header "Authorization: Bearer fb_YOUR_TOKEN"

Oder in der .mcp.json eines Projekts:

{
  "mcpServers": {
    "formbase": {
      "type": "http",
      "url": "https://api.formbase.so/api/mcp",
      "headers": {
        "Authorization": "Bearer fb_YOUR_TOKEN"
      }
    }
  }
}

Cursor, in .cursor/mcp.json oder ~/.cursor/mcp.json:

{
  "mcpServers": {
    "formbase": {
      "url": "https://api.formbase.so/api/mcp",
      "headers": {
        "Authorization": "Bearer fb_YOUR_TOKEN"
      }
    }
  }
}

Um dich statt mit einem Token per OAuth anzumelden, nutze

. Es fügt die Server-URL ohne Header hinzu, und Cursor fordert dich auf, dich bei formbase anzumelden.

Andere Clients nehmen dieselbe URL und denselben Header; ihre eigene Dokumentation zeigt, wo.

OAuth statt API-Tokens verwenden

Eine Drittanbieter-App, die im Auftrag einer Person eine Verbindung herstellt, sollte OAuth verwenden, statt nach einem eingefügten Token zu fragen. formbase 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:

1. GET /.well-known/oauth-protected-resource, dann GET /.well-known/oauth-authorization-server für die Endpunkt-URLs, Scopes und unterstützten Auth-Methoden.

2. 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.

3. Schicke die Person zu /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.

4. Tausche den Code bei POST /oauth/token mit grant_type=authorization_code und deinem code_verifier ein, innerhalb von 60 Sekunden. Codes sind nur einmal verwendbar.

5. Rufe den MCP-Endpunkt mit 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": {
    "formbase": {
      "type": "http",
      "url": "https://api.formbase.so/api/mcp",
      "headers": {
        "Authorization": "Bearer fbo_USER_OAUTH_TOKEN"
      }
    }
  }
}

Verbundene Apps

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.

Nächste Schritte