Headless tools

Use these MCP tools to create and configure Headless endpoints, inspect their settings, and manage a backend key.

Beta

This feature is available to all accounts. Its request and response format can change without a new API version. Do not depend on it for anything you cannot update quickly.

Each invocation attempts to append a private execution audit record, including data reads and proposals; retries may add another record.

`create_headless_form`

Creates a Headless form and its endpoint. It does not create a hosted form page. A new Headless form starts in loose schema mode with honeypot protection on. It is enabled only if you provide at least one allowed origin and the owner is within the Free plan's endpoint limit. If you omit domains, the endpoint is server-only and disabled.

Input

Name	Type	Required	Description
`name`	string	Yes	Form name.
`domains`	string or string[]	No	Sites allowed to submit. Omit for a server-only endpoint.
`schema_mode`	`strict` or `loose`	No	Schema validation mode.
`auto_reply`	boolean	No	Whether respondent confirmation emails are enabled.
`owner_notification`	boolean	No	Whether owner notifications are enabled.

Returns

Returns form with its id, name, and url (null); limited; upgrade_required and notice when present; endpoint details; submit_url; an embed object with script_url and snippet; owner_notification.enabled; and message. The endpoint.endpoint_id identifies the submission endpoint; use it in the submit URL. When owner_notification is omitted, its result is {"enabled":true}.

An endpoint added to an existing Page form starts disabled, in strict mode, with honeypot protection on and no allowed origins.

Example arguments

{
  "name": "Contact form",
  "domains": ["https://example.com"],
  "schema_mode": "loose",
  "auto_reply": true,
  "owner_notification": true
}

`get_headless_endpoint`

Returns the endpoint settings for a form. You need edit access to the form. The tool does not change your data. Secrets and full backend keys are not returned.

Input

Name	Type	Required	Description
`form_id`	string	Yes	Form to inspect.

Returns

Returns endpoint or null, and may include submit_url, fallback_submit_url, embed, and auto_reply with enabled and email_field. The response also includes message. Use endpoint.endpoint_id, rather than the form ID, in Headless submit URLs. Using a form ID returns 404.

Endpoint details include:

Group	Properties
Identity and state	`endpoint_id`, `form_id`, `enabled`, `allowed_origins`, `schema_mode`, `spam_mode`
Key metadata	`api_key_configured`, `api_key_hint`, `api_key_created_at`, `api_key_last_used_at`
Turnstile	`turnstile_enabled`, `turnstile_site_key`, `turnstile_secret_configured`
Timestamps	`created_at`, `updated_at`, `last_used_at`

Example arguments

{
  "form_id": "FORM_ID"
}

`update_headless_endpoint`

Creates an endpoint if the form does not have one, then updates its settings. Turnstile is configured in the dashboard.

Input

Name	Type	Required	Description
`form_id`	string	Yes	Form to configure.
`enabled`	boolean	No	Whether the endpoint is enabled. An endpoint needs an allowed origin or backend key to be enabled.
`allowed_origins`	string[]	No	Complete allowed-origin list. An empty list means key-only access.
`schema_mode`	`strict` or `loose`	No	Schema validation mode. Page forms must use strict mode.
`expected_schema_version`	datetime	No	Schema version used when changing mode through MCP.
`acknowledge_schema_limits`	boolean	No	Acknowledges schema limits when changing mode through MCP.
`spam_mode`	`none` or `honeypot`	No	Spam protection mode.
`auto_reply`	`{ enabled, email_field? }`	No	Configures a respondent confirmation email. Available on paid plans. The default payload key for the respondent's address is `email`.
`verified_email_fields`	string[]	No	Up to five fields. Send this setting alone in its call; Business plan only.

Strict mode rejects unknown keys and enforces configured types and options. Loose mode accepts unknown keys and learns them into the form schema. A string is learned as a short text field; an array is learned as a checkbox field with options.

While any field requires email verification, submissions using a backend key fail with 403 and code email_verification.

Returns

Returns endpoint, submit_url, fallback_submit_url, and message. It may also include auto_reply and verified_email_fields.

Example arguments

{
  "form_id": "FORM_ID",
  "enabled": true,
  "allowed_origins": ["https://example.com"],
  "spam_mode": "honeypot"
}

Free plan limits

The Free plan allows one enabled endpoint and 50 Headless submissions per month. Enabling a second endpoint returns 403. Pro and Business plans allow unlimited enabled endpoints and Headless submissions per month.

`create_headless_api_key`

Creates or replaces an endpoint's backend key in two steps. The endpoint must already exist. The key is shown once, and replacing it invalidates the previous key immediately. A Headless key belongs to one endpoint; it is not a management credential and differs from an mf_live_ API key.

Input

Name	Type	Required	Description
`form_id`	string	Yes	Form whose endpoint needs a key.
`confirm_create`	boolean	No	Confirms key creation or replacement.
`key_token`	string	When confirming	Token returned by the first step.

Returns

The first step returns status: "confirmation_required", the endpoint ID, any key hint being replaced, a key_token, its expiry time, and a message. The token lasts 10 minutes. The confirming step returns status: "created", the full api_key, its hint, whether the endpoint is enabled, and a message.

Confirmation tokens are single-purpose and bound to the action, form, user, calling credential, and proposed configuration or state. An expired token returns “Action token expired. Run preview again.” A token that does not match the request returns “Action token does not match this request.”

Example arguments

First, request confirmation:

{
  "form_id": "FORM_ID"
}

Then confirm with the returned token:

{
  "form_id": "FORM_ID",
  "confirm_create": true,
  "key_token": "mf_mcp_act_YOUR_TOKEN"
}

Submitting to a Headless endpoint

Use the endpoint ID from endpoint.endpoint_id in the submit URL: https://submit.makeform.ai/f/ENDPOINT_ID. Using a form ID in this URL returns 404.

For a backend submission, omit the Origin header and send the endpoint's backend key in either of these headers:

Authorization: Bearer mfh_live_YOUR_KEY

X-Makeform-Headless-Key: mfh_live_YOUR_KEY

If an Origin header is present, the request is treated as a browser request and the backend key is ignored. The origin must be one of the endpoint's allowed domains.

Respondent auto-reply

Auto-reply requires a paid plan. On the Free plan its result reports {"enabled":false,"limited":true}.

Tool errors

Tool errors return HTTP 200 with result.isError: true. The text body contains a JSON-RPC error. Input schema failures start with MCP error -32602: Input validation error. The JSON-RPC error includes a code, message, and data object with a name.