MCP tools for offers

Offer tools manage calls to action that direct visitors to a URL. Offers and forms share ofr_ IDs, but only items with triggeredAction.type: "link" are classified as offers. Other action types belong to form tools. The performance tool on this page reports both.

MCP offer access and draft changes

Every tool accepts an optional string project_id and follows the shared MCP authorization and project-selection rules. There is no additional offer-specific feature check.

Configuration reads prefer the draft over published configuration. Create, update, duplicate, and delete save a draft and a snapshot of the previous configuration. They do not publish, open a URL, or trigger a visitor conversion. Publishing is separate.

Results below are the JSON payload inside an MCP response. Shared errors include missing, invalid, or inaccessible project IDs and unavailable MCP access. Mutations use Validation error: ... for configuration-schema failures and Operation failed: ... for other exceptions. All examples are illustrative, not executed, and use fictional WorkForge resources.

Content and action objects

Create and update accept these optional nested values:

The text parts support {{ phrases.phr_workdemo }} references. The internal offer name does not automatically become the headline. For non-link actions, the more complete input schema is on the form reference.

Non-link actions also receive a post-submit redirectFunnel during save-time repair when no nonempty tree exists: it contains a message with thanks_message, or Thank you! by default. Changing the message setting later does not overwrite an existing nonempty tree. Use the form tools for field management and inspect the saved definition after changing action type.

The stored offer object contains id, name, isEnabled, parts, and triggeredAction: {type, settings}. Input is_enabled becomes isEnabled. There is no offer_id property in a returned offer object; its ID is id.

create-offer

Creates a draft offer. Required name is a string. Optional arguments are project_id, boolean is_enabled defaulting to true, and the parts and action objects above.

Returns the complete new object with a generated ofr_ ID. It does not create a widget or attach the offer to a flow. Invalid stored values can fail configuration validation. A supplied non-link action changes the item's classification; use form reads for that result.

Illustrative request:

{"name":"create-offer","arguments":{"name":"WorkForge demo","parts":{"title":"See WorkForge in action","button_text":"Book a demo"},"action":{"type":"link","settings":{"url":"https://example.com/demo"}}}}

Illustrative result:

{"id":"ofr_workdemo","name":"WorkForge demo","isEnabled":true,"parts":{"title":"See WorkForge in action","description":null,"buttonText":"Book a demo","imageUrl":null},"triggeredAction":{"type":"link","settings":{"url":"https://example.com/demo"}}}

list-offers

Lists link-type items only. Optional string project_id is the only argument. Returns an array of compact summaries with id, name, isEnabled, type: "cta", and triggeredActionType. An empty project returns []. There is no pagination or search argument.

This read makes no configuration change. Shared authorization errors apply.

Illustrative request and result:

{"name":"list-offers","arguments":{}}

[{"id":"ofr_workdemo","name":"WorkForge demo","isEnabled":true,"type":"cta","triggeredActionType":"link"}]

get-offer

Returns one offer with display annotations. Arguments are optional string project_id and required string offer_id.

The result includes the stored offer fields, triggeredActionSummary, and containingFlows, an array of {id, name} objects. IDs can gain resolved-name properties such as id_name. Text parts are display-oriented: HTML is stripped and phrase references receive annotations. They are not a lossless replacement payload for rich content.

Missing offer_id returns offer_id is required. Missing items return Offer not found: ID. A non-link item returns an error naming its action type and directing the caller to get-form. No draft or provider mutation occurs.

Illustrative request and result:

{"name":"get-offer","arguments":{"offer_id":"ofr_workdemo"}}

{"id":"ofr_workdemo","id_name":"WorkForge demo","name":"WorkForge demo","isEnabled":true,"parts":{"title":"See WorkForge in action","description":null,"buttonText":"Book a demo","imageUrl":null},"triggeredAction":{"type":"link","settings":{"url":"https://example.com/demo"}},"triggeredActionSummary":"Link: https://example.com/demo","containingFlows":[]}

update-offer

Changes an existing draft item. Required offer_id is a string. Optional arguments are project_id, string name, boolean is_enabled, and the shared parts and action objects. At least one non-null update value is required.

