# MCP tool reference

All 24 tools, the minimum access level each needs, and their arguments (`*` = required).

## Organization

| Tool | Level | Arguments | Description |
| --- | --- | --- | --- |
| `whoami` | viewer | — | Organization, key name, effective access level and what it allows. Call first. |
| `get_config_reference` | viewer | — | The complete form config reference (field types, properties, templates, payloads). Read before building forms. |
| `get_usage` | viewer | `period`: 24h | 7d | 30d | Monthly submission quota (used / limit / reset date) and webhook call counts by type and outcome. |

## Forms

| Tool | Level | Arguments | Description |
| --- | --- | --- | --- |
| `list_forms` | viewer | `folder_id` (or "none"), `search` | Summaries: id, name, slug, folder, active, webhook flags, field count, hosted URL. |
| `get_form` | viewer | `form_id` | Full form with `config`. Header values redacted. |
| `get_embed_snippet` | viewer | `form_id` | Embed HTML and hosted page URL. |
| `create_form` | editor | `name`\*, `slug`, `n8n_webhook_url`, `webhook_headers`, `onload_webhook_url`, `onload_webhook_method`, `onload_webhook_headers`, `config`, `folder_id` | Create a form. Subject to the plan's form quota. |
| `update_form` | editor | `form_id`\*, any create field, `is_active` | Only sent fields change; `config` is replaced whole. Omit headers to keep them. |
| `delete_form` | admin | `form_id` | Permanent. Prefer `update_form` with `is_active: false`. |

## Webhook history

| Tool | Level | Arguments | Description |
| --- | --- | --- | --- |
| `list_submissions` | viewer | `form_id`, `type`: submit | onload | action | fetch | all, `status`: success | failed, `since`, `limit`, `offset` | Every webhook call with request, n8n response or error, duration. Omit `form_id` to search the organization. |

## Folders

| Tool | Level | Arguments | Description |
| --- | --- | --- | --- |
| `list_folders` | viewer | — | Folders used to organize forms. |
| `create_folder` | editor | `name` | Create a folder. |
| `rename_folder` | editor | `folder_id`, `name` | Rename a folder. |
| `delete_folder` | editor | `folder_id` | Delete a folder; its forms move to the top level. |

## Themes

| Tool | Level | Arguments | Description |
| --- | --- | --- | --- |
| `list_themes` | viewer | — | Themes and which is default. |
| `create_theme` | admin | `name`\*, colors, `column_gap`, `row_gap`, `is_default` | Create a theme. Apply it with `config.theme_id`. |
| `update_theme` | admin | `theme_id`\*, any theme field | Update a theme. |

## Access

| Tool | Level | Arguments | Description |
| --- | --- | --- | --- |
| `list_roles` | viewer | — | Form-access roles. |
| `list_form_users` | viewer | `search`, `status` | People who sign in to protected forms. |
| `get_form_access` | viewer | `form_id` | Login requirement and allowed roles/users. |
| `set_form_access` | admin | `form_id`\*, `auth_required`\*, `role_ids`, `user_ids` | Require login and choose who may access. Lists replace existing ones. |
| `create_form_user` | admin | `email`\*, `password`\* (8+), `name` | Create a form user. |
| `assign_form_user` | admin | `user_id`\*, `form_id`\* | Grant a form user access to a form. |
| `unassign_form_user` | admin | `user_id`\*, `form_id`\* | Remove that access. |

## Results and errors

Tools return JSON text. A failure is returned as a tool result with `isError: true` and the HTTP-style status and message, for example:

```
{ "status": 403, "error": "Insufficient permissions", "code": "INSUFFICIENT_PERMISSIONS",
  "message": "This action requires admin role or higher. You have creator role." }
```

Invalid arguments are rejected by the MCP layer before anything runs.

## Recommended workflow for agents

1.  `whoami` — know the organization and level.
2.  `get_config_reference` — once, before building or editing forms.
3.  `list_forms` → `get_form` — read before you write.
4.  `create_form` / `update_form` with the complete `config`.
5.  `get_embed_snippet` — hand the result to the user.
6.  `list_submissions` — verify deliveries after the user tests.

---
Source: https://form2wf.com/docs/mcp-tools — Form2Workflow documentation (AI agents)