> ## Documentation Index
> Fetch the complete documentation index at: https://formpaste.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# create_form

> MCP tool - create a Formpaste form and get back its access key + a wired snippet.

<Info>**Free** - like the rest of the MCP server, `create_form` is not plan-gated.</Info>

Creates a new form on your account and returns everything needed to wire it up: the
form's id, its `access_key`, and a ready-to-paste snippet for the framework you asked
for. This is the MCP equivalent of clicking **New form** in the dashboard - there is no
separate REST endpoint for this.

## Input schema

| Field              | Type                                                            | Required | Notes                                                           |
| ------------------ | --------------------------------------------------------------- | -------- | --------------------------------------------------------------- |
| `name`             | `string`                                                        | yes      | For your own reference in the dashboard; visitors never see it. |
| `destinationEmail` | `string` (email)                                                | yes      | Where submissions get sent.                                     |
| `framework`        | `"html" \| "react" \| "nextjs" \| "astro" \| "vue" \| "svelte"` | no       | Defaults to `html` if omitted.                                  |

## Example call

```json theme={null}
{
  "name": "create_form",
  "arguments": {
    "name": "Contact form",
    "destinationEmail": "you@example.com",
    "framework": "react"
  }
}
```

## Returned shape

```json theme={null}
{
  "form_id": "frm_...",
  "access_key": "fp_...",
  "snippet": "import { useState } from \"react\";\n\nexport function ContactForm() { ... }",
  "verification_required": false,
  "note": "Delivering to you@example.com - already verified on your account. Submissions will be emailed as they arrive."
}
```

| Field                   | Type      | Meaning                                                                                                                                           |
| ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `form_id`               | `string`  | The new form's id (`frm_…`). Pass this to [`get_snippet`](/docs/agents/get-snippet) or [`list_submissions`](/docs/agents/list-submissions) later.           |
| `access_key`            | `string`  | The form's `access_key` (`fp_…`), already embedded in `snippet`.                                                                                  |
| `snippet`               | `string`  | A bare, wired form for the requested `framework` - the same output as [`get_snippet`](/docs/agents/get-snippet), pre-filled with this form's real key. |
| `verification_required` | `boolean` | See below.                                                                                                                                        |
| `note`                  | `string`  | Human-readable status the agent can relay verbatim to the developer.                                                                              |

## Destination verification: two outcomes

Every form needs a **verified** destination email before submissions get delivered by
email - this stops a form being pointed at an inbox its owner doesn't control. What
`create_form` does about that depends on whether `destinationEmail` is already proven
on your account:

**Already verified** (either it matches a destination you've verified before, or it's
your own account's verified sign-in email) - the form is ready immediately:

```json theme={null}
{ "verification_required": false, "note": "Delivering to you@example.com - already verified on your account. Submissions will be emailed as they arrive." }
```

**A new address** - Formpaste emails a 6-digit code to `destinationEmail` and stores
submissions right away, but holds email delivery until the code is entered:

```json theme={null}
{ "verification_required": true, "note": "A verification code was sent to new@example.com. Submissions are stored immediately, but won't be emailed until the account owner enters that code in the dashboard (form Setup → verify destination)." }
```

<Note>
  The agent can't finish this step itself - it can't read the destination inbox to see
  the code. `verification_required: true` means an agent should tell the developer to
  check that inbox and enter the code on the form's Setup tab in the dashboard. This is
  by design, not a gap: it's the same anti-bombing check the dashboard enforces on every
  new destination, described in [Your first form](/docs/first-form).
</Note>

## Errors

An invalid or revoked token returns an MCP tool error (not a form-specific one):

```
unauthorized: invalid or revoked API token - generate one in Settings → API tokens.
```

See [MCP server](/docs/agents/mcp-server#auth) for the auth model this comes from.

<CardGroup cols={2}>
  <Card title="get_snippet" icon="code" href="/docs/agents/get-snippet">
    Fetch a snippet on its own, for an existing form or as a placeholder.
  </Card>

  <Card title="Cookbook prompts" icon="book" href="/docs/agents/cookbook-prompts">
    Prompts that drive create\_form end to end.
  </Card>
</CardGroup>