formester · Abhay2133 · Jun 16, 2026
diff --git a/docs/formester-mcp-server.md b/docs/formester-mcp-server.md
@@ -1,8 +1,8 @@
 # Formester MCP Server
 
-Connect AI agents directly to your Formester form submissions via the Model Context Protocol (MCP).
+Connect AI agents directly to your Formester forms and submissions via the Model Context Protocol (MCP).
 
-The Formester MCP server lets AI models — including Claude, ChatGPT, and any MCP-compatible agent — read submissions, analyze file attachments, search historical data, and write AI-generated insights back to your records. No custom API integration required.
+The Formester MCP server lets AI models — including Claude, ChatGPT, and any MCP-compatible agent — read and write submissions, analyze file attachments, search historical data, build and edit forms, apply styling, and manage conditional logic. No custom API integration required.
 
 **Endpoint:** `https://app.formester.com/mcp`
 
@@ -38,7 +38,8 @@ For scripts, automation, or clients that don't support OAuth:
 6. **Permissions** — select what the token is allowed to do:
    - **View Submissions** — read submission data and attachment metadata
    - **Update Submissions** — write custom fields back to submissions
-   - **View Forms** — read form metadata
+   - **View Forms** — read form structure, list forms, inspect styling and rules
+   - **Edit Forms** — create, edit, publish forms and manage styling and conditional rules
 7. Click **Create** and copy the token — it won't be shown again
 
 To revoke a token, click **Revoke** next to it on the same page.
@@ -209,7 +210,9 @@ Restart Windsurf after saving.
 
 ## Tools
 
-### `read_submission`
+### Submission Tools
+
+#### `read_submission`
 
 Read a single form submission by UUID.
 
@@ -218,7 +221,7 @@ Read a single form submission by UUID.
 - Set `include_files: true` to include file attachment metadata (IDs, filenames, URLs)
 - File *content* is not returned here — use `fetch_file` for that
 
-### `query_submissions`
+#### `query_submissions`
 
 Search and filter multiple submissions from a form.
 
@@ -227,7 +230,7 @@ Search and filter multiple submissions from a form.
 - Paginated: `limit` (max 100) + `offset`, returns `total_count` and `has_more`
 - Dates must be ISO8601 with timezone, e.g. `2024-01-01T00:00:00Z`
 
-### `update_submission`
+#### `update_submission`
 
 Write AI-generated data back to a submission as custom fields.
 
@@ -236,7 +239,7 @@ Write AI-generated data back to a submission as custom fields.
 - Auto-creates new custom columns if they don't exist
 - Cannot overwrite original form submission fields — only custom fields
 
-### `fetch_file`
+#### `fetch_file`
 
 Download and return the contents of a file attachment.
 
@@ -249,6 +252,134 @@ Download and return the contents of a file attachment.
 
 ---
 