Returns the complete updated stored object, without the additional display summaries from get-offer. Omitted top-level fields, part properties, and action-setting keys remain unchanged. Supplied settings replace matching keys rather than recursively merging arrays. Changing the action type retains unrelated old settings and can turn the item into a form.

Missing ID returns offer_id is required. An empty update returns No fields provided to update. A missing item returns Operation failed: Offer not found: ID. The update handler does not reject a non-link item by type. The caller must select the intended resource.

Illustrative request:

{"name":"update-offer","arguments":{"offer_id":"ofr_workdemo","action":{"settings":{"url":"https://example.com/book-demo"}}}}

Illustrative result:

{"id":"ofr_workdemo","name":"WorkForge demo","isEnabled":true,"parts":{"title":"See WorkForge in action","description":null,"buttonText":"Book a demo","imageUrl":null},"triggeredAction":{"type":"link","settings":{"url":"https://example.com/book-demo"}}}

duplicate-offer

Copies an offer into the draft with a new ofr_ ID. Arguments are optional string project_id, required string offer_id, and optional string new_name. The default name is the original name plus (Copy).

Returns the complete copied offer, retaining its content, enabled state, and destination. It does not duplicate or change containing flows. Missing ID and missing source return errors. A form source returns Item ID is a form, not an offer. Use duplicate-form instead.

Illustrative request and result excerpt:

{"name":"duplicate-offer","arguments":{"offer_id":"ofr_workdemo","new_name":"WorkForge demo alternative"}}

{"id":"ofr_copydemo","name":"WorkForge demo alternative","isEnabled":true}

The full result also contains the copied parts and triggeredAction.

delete-offer

Removes an item from the draft and clears offerId on flow nodes that reference it. Arguments are optional string project_id and required string offer_id.

Returns {"deleted":true,"offer_id":"ID"}. Missing ID returns offer_id is required. A missing item returns Operation failed: Offer not found: ID. This tool doesn't reject form IDs. Supplying a form ID can therefore delete that form and clear its flow references.

Illustrative request and result:

{"name":"delete-offer","arguments":{"offer_id":"ofr_copydemo"}}

{"deleted":true,"offer_id":"ofr_copydemo"}

The deletion does not publish or remove previously recorded conversions.

get-offer-performance

Reports recorded exposure and conversion activity for all forms and offers currently present in the draft-first configuration. It does not accept an individual offer filter.

Returns an array of per-resource rows. The overall row is excluded. A configured item without matching activity need not have a row. The fields are:

• for: an array identifying the offer or form bucket.
• numerator: unique converting visitors in the range.
• denominator: unique exposed visitors for that same item in the range.
• data: daily entries containing x, numerator, and denominator.
• change: relative conversion-rate change against the preceding period, or null when no comparison is available.
• previousPeriod: numerator, denominator, and rate.

The current rate is computed from the returned numerator and denominator; there is no top-level rate property. The service divides by 1 when the denominator is zero for its internal comparison calculation. change is null when the previous denominator is zero. If the previous rate is zero and the current rate is positive, change is 1, the service's convention for a 100% increase. Daily unique counts must not be added to reconstruct range-wide unique counts.

Date-only ranges compare the same number of preceding local calendar days. Timestamp ranges use the preceding equal-duration period. This is observational performance, not a split-test verdict.

A project with no configured offers or forms returns No offers or forms are configured for project ID. Invalid date-only values or timezone values return Date-only inputs must be valid calendar dates and timezone must be valid. Reporting failures can return an MCP failure rather than empty activity. No configuration is changed.

Illustrative request and result for a resource with activity:

{"name":"get-offer-performance","arguments":{"date_from":"2026-10-01","date_to":"2026-10-01","timezone":"UTC"}}

[{"for":["ofr_workdemo"],"numerator":10,"denominator":100,"data":[{"x":"2026-10-01T00:00:00.000Z","numerator":10,"denominator":100}],"change":1,"previousPeriod":{"numerator":5,"denominator":100,"rate":0.05}}]