API and MCP

Formlane-API und MCP-Server: Formulare und Einsendungen lesen

Q: Brauche ich OAuth für den MCP-Server?

Nein. Gib den API-Token als Header Authorization: Bearer … in der Konfiguration deines MCP-Clients an.

Lies deine Formulare und Einsendungen aus Skripten und KI-Agenten: eine Lese-REST-API und ein Remote-MCP-Server für Claude Code, Cursor und andere Clients.

Beide nutzen denselben persönlichen API-Token und sehen nur die Formulare deines eigenen Kontos. Alles ist nur lesend: Kein Token kann Formulare oder Einsendungen anlegen, ändern oder löschen. Einsendungen werden in Frankfurt gespeichert.

Token anlegen

Melde dich bei Formlane an und öffne Dashboard → API-Tokens.
Gib einen Namen ein (zum Beispiel das Tool, das ihn nutzt) und erstelle den Token. Er kann Formulare und Einsendungen lesen.
Kopiere den Token sofort. Er wird nur einmal angezeigt; Formlane speichert nur einen Hash.
Lege ihn als Umgebungsvariable ab, zum Beispiel FORMLANE_API_TOKEN, nicht in einer Datei, die du committest.

Schnellstart

REST mit curl

export FORMLANE_API_TOKEN=fl_xxxxxxxx_…   # shown once when you create it

# All forms of your account
curl -H "Authorization: Bearer $FORMLANE_API_TOKEN" https://smallwerk.com/api/v1/formlane/forms

# Newest 25 submissions of one form (next page: ?cursor=<next_cursor>)
curl -H "Authorization: Bearer $FORMLANE_API_TOKEN" "https://smallwerk.com/api/v1/formlane/forms/FORM_ID/submissions?limit=25"

# Export as CSV (or ?format=json)
curl -H "Authorization: Bearer $FORMLANE_API_TOKEN" -o submissions.csv "https://smallwerk.com/api/v1/formlane/forms/FORM_ID/submissions/export?format=csv"

Claude Code

claude mcp add --transport http formlane https://smallwerk.com/api/mcp/formlane \
  --header "Authorization: Bearer $FORMLANE_API_TOKEN"

Führe den Befehl in einer Shell aus, in der FORMLANE_API_TOKEN gesetzt ist. Frag Claude dann zum Beispiel: „Liste meine Formlane-Formulare und fasse die Einsendungen dieser Woche zusammen.“

.cursor/mcp.json

{
  "mcpServers": {
    "formlane": {
      "url": "https://smallwerk.com/api/mcp/formlane",
      "headers": { "Authorization": "Bearer ${env:FORMLANE_API_TOKEN}" }
    }
  }
}

Cursor liest den Token per ${env:…} aus der Umgebung, die Datei enthält also kein Geheimnis. Mit ~/.cursor/mcp.json gilt er für alle Projekte.

Jeder MCP-Client

Transport:  Streamable HTTP (stateless, POST only)
URL:        https://smallwerk.com/api/mcp/formlane
Header:     Authorization: Bearer <your Formlane API token>
Tools:      list_forms, get_form, list_submissions, export_submissions

# Client without HTTP transport (stdio only)? Use a bridge such as mcp-remote:
npx mcp-remote https://smallwerk.com/api/mcp/formlane --header "Authorization: Bearer ${FORMLANE_API_TOKEN}"

REST-Endpoints

Basis-URL https://smallwerk.com/api/v1/formlane. Alle Endpoints sind GET und antworten mit JSON (bei Fehlern {"error":{"code","message"}}).

Endpoint	Scope	Liefert
`/forms`	`forms:read`	Alle Formulare: id, name, active, access_key, endpoint, allowed_domains, redirect_url, created_at
`/forms/{id}`	`forms:read`	Ein Formular plus `endpoint` und ein fertiges `html_snippet`
`/forms/{id}/submissions`	`submissions:read`	Neueste zuerst. `limit` 1 bis 100 (Standard 25), `cursor` = `next_cursor` der vorigen Seite (am Ende null), `spam` = `false` (Standard), `true` oder `all`
`/forms/{id}/submissions/export`	`submissions:read`	`format=csv` (Standard) oder `json`, bis zu 10.000 neueste Einsendungen, ohne Spam

