Brieform Logo
Brieform

MCP Server · Tools Reference

Brieform MCP Tools Reference

Parameters, return values, and example prompts for every tool in the Brieform MCP server.

Jump to

create_formupdate_formget_formlist_formspublish_formunpublish_formset_form_themeget_responsesduplicate_formdelete_formget_form_analyticsget_form_share_assets
create_form

Create form

Create a new draft form. Pass a full structured form definition for precise control, or pass a natural language prompt and Brieform generates the structure for you. The form starts as a draft and is not publicly accessible until you call publish_form.

Parameters

formobject

Full form definition: title, description, fields (with types, labels, options, conditional logic), theme, steps, successMessage, redirectUrl. Preferred — gives you precise control with no AI cost.

promptstring

Natural language description of the form. Used only when form is not provided. Brieform's AI generates the structure.

Returns

form_id, title, status ("draft"), field_count, preview_url (signed, 24h), summary.

Notes

At least one of form or prompt is required. Field types: text, email, tel, textarea, select, radio, checkbox, rating, date, number, url, password, gdpr.

Example prompts

›“Create a contact form with name, email, and message”
›“Build a 5-question customer feedback survey”
›“Make a job application form with resume upload and cover letter fields”
update_form

Update form

Modify an existing form. Structured mode (preferred): fetch the form with get_form, apply your changes, and send the full updated structure — this gives precise, reliable results. Prompt mode (fallback): describe the change in natural language; Brieform's AI applies it using the current form as context.

Parameters

form_idstringrequired

ID of the form to update.

formobject

Full updated form structure. PUT semantics: replaces all fields, theme, and settings. Include each field's id from get_form to preserve response history.

promptstring

Natural language description of the change (e.g. "add a budget dropdown"). Used only when form is not provided.

Returns

form_id, title, status, field_count, preview_url, summary. summary includes a warning if the form was live when updated.

Notes

If the form is currently published, changes go live immediately. The returned summary includes a warning. Use structured mode for precise edits — prompt mode may inadvertently change unrelated fields.

Example prompts

›“Add a phone number field to my contact form”
›“Make the message field optional in my feedback form”
›“Rename my form to "Q2 Customer Survey"”
get_form

Get form

Fetch the complete structure and metadata of a form. Use this before updating a form in structured mode so you have the current field IDs and configuration.

Parameters

form_idstringrequired

ID of the form to fetch.

Returns

Full form definition including form_id, title, description, fields (with ids), theme, steps, status, public_url (if published), preview_url, response_count.

Example prompts

›“Show me what fields are in my contact form”
›“What's the current structure of my pricing inquiry form?”
list_forms

List forms

List all forms belonging to the authenticated user. Filter by status, search by title, and paginate through large collections.

Parameters

status"draft" | "published"

Filter by form status. Omit to return all.

searchstring

Case-insensitive title search.

limitnumber

Results per page. Default 20, max 100.

cursorstring

Pagination cursor from the previous response's next_cursor.

Returns

forms[] (each with form_id, title, status, field_count, response_count, public_url if published), next_cursor, total.

Example prompts

›“Show me all my published forms”
›“List my draft forms”
›“Do I have a form called "Event RSVP"?”
publish_form

Publish form

Make a form publicly accessible. A URL-friendly slug is auto-generated from the form title if you don't provide one. Idempotent — calling it on an already-published form returns the existing URL.

Parameters

form_idstringrequired

ID of the form to publish.

slugstring

Custom URL slug (e.g. "my-contact-form" → brieform.app/f/my-contact-form). Auto-generated if omitted.

regenerate_slugboolean

Force a new slug even if the form is already published.

Returns

form_id, status ("published"), slug, public_url, share_url.

Example prompts

›“Publish my contact form”
›“Publish my survey and give me the link to share”
›“Publish my form at the slug "q2-feedback"”
unpublish_form

Unpublish form

Take a form offline. The form returns to draft status and is no longer accessible at its public URL. All responses are preserved.

Parameters

form_idstringrequired

ID of the form to unpublish.

Returns

form_id, status ("draft").

Example prompts

›“Take my feedback form offline”
›“Unpublish my pricing inquiry form — I need to update it”
set_form_theme

Set form theme

Change the visual theme of a form. Three modes: apply a named preset (fastest, no AI cost), pass a full custom theme object, or describe the look you want in natural language.

Parameters

form_idstringrequired

ID of the form to retheme.

preset_idstring

