> ## 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.

# MCP server

> Let an agent create forms, fetch snippets, and read submissions directly - no dashboard visit.

<Info>**Free** - the MCP server is not plan-gated. Any account can use it.</Info>

Formpaste ships a remote **MCP server** - this is the [real AI agent-native](https://formpaste.com/features/ai/) integration
path. There is no separate REST "Forms API" or "Provisioning API"; an agent that wants
to create or manage forms programmatically does it through these MCP tools, the same
way a human does it through the dashboard.

## Endpoint

```
POST https://api.formpaste.com/mcp
```

Stateless remote MCP over Streamable HTTP - no session/SSE handshake to manage. Each
request carries its own auth and gets a self-contained response.

## Auth

Every request needs an **account API token** (`fpat_…`) as a standard Bearer header:

```
Authorization: Bearer fpat_YOUR_TOKEN
```

This is the *only* Bearer token in Formpaste. It is unrelated to a form's
`access_key` (used by [`POST /submit`](/docs/quickstart), not by `/mcp`) - see
[Access key vs. API token](/docs/agents/api-tokens#access-key-vs-api-token) if you're unsure
which one you need.

Mint a token from the dashboard under **Settings → API & MCP** - see
[API tokens](/docs/agents/api-tokens) for details, including the fact that it's shown
exactly once.

Tokens can be **scoped**: a full token can use every tool, a setup token can do
everything except read submissions (`list_submissions`). See
[API tokens](/docs/agents/api-tokens).

A missing or revoked token doesn't get a generic 401; the tool call returns an
actionable MCP error:

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

## Install (one command)

Formpaste is a remote server, so most MCP clients (Claude Code, Cursor, Claude
Desktop) connect to it via [`mcp-remote`](https://www.npmjs.com/package/mcp-remote)
rather than a local process. Add this to your client's MCP config, swapping in your
own token:

```json theme={null}
{
  "mcpServers": {
    "formpaste": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.formpaste.com/mcp",
        "--header",
        "Authorization: Bearer fpat_YOUR_TOKEN"
      ]
    }
  }
}
```

Restart your agent/client after saving the config. It should list `formpaste` as a
connected MCP server with **six tools** available.

For per-client instructions (Claude Code, Codex, Cursor, Claude Desktop, VS Code), see
[Install](/docs/agents/install).

## The six tools

| Tool                                                   | Purpose                                                                                    |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| [`create_form`](/docs/agents/create-form)                   | Create a form and get back its `access_key` + a wired snippet.                             |
| [`get_snippet`](/docs/agents/get-snippet)                   | Fetch a wired snippet for a framework, optionally with a real `access_key` filled in.      |
| [`list_forms`](/docs/agents/list-forms)                     | List your forms with ids, access keys, and counts - discover ids or confirm a form exists. |
| [`get_form`](/docs/agents/get-form)                         | Read one form's config to verify wiring. Never returns the webhook secret.                 |
| [`send_test_submission`](/docs/agents/send-test-submission) | Store a test submission to prove a form is live. No email, no quota impact.                |
| [`list_submissions`](/docs/agents/list-submissions)         | Read a form's submissions - metadata by default, full content on opt-in.                   |

Three of these - `list_forms`, `get_form`, and `send_test_submission` - let an agent
verify its own work: discover ids, read back a form's config, and prove it is
receiving. That's the entire tool surface. There's no `update_form`, `delete_form`, or
generic CRUD - those aren't built. If you need to change a form's destination, allowed
domains, or other settings, do that in the dashboard.

## What it's for

The MCP server exists so an agent (Claude Code, Cursor, or anything else that speaks
MCP) can complete a full "add a contact form to this site" task without you leaving
your editor: it calls `create_form`, gets an `access_key` and a wired snippet back,
pastes the snippet into your project, and, if you want it to check for replies later,
calls `list_submissions`. See [Cookbook prompts](/docs/agents/cookbook-prompts) for
ready-to-use prompts that drive this end to end.

If you'd rather not install anything, the `.env` path works too: create the form
yourself in the dashboard, put the `access_key` in `.env`, and prompt your agent to
wire the snippet using it. No MCP connection required - see the `.env`-path prompts in
the [cookbook](/docs/agents/cookbook-prompts).

<CardGroup cols={2}>
  <Card title="Install" icon="download" href="/docs/agents/install">
    Per-client setup for every MCP client.
  </Card>

  <Card title="create_form" icon="wand-magic-sparkles" href="/docs/agents/create-form">
    Provision a form and get a wired snippet back.
  </Card>

  <Card title="list_forms" icon="list" href="/docs/agents/list-forms">
    Discover form ids and confirm a form exists.
  </Card>

  <Card title="get_form" icon="magnifying-glass" href="/docs/agents/get-form">
    Read a form's config to verify wiring.
  </Card>

  <Card title="send_test_submission" icon="paper-plane" href="/docs/agents/send-test-submission">
    Prove a form is live with a test submission.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/docs/agents/troubleshooting">
    Fix connection, auth, and scope problems.
  </Card>
</CardGroup>