> ## Documentation Index
> Fetch the complete documentation index at: https://formhug.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# FormHug MCP Server
> Connect Claude, Cursor, or any MCP-compatible AI assistant to FormHug and manage forms and submissions through natural language.
The **FormHug MCP Server** lets AI assistants manage your forms and data through natural language. Built on the open Model Context Protocol, it turns any MCP-compatible client into a full FormHug interface — create forms, edit fields, read submissions, and submit entries without opening the dashboard.
For the product overview and positioning, see MCP for AI agents. For a narrative walkthrough of the use cases, read FormHug MCP for AI agents.
Describe what you need — AI generates fields and creates the form instantly
Add or remove fields, update names and descriptions
Browse, search, and retrieve form entries
Post new entries to any form programmatically
## MCP server details
| Property | Value |
| --------- | ------------------------------------- |
| URL | `https://formhug.ai/mcp` |
| Transport | Streamable HTTP |
| Auth | OAuth 2.1 (authorization code + PKCE) |
### Prerequisites
* A FormHug account — sign up at formhug.ai
* An MCP-compatible agent or IDE
* A web browser for the OAuth login flow
**Why do I need a FormHug account?** FormHug uses OAuth 2.1 to authenticate your agent. This links the agent's actions to your identity, so you control what it creates and submits on your behalf. Without authentication, the agent cannot access any FormHug tools, including filling other people's forms.
## Agent Capabilities
FormHug is built for both human users and AI agents. Forms stay easy for people to fill out, while remaining structured and machine-readable for MCP-compatible tools.
With the FormHug MCP server, an authenticated agent can manage forms in your account and submit entries to any published FormHug form.
### Manage your own forms
If you have a FormHug account, your agent can create forms, update fields, read submissions, and delete forms on your behalf.
**Example:**
> "Create a job application form with fields for name, email, LinkedIn URL, years of experience, and a cover letter"
Your agent can build the form and return a shareable link without needing you to open the dashboard.
### Submit to any published form
Authenticated agents can also submit entries to published FormHug forms they do not own. Form creators do not need to configure anything extra.
**Example:**
> "Fill in the onboarding form at formhug.ai/f/abc123 using the details from my notes"
## Connect Your Client
### Claude
Works on both **Claude Desktop** and **claude.ai**.
Go to **Customize → Connectors**, click **+** then **Add custom connector**.
Paste the remote MCP server URL and click **Add**:
```
https://formhug.ai/mcp
```
Authorize and the FormHug tools will be available in your chat.
**Team / Enterprise plans:** Ask your org Owner to add the connector via **Organization settings → Connectors** first, then connect from your own Connectors page.
### Cursor
Open **Cursor** → Settings → **MCP Servers** → Add Server.
Paste the server URL: `https://formhug.ai/mcp`
Authorize when prompted.
### Other MCP Clients
Any client that supports the Model Context Protocol can connect using the server URL above. The server uses standard HTTP transport.
## Available Tools
The FormHug MCP server exposes the tools below. Read-only tools are safe to call at any time; write tools that change account state are flagged.
### Account
| Tool | What It Does |
| -------- | --------------------------------------------------------------------------------------------------------------- |
| `get_me` | Get the currently authenticated user — email, display name, totals, organization, and current subscription plan |
### Forms
| Tool | What It Does |
| -------------------- | ------------------------------------------------------------------------------------------- |
| `list_forms` | List the forms you own, with optional name or folder filter (paginated) |
| `get_form` | Get a form's full structure, including every field's `api_code`, type, and choices |
| `preview_form` | Get a human-readable markdown preview of a form's structure |
| `get_published_form` | Get the public structure of any published form by token (supports password-protected forms) |
| `create_form` | Create a new form, optionally with fields defined inline |
| `update_form` | Update a form's name, description, locale, timezone, or folder |
| `delete_form` | Permanently delete a form and all of its entries |
### Fields
| Tool | What It Does |
| --------------- | ------------------------------------------------------------------------------------------- |
| `add_fields` | Append one or more fields to the end of an existing form |
| `update_fields` | Update one or more existing fields (label, required, placeholder, choices, …) by `api_code` |
| `remove_field` | Remove a field by its `api_code` |
| `move_field` | Reorder a field by placing it immediately before or after another field |
### Theme & settings
| Tool | What It Does |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `get_form_theme` | Get a form's current visual theme — header image, colors, typography, button and container styling |
| `update_form_theme` | Update a form's theme with partial-merge semantics (header image changes auto-derive a palette) |
| `get_form_settings` | Get a form's settings — locale, timezone, after-submission behavior, availability, access control, submission options |
| `update_form_settings` | Update a form's settings with partial-merge semantics |
### Entries
| Tool | What It Does |
| -------------- | ------------------------------------------------------------------------ |
| `list_entries` | List entries for a form (paginated, with cursor) |
| `get_entry` | Retrieve a single entry by serial number |
| `submit_entry` | Submit a new entry — works for your own forms and for any published form |
### Uploads
The MCP server cannot transfer file bytes itself. These tools return a one-time `upload_id` plus a direct `upload_url` — the client `PUT`s the raw file bytes to that URL, then references the `upload_id` in a follow-up tool call.
| Tool | What It Does |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prepare_image_upload` | Start a 2-step upload for a form header or wallpaper background image; reference the returned `upload_id` in `update_form_theme` |
| `prepare_entry_attachment_upload` | Start a 2-step upload for an `attachment` field (or a file column inside a `table` / `matrix`); reference the returned `upload_id` in `submit_entry` so entries can include files |
### Folders
| Tool | What It Does |
| --------------------- | ------------------------------------------------------------------- |
| `list_folders` | List all folders you own, including parent/ancestor relationships |
| `create_folder` | Create a new folder, optionally nested under a parent |
| `update_folder` | Rename a folder |
| `delete_folder` | Delete a folder; its forms and sub-folders move back to the desktop |
| `move_form_to_folder` | Move a form into a specific folder (or back to the desktop) |
### Webhooks
Webhook tools require the `integration:read` / `integration:write` scopes on your access token.
| Tool | What It Does |
| ---------------------------- | ------------------------------------------------------------------------------------------------- |
| `list_webhooks` | List webhook integrations configured on a form |
| `create_webhook` | Create a webhook that delivers a JSON payload on `entry_created` / `entry_updated` / `entry_paid` |
| `update_webhook` | Update a webhook's URL, subscribed trigger events, or enabled flag |
| `delete_webhook` | Permanently delete a webhook integration |
| `get_webhook_sample_payload` | Preview the JSON payload a webhook would deliver for a given trigger event |
`delete_form`, `delete_folder`, and `delete_webhook` are permanent. Deleting a form also deletes every entry it has received. These actions cannot be undone.
### Supported Field Types
Field types use snake\_case identifiers. The same set is available when creating fields (`create_form`, `add_fields`, `update_fields`) and when reading or submitting entries.
**Basic fields**
| Type | Notes |
| ------------ | -------------------------------------------------------------------------------- |
| `short_text` | Single-line text |
| `long_text` | Multi-line text |
| `radio` | Single-select choices |
| `checkbox` | Multi-select choices |
| `dropdown` | Single-select dropdown |
| `number` | Numeric input (precision, range, percentage, icon) |
| `email` | Email address |
| `phone` | Phone with international dial prefix |
| `date` | Date / datetime / month / age (controlled by `precision`) |
| `name` | Person name |
| `url` | URL |
| `address` | Structured postal address |
| `rating` | Star / heart / happy scale (3–10 levels) |
| `nps` | Net Promoter Score (0–10) |
| `attachment` | File upload — submit files via the 2-step `prepare_entry_attachment_upload` flow |
| `signature` | Hand-drawn signature — read-only via MCP |
| `ranking` | Drag-to-rank choices |
| `time` | Time-of-day picker |
| `location` | GPS location |
**Advanced fields**
`cascade` · `matrix` · `matrix_rating` · `likert` · `table` · `product` · `booking` · `linked_form`
**Display-only fields**
These render content but collect no answer, so they never appear in entry values.
| Type | Notes |
| ------------- | ------------------------------------------------------------------------------------------ |
| `page_break` | Splits a `classic`-layout form into pages (no effect on `card` layout) |
| `description` | A text block / section break — `label` is an optional heading, `notes` holds the body text |
When submitting entries via `submit_entry`, call `get_form` (or `get_published_form`) first to discover each field's `api_code` and type, then pass `field_values` keyed by `api_code`. The agent can read `formhug://entry-values` from the server for the exact value shape per type — including choice objects, phone country codes, and the nested shapes used by matrix, table, and booking.
`signature` fields are read-only via MCP — skip them when submitting entries. `attachment` fields are supported through the 2-step `prepare_entry_attachment_upload` flow, since the MCP server cannot transfer file bytes directly.
## Example Prompts
Once connected, give your AI assistant natural language instructions:
**Building and editing forms**
* *"Create a customer feedback form with a star rating, email, and comment field"*
* *"Add a required phone number field to my Event Registration form"*
* *"Show me all my forms"*
* *"What fields does my Contact Us form have?"*
**Reading submissions**
* *"List the last 20 submissions for my Contact Us form"*
* *"Show me the most recent entry on my survey"*
* *"Get entry number 5 from my registration form"*
**Managing forms**
* *"Rename the form called Test to Customer Feedback 2025"*
* *"Delete the form called Old Test Form"*
**Submitting entries**
* *"Submit a test entry to my Contact form — name: Jane Smith, email: [jane@example.com](mailto:jane@example.com)"*
## Related
Install the ChatGPT app and create hosted forms from a conversation
Connect Claude to FormHug with a custom MCP connector
View and manage submissions in the FormHug dashboard
Build forms with AI directly inside FormHug
Learn how fields and forms are structured
See the product page for agent-driven form creation and submission workflows