Named preset: modern-blue, slate-professional, vibrant-green, elegant-violet, warm-rose, sunset-orange, corporate-neutral, minimal-stone.

themeobject

Full custom theme object with primaryColor, backgroundColor, textColor, fontFamily, borderRadius.

promptstring

Natural language theme description (e.g. "dark background, orange accent"). Brieform's AI generates the theme.

Returns

form_id, title, theme_summary, preview_url.

Notes

Pass exactly one of preset_id, theme, or prompt.

Example prompts

›“Apply the dark slate theme to my contact form”
›“Give my survey a warm rose theme”
›“Make my form look minimal and professional — light grey background”
get_responses

Get responses

Fetch submissions for a form. For large datasets or when exporting to another tool (Notion, Google Sheets, etc.), use format: "csv_url" to get a signed download link instead of inline JSON — this avoids filling your context window.

Parameters

form_idstringrequired

ID of the form.

limitnumber

Responses per page. Default 50, max 200.

cursorstring

ISO timestamp cursor from previous response's next_cursor for pagination.

sincestring (ISO datetime)

Return only responses submitted at or after this time.

format"json" | "csv_url"

json: inline data. csv_url: returns a signed URL (1h TTL) to a CSV file. Recommended for 50+ responses.

Returns

responses[] (each with response_id, submitted_at, fields keyed by label), next_cursor, total, csv_url (if csv_url format).

Example prompts

›“Show me the latest responses to my contact form”
›“How many people filled out my survey this week?”
›“Give me a CSV of all my job application form responses”
›“Summarize the feedback from my product survey”
duplicate_form

Duplicate form

Create a copy of an existing form. The duplicate is created as a draft with all fields, theme, and settings copied. It does not copy existing responses.

Parameters

form_idstringrequired

ID of the form to duplicate.

new_titlestring

Title for the new form. Defaults to "Copy of [original title]".

Returns

Same shape as create_form: form_id, title, status ("draft"), field_count, preview_url, summary.

Example prompts

›“Duplicate my contact form and call the copy "Lead Capture"”
›“Make a copy of my Q1 survey for Q2”
delete_form

Delete form

Permanently delete a form and all its responses. This is irreversible. Requires confirm: true as a safety gate.

Parameters

form_idstringrequired

ID of the form to delete.

confirmtruerequired

Must be exactly true. Safety gate — deletion is permanent.

Returns

deleted (true), form_id.

Notes

All responses are deleted with the form. Export responses with get_responses before deleting if you want to keep them.

Example prompts

›“Delete my old contact form — I don't need it anymore”
›“Remove the test form I created yesterday”
get_form_analytics

Get form analytics

Return view, submission, and conversion metrics for a form over the chosen period. Includes a daily breakdown, top traffic sources, and a step-by-step funnel for multi-step forms. Use when the user asks how their form is performing.

Parameters

form_idstringrequired

ID of the form to fetch analytics for.

period"7d" | "30d" | "90d"

Time window. Defaults to "30d".

Returns

form_id, period, total_views, total_submissions, conversion_rate (0..1), daily[] (date/views/submissions), top_referrers[] (source/count, up to 10), funnel[] (step_id/step_title/step_order/viewed/completed/drop_off_pct) or null for single-step forms.

Notes

Requires Starter plan or higher. Free-plan users get a QUOTA_EXCEEDED error.

Example prompts

›“How is my contact form doing this month?”
›“Where is the traffic to my survey coming from?”
›“Show me where people are dropping off in my application form”
get_form_share_assets

Get form share assets

Return everything needed to share a form in one call: public URL, signed preview URL, iframe embed snippet, social preview image, and a scannable QR code (PNG data URI). Drafts return nulls for the public-only assets — the preview URL still works for the owner.

Parameters

form_idstringrequired

ID of the form to fetch share assets for.

qr_sizenumber

QR code dimensions in pixels (square). Default 256, range 128..1024.

Returns

form_id, title, status, public_url (null if draft), preview_url, embed_iframe, og_image_url (null if draft), qr_png_data_uri (null if draft).

Notes

QR codes are only generated for published forms (drafts have no public URL to encode).

Example prompts

›“How do I share my contact form?”
›“Give me a QR code for my event RSVP form”
›“Get the embed snippet for my pricing inquiry form”

Start using the MCP server

Free account. 60 seconds to connect. Works with Claude, ChatGPT, and more.

Install in AI →Create free account

No credit card · Works with Claude, ChatGPT, Cursor

← Back to MCP docs