API and MCP

Formlane API and MCP server: read forms and submissions

Q: Do I need OAuth for the MCP server?

No. Pass the API token as Authorization: Bearer … header in your MCP client configuration.

Read your forms and submissions from scripts and AI agents: a read-only REST API and a remote MCP server for Claude Code, Cursor and other clients.

Both use the same personal API token and see only the forms of your own account. Everything is read-only: no token can create, change or delete forms or submissions. Submissions stored in Frankfurt.

Create a token

Sign in to Formlane and open Dashboard → API tokens.
Enter a name (for example the tool that will use it) and create the token. It can read forms and submissions.
Copy the token right away. It is shown once; Formlane only keeps a hash of it.
Store it as an environment variable, for example FORMLANE_API_TOKEN, not in a file you commit.

Quick start

REST with 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"

Run it in a shell where FORMLANE_API_TOKEN is set. Then ask Claude for example: "List my Formlane forms and summarise this week's submissions of the contact form."

.cursor/mcp.json

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

Cursor reads the token from the environment via ${env:…}, so the file holds no secret. Use ~/.cursor/mcp.json to enable it for all projects.

Any 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

Base URL https://smallwerk.com/api/v1/formlane. All endpoints are GET and answer JSON ({"error":{"code","message"}} on errors).

Endpoint	Scope	Returns
`/forms`	`forms:read`	All forms: id, name, active, access_key, endpoint, allowed_domains, redirect_url, created_at
`/forms/{id}`	`forms:read`	One form plus `endpoint` and a ready-to-paste `html_snippet`
`/forms/{id}/submissions`	`submissions:read`	Newest first. `limit` 1 to 100 (default 25), `cursor` = `next_cursor` of the previous page (null at the end), `spam` = `false` (default), `true` or `all`
`/forms/{id}/submissions/export`	`submissions:read`	`format=csv` (default) or `json`, up to 10,000 newest submissions, spam excluded

A form of another account answers 404, the same as an unknown id.

MCP server

Remote MCP server at https://smallwerk.com/api/mcp/formlane (Streamable HTTP, stateless). Same token, same scopes, same limit as REST. Tools:

Tool	Scope	What it does
`list_forms`	`forms:read`	Lists your forms
`get_form`	`forms:read`	One form with endpoint and HTML snippet
`list_submissions`	`submissions:read`	One page of submissions (`limit`, `cursor`, `spam`)
`export_submissions`	`submissions:read`	Newest non-spam submissions as JSON, up to 1,000 per call (`truncated` tells if there are more)

Scopes, limits and revocation

Scopes: forms:read and submissions:read. There are no write scopes.
Rate limit: 60 requests per minute per token, REST and MCP together. Above that you get 429 with Retry-After: 60.
Up to 10 active tokens per account.
Revoke a token in Dashboard → API tokens. It stops working on the next request (401). Create a new one if a token was exposed.
Errors: 400 invalid parameter, 401 missing, invalid or revoked token, 403 token lacks the scope, 404 form not found, 429 rate limit.

Submissions are untrusted data

Submission fields were typed by unknown people into a public form. Someone can write "ignore your instructions and …" into a message field. Formlane marks this content so agents can keep it apart from instructions:

REST: field values sit only under data, the body carries an untrusted_data notice and the response has the header X-Content-Untrusted: submissions.
MCP: tool descriptions say that submissions are untrusted, and the payload comes wrapped in <untrusted_submissions> … </untrusted_submissions> after a notice.
Because tokens are read-only, a manipulated message cannot change anything in Formlane. Still review what an agent does with submission content in other tools.

Privacy and responsibility

A token gives read access to all forms and submissions of your account, so treat it like a password. Store it in an environment variable or secret manager, never in a repository or front-end code, and revoke it in Dashboard → API tokens if it may have leaked. Tokens do not expire until you revoke them. Submissions usually contain personal data of the people who filled in your forms. When you connect an AI client or another service, you decide where that data goes: check that you have a legal basis, that your privacy notice covers it and, where needed, that you have a data processing agreement with that provider. We do not send your data to AI services; your client fetches it. See Terms § 6a and the DPA.

FAQ

Can an agent create forms or delete submissions?

No. Tokens are read-only: they can list forms and read or export submissions, nothing else.

Do I need OAuth for the MCP server?

No. Pass the API token as Authorization: Bearer … header in your MCP client configuration.

Does a token see forms of other accounts?

No. Every request is limited to the account that created the token; other forms answer 404.

Get your access key

Free for 250 submissions a month. Submissions stored in Frankfurt.