Ein Formular eines anderen Kontos antwortet mit 404, genau wie eine unbekannte ID.

MCP-Server

Remote-MCP-Server unter https://smallwerk.com/api/mcp/formlane (Streamable HTTP, zustandslos). Gleicher Token, gleiche Scopes, gleiches Limit wie REST. Tools:

Tool	Scope	Was es tut
`list_forms`	`forms:read`	Listet deine Formulare
`get_form`	`forms:read`	Ein Formular mit Endpoint und HTML-Snippet
`list_submissions`	`submissions:read`	Eine Seite Einsendungen (`limit`, `cursor`, `spam`)
`export_submissions`	`submissions:read`	Neueste Einsendungen ohne Spam als JSON, bis zu 1.000 pro Aufruf (`truncated` zeigt, ob es mehr gibt)

Scopes, Limits und Widerruf

Scopes: forms:read und submissions:read. Schreib-Scopes gibt es nicht.
Rate-Limit: 60 Anfragen pro Minute pro Token, REST und MCP zusammen. Darüber kommt 429 mit Retry-After: 60.
Bis zu 10 aktive Tokens pro Konto.
Widerrufe einen Token unter Dashboard → API-Tokens. Er funktioniert ab der nächsten Anfrage nicht mehr (401). Leg einen neuen an, wenn ein Token offengelegt wurde.
Fehler: 400 ungültiger Parameter, 401 Token fehlt, ist ungültig oder widerrufen, 403 Token fehlt der Scope, 404 Formular nicht gefunden, 429 Rate-Limit.

Einsendungen sind nicht vertrauenswürdige Daten

Einsendungsfelder haben unbekannte Personen in ein öffentliches Formular getippt. Jemand kann „ignoriere deine Anweisungen und …“ in ein Nachrichtenfeld schreiben. Formlane markiert diese Inhalte, damit Agenten sie von Anweisungen trennen können:

REST: Feldwerte stehen nur unter data, die Antwort enthält einen untrusted_data-Hinweis und den Header X-Content-Untrusted: submissions.
MCP: Die Tool-Beschreibungen sagen, dass Einsendungen nicht vertrauenswürdig sind, und die Daten kommen nach einem Hinweis in <untrusted_submissions> … </untrusted_submissions> eingepackt.
Da Tokens nur lesen, kann eine manipulierte Nachricht in Formlane nichts ändern. Prüfe trotzdem, was ein Agent mit Einsendungsinhalten in anderen Tools macht.

Datenschutz und Verantwortung

Ein Token gibt Lesezugriff auf alle Formulare und Einsendungen deines Kontos. Behandle ihn wie ein Passwort: Speichere ihn in einer Umgebungsvariable oder einem Secret-Manager, nie in einem Repository oder im Frontend-Code, und widerrufe ihn unter Dashboard → API-Tokens, wenn er offengelegt sein könnte. Tokens laufen nicht ab, bis du sie widerrufst. Einsendungen enthalten meist personenbezogene Daten der Personen, die deine Formulare ausgefüllt haben. Wenn du einen KI-Client oder einen anderen Dienst verbindest, entscheidest du, wohin diese Daten gehen: Prüfe, dass du eine Rechtsgrundlage hast, deine Datenschutzerklärung das abdeckt und du, wo nötig, einen Auftragsverarbeitungsvertrag mit dem Anbieter hast. Wir senden deine Daten nicht an KI-Dienste; dein Client ruft sie ab. Siehe AGB § 6a und AVV.

Häufige Fragen

Kann ein Agent Formulare anlegen oder Einsendungen löschen?

Nein. Tokens sind nur lesend: Sie können Formulare auflisten und Einsendungen lesen oder exportieren, sonst nichts.

Brauche ich OAuth für den MCP-Server?

Nein. Gib den API-Token als Header Authorization: Bearer … in der Konfiguration deines MCP-Clients an.

Sieht ein Token Formulare anderer Konten?

Nein. Jede Anfrage ist auf das Konto beschränkt, das den Token angelegt hat; andere Formulare antworten mit 404.

Access Key holen

Kostenlos für 250 Einsendungen pro Monat. Einsendungen werden in Frankfurt gespeichert.