formpaste-mcp

formpaste-mcp

Create and wire up contact forms from your coding agent. Six tools for forms, snippets, and submissions.

What this is

This package is a thin wrapper that launches mcp-remote pointed at the hosted Formpaste MCP server (https://api.formpaste.com/mcp, streamable-http transport). The equivalent manual mcp-remote config works identically; this package exists mainly so agents and clients can discover and install Formpaste's MCP server by name, not because it does anything the manual config cannot.

Requirements

• Node.js 18 or later
• A Formpaste account
• An API token from Settings -> API & MCP in the Formpaste dashboard

Install

Each client below is configured to talk to the hosted MCP endpoint at https://api.formpaste.com/mcp. Replace fpat_YOUR_TOKEN with a token minted from Settings -> API & MCP.

Claude Code

claude mcp add formpaste --transport http https://api.formpaste.com/mcp \
  --header "Authorization: Bearer fpat_YOUR_TOKEN"

Codex

# ~/.codex/config.toml
[mcp_servers.formpaste]
command = "npx"
args = ["mcp-remote", "https://api.formpaste.com/mcp", "--header", "Authorization: Bearer fpat_YOUR_TOKEN"]

Cursor

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

Claude Desktop

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

VS Code

// .vscode/mcp.json
{
  "servers": {
    "formpaste": { "command": "npx", "args": ["mcp-remote", "https://api.formpaste.com/mcp", "--header", "Authorization: Bearer fpat_YOUR_TOKEN"] }
  }
}

Any MCP client, via this package

FORMPASTE_TOKEN=fpat_YOUR_TOKEN npx formpaste-mcp

formpaste-mcp reads FORMPASTE_TOKEN from the environment (or a --token flag) and starts mcp-remote against the hosted endpoint for you.

The six tools

Tool	Purpose	Scope
create_form	Create a form, return its access key and a wired snippet	setup
get_snippet	Return a copy-paste snippet for html/react/nextjs/astro/vue/svelte	setup
list_forms	List all forms with ids, names, access keys, inbox/spam counts	setup
get_form	Read one form's config to verify it is wired correctly	setup
send_test_submission	Store a test submission to prove a form is live	setup
list_submissions	List submissions, optionally including message bodies	full

Token scopes

Formpaste API tokens have two scopes:

• full can do everything, including reading submission content via list_submissions.
• setup can do everything except list_submissions, so it never reads third-party submission content.

Use a setup-scoped token for agent use. It covers form creation, snippets, and verifying that a form is wired correctly, without granting access to the data your forms collect.

Worked example

See examples/wire-a-form.md for a full walkthrough: create a form, get a snippet, paste it into a page, send a test submission, and confirm the form is wired correctly.

Links

• Documentation: https://formpaste.com/docs
• MCP server docs: https://formpaste.com/docs/agents/mcp-server
• Install guide: https://formpaste.com/docs/agents/install
• Issues: https://github.com/webrating/formpaste-mcp/issues