MCP form and workspace read tools

Use these tools to inspect your Makeform workspace and forms, or to generate an embed package for a published hosted form. Send the JSON arguments shown for each tool.

Successful tool results include content[0].text and structuredContent. The structured content matches the tool’s declared output schema. Each invocation attempts to append a private execution audit record, including data reads; retries may add another record. These tools do not change your data.

Tool errors return HTTP 200 with result.isError: true. The text body contains JSON like this:

{
  "jsonrpc_error": {
    "code": -32600,
    "message": "Request could not be completed",
    "data": {
      "name": "ERROR_NAME"
    }
  }
}

Input schema failures have text beginning with MCP error -32602: Input validation error.

get_workflow_guide

Returns the live Markdown workflow guide, including steps, tool list, safety rules, common field types, and design and settings notes.

Input

Name	Type	Required	Description
—	—	—	No arguments.

Returns

An object with a guide string.

Example call

{}

get_workspace

Returns the credential’s context: plan, role, form and member counts, and the custom workspaces it can access.

Input

Name	Type	Required	Description
—	—	—	No arguments.

Returns

An object with workspace_id, plan_tier, user_role, form_count, member_count, and workspaces. Each workspace has an id, name, and team_id.

Example call

{}

list_forms

Lists accessible forms, with the most recently updated first.

Input

Name	Type	Required	Description
`status`	`all`, `draft`, or `published`	No	Filter forms by status. Defaults to `all`.
`limit`	Integer from 1 to 100	No	Number of forms to return. Defaults to `20`.
`offset`	Integer ≥ 0	No	Number of forms to skip.

Returns

An object with forms, an array of form objects. Each form includes id, name, status, created_at, updated_at, and submission_count.

Example call

{
  "status": "published",
  "limit": 20,
  "offset": 0
}

get_form

Returns a form’s draft and published config, plus its settings.

Input

Name	Type	Required	Description
`form_id`	String	Yes	Form to retrieve.
`include_image_assets`	Object	No	Request image assets with `target` set to `open_graph_image`, `favicon`, `logo`, `cover_image`, or `qr_logo`. Requires edit access. You can also set `limit` from 1 to 20 and `offset` to 0 or greater.

Returns

An object with id, name, status, preview_config, live_config, settings, draft_hash, live_hash, created_at, updated_at, published_at, submission_count, field_count, url, and edit_url. The respondent url is null for drafts. The edit_url points to the builder, or to the Headless page for Headless forms. Callers who can manage integrations may also receive email_notifications; it never contains email addresses.

When requested, image_assets includes target, current_binding (state, asset_id, and binding_url), candidates, and pagination (offset, limit, and next_offset).

Example call

{
  "form_id": "FORM_ID",
  "include_image_assets": {
    "target": "logo",
    "limit": 10,
    "offset": 0
  }
}

get_form_config_schema

Returns the JSON Schema for the form config, using the same contract that validates drafts. See form config and field types.

Input

Name	Type	Required	Description
—	—	—	No arguments.

Returns

A JSON Schema object with $schema, type, properties, required, additionalProperties, and definitions.

Example call

{}

get_form_embed

Builds a paste-ready embed package for a published hosted form. The package can include a Standard, Popup, Slider, or Fullpage snippet. See Makeform embeds for embed options and setup.

Input

Name	Type	Required	Description
`form_id`	String	Yes	Published hosted form to embed.
`embed_type`	String	No	`standard`, `popup`, `slider`, or `fullpage`.
`snippet_mode`	String	No	`default` or `csp_external`.
`options`	Object	No	Options for the selected embed type.
`hidden_fields`	Object	No	Static values for hidden fields already declared in the form’s settings. Values can be strings, finite numbers, or booleans. Declare hidden fields with `update_form_settings`.

Returns

A package with form_id, form_name, status, embed_type, embed_url, html_snippet, sdk, normalized_options, effective_behavior, requirements, and warnings. Depending on the request, it may also include snippet_mode, csp, and normalized_hidden_fields. In CSP mode, csp lists the source values the host page must allow.

The form must be published. Drafts return publish_required. If hidden_fields contains a field that is not declared in the form’s settings, the tool returns an error named invalid_hidden_fields.

Example call

{
  "form_id": "FORM_ID",
  "embed_type": "standard",
  "snippet_mode": "default",
  "options": {},
  "hidden_fields": {
    "utm_source": "pricing"
  }
}

get_form_stats

Returns submission totals and completion statistics for a form.

Input

Name	Type	Required	Description
`form_id`	String	Yes	Form to retrieve stats for.

Returns

An object with form_id, total_submissions, submissions_today, submissions_by_ref, submissions_last_7_days, submissions_last_28_days, submissions_this_month, completed_submissions, partial_submissions, and completion_rate.

Example call

{
  "form_id": "FORM_ID"
}