+### Form Management Tools
+
+#### `list_forms`
+
+List all forms in your organization.
+
+- **Required permission:** View Forms
+- **Note:** Requires an organization-wide token (not a form-restricted token)
+- **Filters:** `query` — case-insensitive substring match on form name
+- Paginated: `page` + `per_page` (max 100)
+- **Returns:** Form ID, name, publish status, submission count, timestamps
+
+#### `create_form`
+
+Create a new form using a natural language description.
+
+- **Required permission:** Edit Forms
+- **Note:** Requires an organization-wide token
+- Provide `form_description` (e.g. `"Contact form with name, email, phone, and a message field"`)
+- Optionally pass explicit `form_fields`, a `quiz_type`, or a `name`
+- **Returns:** `process_id` — poll with `get_job_status` (job type: `form_creation`). Typically completes in 5–30 seconds.
+
+#### `get_form_data`
+
+Get the full structure of a form: pages, fields, and their IDs.
+
+- **Required permission:** View Forms
+- **Returns:** Pages with IDs, all fields with IDs, types, labels, validation rules, preview and live URLs
+- **Always call this before** `update_form_content` — field and page IDs are required for all edit operations
+
+#### `update_form_content`
+
+Add, edit, move, or delete fields and pages on a form. One action per call.
+
+- **Required permission:** Edit Forms
+- **Always call `get_form_data` first** to get valid field and page IDs
+- All changes are saved as a **draft** — call `form_publish` to make them live
+
+**Available actions:**
+
+| Action | What it does | Sync/Async |
+|--------|-------------|-----------|
+| `create_fields` | Add new fields using a natural language description | Async (poll `get_job_status`, type `field_create`) |
+| `update_fields` | Modify existing fields using a natural language description | Async (poll `get_job_status`, type `field_update`) |
+| `move_field` | Reposition a field (supports cross-page moves) | Sync |
+| `delete_fields` | Permanently delete fields (requires `confirm: true`) | Sync |
+| `create_page` | Add a new page | Sync |
+| `rename_page` | Rename an existing page | Sync |
+| `move_page` | Reorder pages | Sync |
+| `delete_page` | Permanently delete a page and all its fields (requires `confirm: true`) | Sync |
+
+#### `form_publish`
+
+Publish or unpublish a form.
+
+- **Required permission:** Edit Forms
+- `action`: `"publish"` or `"unpublish"`
+- Requires `confirm: true` as a safety gate
+- **Returns:** Updated publish status and the live URL
+
+---
+
+### Form Styling Tools
+
+#### `get_form_styling`
+
+Read the current styling of a form.
+
+- **Required permission:** View Forms
+- **Returns:** All style properties (colors, fonts, spacing, layout), per-page layout settings, and which properties are plan-gated (e.g. custom CSS)
+- **Always call this before** `set_form_styling` to see current values
+
+#### `set_form_styling`
+
+Update the visual appearance of a form.
+
+- **Required permission:** Edit Forms
+- Pass a `stylings` object with any combination of the properties below, and/or `page_stylings` for per-page layout
+
+**Colors:** `background_color`, `form_color`, `font_color`, `button_color`, `button_text_color`, `border_color`, `placeholder_color`, `progress_color`, `link_color`, `answer_text_color`
+
+**Typography:** `font_family`, `font_size` (8–72 px), `answer_font_size`, `label_font_weight`, `description_font_weight`
+
+**Spacing:** `margin_top`, `margin_bottom`, `form_vertical_padding`, `form_horizontal_padding`, `max_width`
+
+**Page layout:** pass `page_stylings: [{id: "page_uuid", page_layout: "full|left|right"}]`
+
+**Other:** `background_brightness` (10–200 %), `logo_size` (20–200 px), `is_rtl_language`, `custom_css` (plan-gated)
+
+---
+
+### Conditional Rules Tools
+
+#### `get_form_rules`
+
+Read the conditional logic rules on a form.
+
+- **Required permission:** View Forms
+- Paginated: `page` + `per_page` (max 100)
+- **Returns:** All rules with their conditions and actions
+
+#### `set_form_rules`
+
+Create or replace conditional logic rules using a natural language description.
+
+- **Required permission:** Edit Forms
+- Provide `rules_description` (e.g. `"Hide the shipping address field unless the user selects Delivery, and make the phone field required on page 2"`)
+- **Returns:** `process_id` — poll with `get_job_status` (job type: `rules_update`). Typically completes in 5–30 seconds.
+- The AI validates the resulting rules and will block conflicting rule sets
+
+---
+
+### Async Job Polling
+
+#### `get_job_status`
+
+Check the status of an async job started by `create_form`, `update_form_content`, or `set_form_rules`.
+
+- **Required permission:** View Forms
+- Provide the `process_id` and `job_type` returned by the async tool
+- **Statuses:**
+  - `in_progress` — still running, poll again
+  - `success` — completed; response includes job-specific results (e.g. form creation returns the new form's ID and edit URL)
+  - `failed` — job failed; response includes an error message
+  - `not_found` — invalid or expired `process_id` (process IDs expire after 15 minutes)
+
+---
+
 ## Choosing permissions
 
 Select only what your agent needs:
@@ -257,7 +388,8 @@ Select only what your agent needs:
 |-----------------|--------|
 | Only reads submissions | View Submissions |
 | Reads and writes insights back | View Submissions + Update Submissions |
-| Also needs form details | Add View Forms |
+| Reads form structure or lists forms | Add View Forms |
+| Builds, edits, or publishes forms | Add Edit Forms |
 
 ---
 
@@ -267,10 +399,15 @@ Select only what your agent needs:
 - **Support triage** — classify incoming requests by category and urgency, route automatically
 - **Lead qualification** — analyze contact form submissions, flag high-priority leads
 - **Survey analysis** — run sentiment analysis across all responses, tag themes, export insights
+- **Form generation** — describe what you need in plain English, let the AI build the form for you
+- **Brand-consistent styling** — apply a color palette and typography to a form programmatically
+- **Conditional logic** — describe your show/hide and required-field rules in plain language and let the AI wire them up
 
 ---
 
-## Typical workflow
+## Typical workflows
+
+**Submission processing workflow**
 
 ```
 1. Trigger (webhook / scheduled task / manual)
@@ -281,6 +418,20 @@ Select only what your agent needs:
 6. update_submission     → write results (scores, labels, summaries) back to the record
 ```
 
+**Form creation workflow**
+
+```
+1. create_form           → describe the form in plain English; receive process_id
+2. get_job_status        → poll until status = "success"; receive form UUID
+3. get_form_data         → inspect generated fields and page IDs
+4. update_form_content   → add, edit, or reorder fields as needed
+5. get_form_styling      → inspect current styling
+6. set_form_styling      → apply brand colors and typography
+7. set_form_rules        → describe conditional logic in plain language
+8. get_job_status        → poll until rules job completes
+9. form_publish          → make the form live
+```
+
 ---
 
 ## Troubleshooting