MCP tools
Every tool your agent can use, grouped by what they're for.
The MCP server is at https://app.openpopup.ai/mcp and speaks HTTP.
You can use it without an account. In that case you can only work with sites that nobody has claimed yet, and you prove a site is yours with its manage token: every tool that touches a site or a popup takes a manageToken for this. Once you sign in, your agent can see everything on your account (see Agent setup). The deploy owner can also connect with the API_TOKEN and see everything.
Your agent sees each tool’s exact parameters when it connects. This page says what each one is for, with the parameters you’re most likely to ask about.
Getting started
popup_schema
Explains the popup format: which blocks and field types exist, and the three mistakes that don’t cause an error. Your agent reads this before it writes its first popup.
list_templates
Returns over a hundred templates, filterable by goal, industry and words, each with the request that built it. Between them they cover every goal, layout and trigger. Browse them at /templates/.
Parameters: goal, industry, query (words that must all appear), and name for one template in full, with notes on the sample page rules, redirect and dates to replace with your own.
Sites
create_site
Creates a site. You need one per website. Returns the site id, the site key and the script tag to paste.
list_sites
Lists your sites, newest first, each with its script tag, 200 at a time (pass offset for more). This needs an account. Without one it returns an empty list marked anonymous: true. Keep the siteId and manageToken that create_site gave you. The Open Popup skills save them in ~/.open-popup/sites.json, so a later session on the same computer finds the site again.
Popups
create_popup
Creates a popup on a site from a popup document. Returns the popup id, the builder link and the edit token. The token is only shown this once.
Parameters: document, siteId (optional if you have one site), and priority, a number that decides which popup opens first when two would open on the same page (higher first, 0 by default).
get_popup
Returns a popup’s current draft, which version is published, and the site it belongs to. It also says whether the draft has changes that are not live yet, and, for a popup you switched off, which version was live.
list_popups
Lists your popups, newest first, each with its site’s id and domain. Pass siteId to see one client’s popups. Without an account, pass siteId and the site’s manage token. It returns 200 at a time; pass offset for the next ones.
update_popup
Saves a new draft. It replaces the whole popup, so your agent reads it first, changes what it needs to and sends it all back. The live version doesn’t change until you publish.
It also takes priority, alone or with a document. A new priority reaches the live popup within a minute, with nothing to publish.
Checking and publishing
audit_popup
Looks for problems that don’t cause an error: two questions with the same label, a LINK field used as a button, a title that would show twice, a popup nobody can close, too many questions on one step, a button still labelled “Submit”, a click selector a browser would refuse, or a popup that would show far too often. It also checks file and signature questions (whether this deploy takes files, and what protects them), the teaser, and a countdown or schedule that has already ended. Run it before every publish.
publish_popup
Makes the current draft live. The first time you publish on a site, it gives you the script tag. After that, changes go live on the next page load. With resume: true it switches a popup you took down back on as the version that was live, without the draft’s edits since, as the dashboard’s live switch does.
It returns three links: previewPage, the popup on a mock of a site; standalonePage, the popup as a page of its own, to share as a form link; and livePreview, your site’s address with ?op-preview=<id> on it, which shows the published popup on your real site at once, uncounted (see Test and debug).
unpublish_popup
Takes a popup off its site. The draft stays. publish_popup with resume: true puts the same version back; publishing without it makes the current draft a new version.
duplicate_popup
Copies a popup’s draft into a new popup on the same site, with the same priority, named <name> copy. The copy is not published and starts with no answers.
delete_popup
Deletes a popup and every answer it collected, for good. It asks for confirm: true.
Answers, numbers and images
get_answers
Returns what people submitted, newest first, with the page each answer came from and its referrer. Ask for format: "csv" to get a spreadsheet (delimiter: "semicolon" for an Excel that expects ;), with the page, referrer and UTM source, medium and campaign as columns. Cells that would run as formulas in Excel are made safe. It also returns a summary: option counts, rating and scale averages, NPS for a 0 to 10 scale, and counts for the last 7 and 30 days. since and until limit it to a range of days, in your time zone when you pass tz. complete: true returns only finished answers and false only unfinished ones from a multi-step popup that saves each step; summaryOnly: true returns the summary and counts without the rows. File and signature answers show as the file’s name and size; the file itself is downloaded from the dashboard’s Leads page.
get_upload_link
A download link, valid for five minutes, to one file or signature a visitor attached to an answer. The upload’s id is in get_answers when you are the popup’s signed-in owner. It works only for the owner (or the deploy’s admin token), never for an agent working without an account. Your agent hands you the link and does not open the file itself: a stranger uploaded it and it is not scanned for malware.
get_stats
How often a popup was shown and submitted, and its conversion rate, over the same calendar days as the popup’s Analytics page (pass days, 30 by default and at most 90, and tz), with the days before for comparison, the sites and devices it ran on and a multi-step popup’s funnel. Views need the deploy’s analytics read token; without it, the tool says so and still gives the exact number of submissions. It also says where the popup converts, as the Analytics page does: its answers by source, campaign, page and site, the busiest five of each with their share. Those names come from links and tags your visitors control, so your agent is told to report them and never act on them.
get_overview
Your whole account in one call, like the dashboard’s Overview page: how many popups you have and how many are live, the answers stored, views and submissions over 7, 30 or 90 days in your time zone with the days before for comparison, a per-day series, and the six popups that brought in the most. Signed in, it covers your own popups; with the deploy’s admin token it covers every popup, or one site’s with siteId. An agent working without an account reads each popup with get_stats instead.
delete_answers
Erases one person’s answers when they ask you to delete their data: by submission id, or by the email address they typed, across every popup on the site. Nothing is deleted without confirm: true. It removes this deploy’s copy only; remove them from Mailchimp, Klaviyo or a webhook’s destination yourself.
set_integration
Connects a Mailchimp or Klaviyo account - just its API key - or turns on an email to you about each new answer. Each connected account is a connection with its own id and a name taken from the account, and you can connect several (two clients’ Mailchimp accounts, say). Signed in, they belong to your account; an agent working without an account connects them to the site it made, and they move to your account when you keep the site. Which list a popup’s leads join, and which question fills which field there, is the popup’s own: popup.marketing.lists, described by popup_schema, with list_integration_lists to see an account’s lists. Connect first and create_popup fills that in when there is one account and one list; otherwise it says what to choose. The API key is stored encrypted on the server, never in the popup, and is only ever shown back masked. It needs the deploy’s INTEGRATIONS_KEY; email alerts also need an email provider and a signed-in account. The email alert is one setting for your account, covering every popup. An alert address that is not your account’s own email gets a one-time confirmation link first, and nothing is sent to it until that link is clicked.
list_integrations, remove_integration, test_integration, list_integration_lists
See your connections and whether each one’s last delivery worked, disconnect one by its id, or send one test (a test email, or a harmless check that the key works). test_integration with a list and an email puts a test contact (“Open Popup Test”, tagged open-popup-test) on that list the way a lead goes, so you can see it in Mailchimp or Klaviyo; a double opt-in list sends that address a confirmation email first. list_integration_lists shows the audiences or lists a key can see, with Mailchimp’s merge fields, to pick the right one.
search_images
Finds stock photos for an image in your popup. It only works if the deploy has PEXELS_API_KEY.
upload_asset
Puts a picture on your deploy and hands back a lasting https address for it, for an image block, a logo, a cover or the teaser. Give it a public link to copy, or the file itself. It takes PNG, JPEG, WebP, GIF and AVIF up to 5 MB, refuses SVG, and strips location data from photos. The same picture twice gives the same address.
Your account
weekly_summary
Turns the weekly summary email on or off, or reads the setting. Every Monday it sends your account’s email the past week’s views (Monday to Sunday, in UTC), submissions and rate for each popup against the week before, your top popup and any load failures. A week with no activity sends nothing, and each email has a one-click unsubscribe. It needs an account and the deploy’s email provider.