Form, field and widget tools | Made with Pepper

For: developers connecting an HTTP or MCP client. Start with Agent API and AI clients.

AI is optional. You confirm invoice issuance in Pepper.

Forms and custom fields

These tools need the delegate's Use internal forms permission and current record access.

HTTP method and path	MCP tool	Scope
`GET /api/v1/forms/{id}`	`forms_get`	`forms:read`
`GET /api/v1/custom-fields`	`fields_schema`	`forms:read`
`GET /api/v1/custom-fields/{id}`	`fields_get`	`forms:read`
`POST /api/v1/custom-fields/{id}/merge`	`fields_merge`	`forms:read`
`POST /api/v1/forms/prepare`	`forms_prepare`	`forms:prepare`
`GET /api/v1/views/form`	`views_form`	`forms:read`
`GET /api/v1/views/form_record`	`views_form_record`	`forms:read`
`GET /api/v1/views/form_submission`	`views_form_submission`	`forms:read`

forms_get needs id and type (form, form_record or form_submission). Only form managers receive the public form address.

Custom reads need type, the registered record type. Value and merge reads also need id. Merge needs template, up to 4,000 characters.

fields_schema returns active definitions. Use custom_<key> in ordinary view filters, sorts and columns. Retired or unsupported criteria return 422.

forms_prepare needs operation, payload and an idempotency key. HTTP uses the Idempotency-Key header; MCP uses idempotency_key.

Operation	Other inputs and permission
`save`	Complete form definition; `record_id` and current `payload.version` for an edit; form management
`publish`	`record_id`, `payload.version`, `payload.published`; form management
`submit`	Internal form `record_id`, `payload.version`, `payload.values`; target permission for customer forms
`define`	Record `type`, `payload.definition`; `field_id` and `payload.version` for an edit; form management
`retire`	Record `type`, `field_id`, `payload.version`; form management
`set`	Record `type`, `record_id`, `payload.revision`, `payload.values`; ordinary record write permission
`archive`	Submission `record_id`, `payload: {}`; form management; optional `type` must be `form_submission`
`restore`	Submission `record_id`, `payload: {}`; form management; optional `type` must be `form_submission`

Preparation returns written: false, proposed input and review_url. It writes no form, customer, custom value, file or submission.

Open the link in the browser. Review the proposed values or the submission's current state. Use the ordinary Save, Publish form, Submit form, Retire field, Archive or Restore control.

Publish and retire links open the appropriate screen without selecting or executing the action. Check the intended field and state yourself.

Archive and restore links open the permitted submission. The page shows its current state and the available control; opening it changes nothing. Preparation returns no proposed values for these operations. Form management and current record access still apply when you open the link and confirm the action.

The browser rechecks permissions and versions. Prepared input has a 12,000-byte limit. Choose new files in the browser.

Read the forms manual for the complete definition and value limits. Public links are separate from agent connections.

Widgets

Both tools require Manage forms and custom definitions and an active non-guest delegate.

HTTP method and path	MCP tool	Scope
`GET /api/v1/widgets/{id}`	`widgets_get`	`forms:read`
`POST /api/v1/widgets/prepare`	`widgets_prepare`	`forms:prepare`

widgets_get needs id. It returns configuration, the public snippet and load/response counts. It returns no entered values or visitor identity.

widgets_prepare needs payload and an idempotency key. HTTP uses Idempotency-Key; MCP uses idempotency_key.

Payload field	Required value
`name`, `type`, `source_id`	Name up to 120 characters, `form`, and a response-form ULID
`origins`	1–20 exact HTTPS origins; HTTP loopback for local tests
`language`, `theme`	`page` or a supported locale; `light`, `dark` or `page`
`accent`	A 6-digit hexadecimal color
`show_title`, `enabled`	Booleans; proposed values only
`version`	Current widget version for an edit; omit for a new widget

For an edit, also send widget_id. Preparation validates the selected form and settings. Its browser proposal has a 12,000-byte limit.

The result contains written: false, payload and review_url. Open the link, review the preview and save through the ordinary configurator.

Saving closes publication. Enable and publish through the browser after checking the website origins. The agent performs no save or publication action.

Read the widget guide for source restrictions, sign-in and refusal recovery.