The full MCP tool catalog, with params and returns.
The MCP server exposes 29 tools. Everything below is generated from the live tool schemas in server/mcp-tools.ts — the source of truth — by npm run gen:mcp-docs. A CI check fails the build if a tool changes and this page isn't regenerated, so it can't drift.
| Tool | What it does |
|---|---|
| whoami | Which OptiMonk account this connection is acting as, and what it is allowed to do. Call this first when a tool returns a not-found or a scope error — those read the same whether the credential is pointed at the wrong account or the object really is missing. |
| build_popup | Start a popup build from a public reference image URL. Returns a runId, which is also a valid jobId: call watch_job to wait until the job is terminal, or get_job for a single read or when the client cannot hold a request open. |
| get_popup_html | Fetch completed build HTML. Wait with watch_job first (the runId is a valid jobId); use get_job for a single read or when the client cannot hold a request open. |
| get_popup_preview | SEE a completed build: server-rendered screenshots at real browser proportions — desktop (1440×900) and mobile (390×844) — returned as image content blocks. get_popup_html returns the markup; this returns the picture. |
| edit_popup | Apply a natural-language edit to a completed build. Returns queued with a jobId; call watch_job with that jobId, then get_popup_html. Use get_job for a single read or when the client cannot hold a request open. |
| upload_reference_image | Upload a base64-encoded image to public storage; use the returned publicUrl as build_popup referenceUrl. |
| get_design_thread | Read a design thread: the ordered event log, the derived state (designing / variant_picked / campaign_live) and the current concept cards with their preview images. campaign_live means a campaign exists (it is created inactive); state.published says whether it was published and switched on. A single read; to wait for progress use watch_design_thread, never a poll loop. To show the cards for the user to pick from, use get_concept_board. |
| get_concept_board | SEE the concept cards of a design thread: this result ATTACHES the images — one 2×2 board with each card's letter and name rendered into it, plus one thumbnail per card in board order. Show the user the attached board image (or the attached thumbnails) exactly as returned; never hotlink imageUrl/mockupUrl inside HTML, widgets or artifacts (sandboxes block cross-origin images and the user sees broken tiles) — those URLs are for opening in a browser only. Under the picture list each letter with its name, then ask ONE question: which letter? Call select_variant only after the user has chosen. get_design_thread returns the same cards as data. |
| start_design_thread | Open a new design thread from a brief (e.g. "a welcome popup for earfun.hu with 10% off"). Returns the session id; the agent then asks discovery questions and generates concepts — call watch_design_thread to wait for the next question or the concept cards (never sleep or poll), and send_design_message to answer. |
| get_coupon | Read the coupon a build hands out: whether the popup even has a coupon element, the stored spec, and every fixed code currently in it. Call this before proposing a coupon — an empty codes list means the popup would publish a blank coupon box. |
| list_campaigns | List campaigns for this account (newest first). |
| get_campaign | Get a campaign by runId and/or campaignId (at least one required). |
| create_campaign | Create a DRAFT campaign from a completed build (no publish). Requires a designer-session-backed build: start_design_thread creates one, while a standalone build_popup run does not. Returns `livePreview` (a shareable public preview link and a logged-in app link) — give both to the user in your closing message, with a targeting summary from `summary`. |
| set_campaign_name | Rename a campaign. |
| publish_campaign | Publish a campaign to OptiMonk and activate it. Returns `livePreview` (a shareable public preview link and a logged-in app link) — give both to the user in your closing message, with a targeting summary. |
| get_campaign_settings | Read a build's current delivery settings (triggers, targeting, frequency, overlay) and a human-readable summary of them. |
| set_campaign_settings | Save a build's delivery settings (triggers, targeting, frequency, overlay) as one unit; creates the campaign's settings draft if no campaign exists yet. |
| prepare_animated_background | Start generating the animated background for one design, before the merchant is asked whether they want it. Takes about 40 seconds. Safe to call again: a second call while one is running, or on a design that already has its answer, starts nothing and tells you which. Many designs are deliberately not eligible — a flat-colour background has nothing to animate — and that is a normal answer, not a failure. Pass wait to be told the settled outcome instead of returning at the claim. |
| set_animated_background | Record whether this design should use its animated background or stay static. Choosing animated requires that the design actually has a clip — prepare_animated_background makes one, and many designs are deliberately not eligible. The answer survives a reload. Note: builds are static for now — the design journey no longer offers animation and the built popup does not carry the clip; the recorded answer is kept for a later campaign-page feature. |
| set_coupon | Settle the coupon on a build AFTER the merchant agreed to it: writes the spec, rewrites the fixed code in the popup, and records the agreement on the design thread. Propose the coupon in the conversation first — this tool is the approval, not the proposal. |
| get_job | Read the status of a long-running job by its jobId — a build, or a queued design-thread change. terminal tells you whether anything further will happen on its own. A build job in status selected is a design that was picked but never built: nothing is running, and select_variant starts the build. Prefer watch_job while you are waiting; use this for a single read or when the client cannot hold a request open. |
| watch_job | Wait for a long-running job to finish instead of polling. Emits progress notifications while it runs (when your client sends a progressToken) and returns the final status. Returns immediately if the job is already finished. On timeout it returns timedOut with the status so far — call again to keep waiting. Without a progressToken the call is silent until it returns, so keep timeoutSeconds under your client's idle timeout for tool calls (often 300 s); the default already is. |
| set_plan_coupon | Settle the coupon on the PLAN, before any popup has been built — the coupon step of the campaign-creation flow. Use this while the merchant is still choosing a design; once a popup exists, set_coupon writes to the build itself. Propose the coupon in the conversation first: this tool records the agreement, it is not the proposal. |
| regenerate_animated_background | Change how a built popup's animated background MOVES ("slower", "make the steam drift left", "stop the water moving"). Needs a built popup that already HAS an animated background — it regenerates the clip, it cannot add one. Takes about a minute: answers at once with a jobId, watch it with watch_job and read result.body for the new clip's url and motion. The new clip is a draft until it is saved. |
| patch_popup | Edit a built popup by describing the change in words ("make the headline bigger", "swap the button colour"). Answers at once with a jobId; watch it with watch_job, then read the edited html from the finished job's result (result.body.html). Omit html to edit the popup's current document. Use edit_popup instead for a conversational redesign through the design thread. |
| send_design_message | Send a message to a design thread. While the thread is still scoping it ANSWERS the agent's discovery question; once cards exist it refines the concept board; after select_variant it edits the picked popup. Set newVariant to start another concept round instead; newVariantFrom can optionally anchor it to a picked run. Otherwise the server routes by thread state. Then wait with watch_design_thread when the message landed on the board (routedTo: board) or with watch_job on the returned jobId when it landed on a run — never sleep or poll get_design_thread between calls. (Picking a variant is not done by message — use select_variant.) |
| restore_revision | Restore an earlier version of the popup in a design thread. Name the version by revisionId, or ask for stepsBack (1 = the previous version). The restore runs as a queued design change and answers with a jobId to watch; the live campaign is not changed until you publish again. |
| select_variant | Pick one or more concept cards and BUILD them into popups — the agent's Build it. This is THE decision that narrows the thread: afterwards send_design_message edits the picked popup instead of the board. The build starts in the background and the draft campaign is created right away: watch the returned jobId with watch_job, then agree targeting with get_campaign_settings / set_campaign_settings and publish with publish_campaign. This call answers within about 40 seconds even when the build is still starting up — `pending: true` with a null campaignId means exactly that, so watch the jobId and read the campaign from get_design_thread shortly after; never re-pick because a call felt slow, and if one ever does time out, repeat it with the same ids rather than picking again, since a repeat returns the same runs and never builds twice. Pass several ids for an A/B pair — always the FULL selection in the same order, since a call that adds to an earlier pick re-adopts the cards it repeats rather than reusing their runs. |
| watch_design_thread | Wait for a design thread to need you instead of polling: returns when the agent asks a discovery question, when the concept cards and their mockups are all ready, when the thread ends, or on timeout (then call again). Returns immediately if one of those already holds. Never sleep or poll get_design_thread between calls. |
Tool details
Parameters, defaults, enums, and return fields for each tool:
whoami
0 params
Which OptiMonk account this connection is acting as, and what it is allowed to do. Call this first when a tool returns a not-found or a scope error — those read the same whether the credential is pointed at the wrong account or the object really is missing.
Returns accountId loginId via credential scopes canPublish
build_popup
5 params
Start a popup build from a public reference image URL. Returns a runId, which is also a valid jobId: call watch_job to wait until the job is terminal, or get_job for a single read or when the client cannot hold a request open.
referenceUrl string required
Publicly fetchable PNG/JPG/WEBP of the popup to recreate
domain string required
Target store hostname, e.g. shop.com
userPrompt string optional
formatHint enum optional
card fullscreen
idempotencyKey string optional
Pass a stable id to make retries safe: a second call with the same key returns the first call's runId instead of starting (and charging for) another build.
Returns runId shortId status replayed note
get_popup_html
2 params
Fetch completed build HTML. Wait with watch_job first (the runId is a valid jobId); use get_job for a single read or when the client cannot hold a request open.
runId string required
viewport enum optional default: desktop
desktop mobile
Returns html viewport
get_popup_preview
2 params
SEE a completed build: server-rendered screenshots at real browser proportions — desktop (1440×900) and mobile (390×844) — returned as image content blocks. get_popup_html returns the markup; this returns the picture.
runId string required
viewport enum optional default: both
both desktop mobile
Which viewport(s) to picture. Each comes back as its own image block.
Returns runId images missing
edit_popup
4 params
Apply a natural-language edit to a completed build. Returns queued with a jobId; call watch_job with that jobId, then get_popup_html. Use get_job for a single read or when the client cannot hold a request open.
runId string required
message string required
What to change, e.g. 'make the headline red' (maximum 2000 characters)
viewport enum optional default: desktop
desktop mobile
imageUrls array optional
Up to 8 public reference image URLs
Returns runId jobId status note
upload_reference_image
2 params
Upload a base64-encoded image to public storage; use the returned publicUrl as build_popup referenceUrl.
imageBase64 string required
Base64-encoded image bytes (no data: prefix)
contentType enum required
image/png image/jpeg image/webp
Returns publicUrl storageKey
get_design_thread
1 param
Read a design thread: the ordered event log, the derived state (designing / variant_picked / campaign_live) and the current concept cards with their preview images. campaign_live means a campaign exists (it is created inactive); state.published says whether it was published and switched on. A single read; to wait for progress use watch_design_thread, never a poll loop. To show the cards for the user to pick from, use get_concept_board.
sessionId string required
Design session id
Returns sessionId domain status state legacy events concepts
get_concept_board
1 param
SEE the concept cards of a design thread: this result ATTACHES the images — one 2×2 board with each card's letter and name rendered into it, plus one thumbnail per card in board order. Show the user the attached board image (or the attached thumbnails) exactly as returned; never hotlink imageUrl/mockupUrl inside HTML, widgets or artifacts (sandboxes block cross-origin images and the user sees broken tiles) — those URLs are for opening in a browser only. Under the picture list each letter with its name, then ask ONE question: which letter? Call select_variant only after the user has chosen. get_design_thread returns the same cards as data.
sessionId string required
Design session id
Returns sessionId cells next
start_design_thread
1 param
Open a new design thread from a brief (e.g. "a welcome popup for earfun.hu with 10% off"). Returns the session id; the agent then asks discovery questions and generates concepts — call watch_design_thread to wait for the next question or the concept cards (never sleep or poll), and send_design_message to answer.
text string required
The brief: what popup is wanted, for which store
Returns sessionId shortId next
get_coupon
1 param
Read the coupon a build hands out: whether the popup even has a coupon element, the stored spec, and every fixed code currently in it. Call this before proposing a coupon — an empty codes list means the popup would publish a blank coupon box.
runId string required
The build's runId
Returns runId hasCouponElement spec summary codes emptyCodeSlots contractIssues
list_campaigns
1 param
List campaigns for this account (newest first).
limit number optional default: 20
Returns campaigns nextCursor
get_campaign
2 params
Get a campaign by runId and/or campaignId (at least one required).
runId string optional
campaignId string optional
Returns id name status domain v3RunId omCampaignId livePreview next
create_campaign
2 params
Create a DRAFT campaign from a completed build (no publish). Requires a designer-session-backed build: start_design_thread creates one, while a standalone build_popup run does not. Returns `livePreview` (a shareable public preview link and a logged-in app link) — give both to the user in your closing message, with a targeting summary from `summary`.
runId string required
A completed build's runId
domain string optional
Only after a domain_not_on_account refusal: the merchant's own domain to file the campaign under, from the list that refusal named
Returns id name status campaign summary livePreview next
set_campaign_name
2 params
Rename a campaign.
campaignId string required
name string required
Returns name
publish_campaign
1 param
Publish a campaign to OptiMonk and activate it. Returns `livePreview` (a shareable public preview link and a logged-in app link) — give both to the user in your closing message, with a targeting summary.
campaignId string required
The campaign to publish, by id
Returns campaignId omCampaignId omVariantId databaseId propagating ssrPreviewUrl activation redirect livePreview next
get_campaign_settings
2 params
Read a build's current delivery settings (triggers, targeting, frequency, overlay) and a human-readable summary of them.
runId string optional
The build whose settings to read (give this OR campaignId)
campaignId string optional
The campaign whose settings to read (give this OR runId)
Returns campaignId settings summary livePreview next
set_campaign_settings
12 params
Save a build's delivery settings (triggers, targeting, frequency, overlay) as one unit; creates the campaign's settings draft if no campaign exists yet.
runId string optional
The build whose settings to save (give this OR campaignId)
campaignId string optional
The campaign whose settings to save (give this OR runId)
trigger enum required
timed exitIntent scrollDown inactivity click javascriptEvent omPassthrough
What opens the popup — the choice the delay/scroll fields below hang off
timedDelaySec number optional
Seconds to wait, for a timed or inactivity trigger only (default 5)
scrollPercent number optional
How far down the page, for a scrollDown trigger only (default 50)
where enum required
all homepage urlContains
Which pages the popup may show on
urlContains string optional
The URL fragment to match, for where: "urlContains" only (default "")
triggers array optional
targeting array optional
frequency object optional
overlay object optional
meta object optional
Returns campaignId settings summary livePreview next
prepare_animated_background
3 params
Start generating the animated background for one design, before the merchant is asked whether they want it. Takes about 40 seconds. Safe to call again: a second call while one is running, or on a design that already has its answer, starts nothing and tells you which. Many designs are deliberately not eligible — a flat-colour background has nothing to animate — and that is a normal answer, not a failure. Pass wait to be told the settled outcome instead of returning at the claim.
sessionId string required
The design thread the concept belongs to
conceptId string required
The design to animate the background of
wait boolean optional
Hold the call until the clip has settled (about 40 seconds) instead of returning as soon as the work is claimed
Returns sessionId conceptId outcome pending
set_animated_background
4 params
Record whether this design should use its animated background or stay static. Choosing animated requires that the design actually has a clip — prepare_animated_background makes one, and many designs are deliberately not eligible. The answer survives a reload. Note: builds are static for now — the design journey no longer offers animation and the built popup does not carry the clip; the recorded answer is kept for a later campaign-page feature.
sessionId string required
The design thread the concept belongs to
conceptId string required
The design being answered for
choice enum required
static animated
animated = use the generated clip as the background · static = keep the still plate
version number optional
The mockup version this answer is about. Omit unless you are tracking versions; a mismatch is refused rather than stored against the wrong picture.
Returns sessionId conceptId choice
set_coupon
9 params
Settle the coupon on a build AFTER the merchant agreed to it: writes the spec, rewrites the fixed code in the popup, and records the agreement on the design thread. Propose the coupon in the conversation first — this tool is the approval, not the proposal.
runId string required
The build's runId
type enum required
fixed unique shopify_automatic
fixed = one code everyone sees (needs fixedCode) · unique = codes from the campaign's uploaded pool · shopify_automatic = Shopify generates a code per visitor (needs automatic)
fallbackAction enum optional
hide text
unique/shopify_automatic: what to do when no code is available. Default hide.
fallbackCoupon string optional
Text shown when fallbackAction is text
autoRedeem boolean optional
Shopify shops: apply the code at checkout automatically
automatic object optional
Required for shopify_automatic
fixedCode string optional
The code to show, for type=fixed. Required unless the popup already carries one.
couponIndex number optional
Write into ONE coupon slot (index into get_coupon's codes). Omit to set every slot.
fixedCodeChanges array optional
Write several coupon slots at once: one {couponIndex, code} per slot. Use instead of fixedCode/couponIndex, never alongside them.
Returns runId ok draft summary codes omPublished omPublishError contractIssues savedCodes
get_job
1 param
Read the status of a long-running job by its jobId — a build, or a queued design-thread change. terminal tells you whether anything further will happen on its own. A build job in status selected is a design that was picked but never built: nothing is running, and select_variant starts the build. Prefer watch_job while you are waiting; use this for a single read or when the client cannot hold a request open.
jobId string required
The jobId from a command that started long work (or a bare runId from build_popup)
Returns jobId kind status terminal sourceStatus error runId threadId hasHtml result
watch_job
2 params
Wait for a long-running job to finish instead of polling. Emits progress notifications while it runs (when your client sends a progressToken) and returns the final status. Returns immediately if the job is already finished. On timeout it returns timedOut with the status so far — call again to keep waiting. Without a progressToken the call is silent until it returns, so keep timeoutSeconds under your client's idle timeout for tool calls (often 300 s); the default already is.
jobId string required
The jobId from a command that started long work (or a bare runId from build_popup)
timeoutSeconds number optional
How long to wait before giving up and reporting the status so far (default 240, max 900).
Returns jobId kind status terminal sourceStatus error runId threadId hasHtml result timedOut
set_plan_coupon
7 params
Settle the coupon on the PLAN, before any popup has been built — the coupon step of the campaign-creation flow. Use this while the merchant is still choosing a design; once a popup exists, set_coupon writes to the build itself. Propose the coupon in the conversation first: this tool records the agreement, it is not the proposal.
sessionId string required
The design thread whose plan the coupon belongs to
type enum required
fixed unique shopify_automatic
fixed = one code everyone sees (needs fixedCode) · unique = codes from the campaign's uploaded pool · shopify_automatic = Shopify generates a code per visitor (needs automatic)
fallbackAction enum optional
hide text
unique/shopify_automatic: what to do when no code is available. Default hide.
fallbackCoupon string optional
Text shown when fallbackAction is text
autoRedeem boolean optional
Shopify shops: apply the code at checkout automatically
automatic object optional
Required for shopify_automatic
fixedCode string optional
The code to show, for type=fixed
Returns sessionId coupon fixedCode agreedBy at
regenerate_animated_background
2 params
Change how a built popup's animated background MOVES ("slower", "make the steam drift left", "stop the water moving"). Needs a built popup that already HAS an animated background — it regenerates the clip, it cannot add one. Takes about a minute: answers at once with a jobId, watch it with watch_job and read result.body for the new clip's url and motion. The new clip is a draft until it is saved.
runId string required
The build (run) id whose animated background to regenerate
instruction string required
What should move differently, in plain words
Returns runId jobId
patch_popup
12 params
Edit a built popup by describing the change in words ("make the headline bigger", "swap the button colour"). Answers at once with a jobId; watch it with watch_job, then read the edited html from the finished job's result (result.body.html). Omit html to edit the popup's current document. Use edit_popup instead for a conversational redesign through the design thread.
viewport enum required
desktop mobile
Which document to edit: desktop or mobile
html string optional
The document to edit. Omit to edit the run's current html for the viewport
instruction string required
What to change, in plain words
selectedIds array optional
Optional data-v3id handles that scope the edit to particular elements
overlaySelected boolean optional
True when the caller selected the campaign's overlay/backdrop rather than an element
mode enum optional
fast full
fast (default) for a surgical patch, full for a rebuild of the document
omStep number optional
For multi-page popups: the 1-based page the instruction refers to
history array optional
Recent user/agent exchanges about this popup, oldest first, so a follow-up resolves
skipSettingsGate boolean optional
Skip the campaign-settings intent check (for re-sends of an instruction already vetted)
measuredFeedback string optional
What a previous attempt measured against the ask, for a second try at a size
runId string required
The build (run) id whose popup to edit
requestId string optional
Optional idempotency key: the same key on the same run returns the same job
Returns runId jobId replayed
send_design_message
7 params
Send a message to a design thread. While the thread is still scoping it ANSWERS the agent's discovery question; once cards exist it refines the concept board; after select_variant it edits the picked popup. Set newVariant to start another concept round instead; newVariantFrom can optionally anchor it to a picked run. Otherwise the server routes by thread state. Then wait with watch_design_thread when the message landed on the board (routedTo: board) or with watch_job on the returned jobId when it landed on a run — never sleep or poll get_design_thread between calls. (Picking a variant is not done by message — use select_variant.)
sessionId string required
Design session id
message string required
What to change, in plain language
imageUrls array optional
Optional reference images for this message (public urls or app-relative refs), up to 8
viewport enum optional
desktop mobile
Which viewport the change is about, once a variant is picked
answers object optional
Optional structured answers to a clarify card: question id (from the agent_message questions payload in get_design_thread) → the chosen answer. Prose in `message` alone is read too, but only when it names one of the offered options exactly; anything else leaves the card unanswered.
newVariant boolean optional
Start a new concept round instead of editing the picked popup
newVariantFrom string optional
Optional picked run to use as the new variant's anchor
Returns sessionId jobId routedTo runId state
restore_revision
3 params
Restore an earlier version of the popup in a design thread. Name the version by revisionId, or ask for stepsBack (1 = the previous version). The restore runs as a queued design change and answers with a jobId to watch; the live campaign is not changed until you publish again.
sessionId string required
The design thread id
revisionId string optional
A revision id from an earlier edit_applied event or a version listing
stepsBack number optional
How many versions to go back from the current one; 1 = the previous version
Returns sessionId runId jobId targetRevisionId targetRevisionNumber
select_variant
3 params
Pick one or more concept cards and BUILD them into popups — the agent's Build it. This is THE decision that narrows the thread: afterwards send_design_message edits the picked popup instead of the board. The build starts in the background and the draft campaign is created right away: watch the returned jobId with watch_job, then agree targeting with get_campaign_settings / set_campaign_settings and publish with publish_campaign. This call answers within about 40 seconds even when the build is still starting up — `pending: true` with a null campaignId means exactly that, so watch the jobId and read the campaign from get_design_thread shortly after; never re-pick because a call felt slow, and if one ever does time out, repeat it with the same ids rather than picking again, since a repeat returns the same runs and never builds twice. Pass several ids for an A/B pair — always the FULL selection in the same order, since a call that adds to an earlier pick re-adopts the cards it repeats rather than reusing their runs.
sessionId string required
Design session id
conceptIds array required
The full selection of concept card ids from get_design_thread; more than one starts an A/B
domain string optional
Only after a domain_not_on_account refusal: the merchant's own domain to file the campaign under, from the list that refusal named
Returns sessionId runId runIds campaignId jobId pending state next
watch_design_thread
2 params
Wait for a design thread to need you instead of polling: returns when the agent asks a discovery question, when the concept cards and their mockups are all ready, when the thread ends, or on timeout (then call again). Returns immediately if one of those already holds. Never sleep or poll get_design_thread between calls.
sessionId string required
Design session id, from start_design_thread
timeoutSeconds number optional
How long to wait before returning with reason "timeout" (default 240, max 900).
Returns sessionId status state reason question concepts timedOut next