Apex MCP tool reference

The MCP server exposes Apex build, analysis, backlog, configuration, landing page, and preview tools over stdio and the hosted connector. Each tool calls the Apex public API with the configured API key and returns text content to the MCP client. Failed API calls return an error text block and mark the tool result as an error.

Earlier parameter names (id_or_slug, experiment_id_or_slug, id) are still accepted.

Experiment launch is dashboard-only. The MCP server does not expose a start_experiment tool, so approval and readiness gates remain visible during launch.

Experiment tools

Tool	Purpose	Inputs	Output
list_experiments	List experiments, optionally filtered by status.	status: optional draft, running, paused, or completed; limit: optional number from 1 to 100.	Markdown list of experiments with name, ID, slug, status, traffic allocation, store URL, creation date, and variations. Adds "More results available" when the API page has more rows.
get_experiment	Fetch one experiment by UUID or slug.	experiment_id: experiment UUID or slug.	Markdown experiment summary with the same formatted fields as list_experiments.
get_results	Read a compact results summary without filling the chat context with the raw results payload.	experiment_id: experiment UUID or slug.	Experiment, run window, primary goal, per-variation visitors, conversions, rate, lift, confidence or probability, and verdict. The output is capped at 4,000 characters and names unavailable metrics when analytics are degraded.
create_experiment	Create a draft A/B test.	name: required string; slug: optional string; description: optional string; traffic_allocation: optional percentage from 0 to 100, defaulting to 100.	Markdown confirmation with the created experiment summary.
pause_experiment	Pause a running experiment.	experiment_id: experiment UUID.	Text confirmation that the named experiment is now paused.
complete_experiment	Complete or stop an experiment.	experiment_id: experiment UUID.	Text confirmation that the named experiment is now completed.

Variation build tools

Tool	Purpose	Inputs	Output
list_variation_files	List files in a variation workspace.	experiment_id: experiment UUID or slug; variation_id: variation UUID, public ID, slug, or a name unique within the experiment.	JSON file list with path, kind, contentType, sha256, sizeBytes, updatedAt and readonly. The canonical editable files are src/index.js and src/index.scss.
read_variation_file	Read one workspace file.	experiment_id; variation_id; path: relative workspace path.	JSON file record with those metadata fields and the requested content. Absolute paths and paths containing empty, . or .. segments are rejected.
write_variation_file	Replace one workspace file.	experiment_id; variation_id; path; content: complete file content; optional expected_version: the file's sha256 from read_variation_file.	JSON ok/changed result and file metadata without echoed content or revision IDs, or a conflict error when the file changed since it was read. Run build_variation before previewing the change.
build_variation	Compile the variation workspace after edits.	experiment_id; variation_id.	Build status, or build error lines when compilation fails.

Write a checkout message with write_variation_file to src/mutations.json as [{ "action": "checkoutBlock", "checkoutBlock": { "heading": "Free returns for 30 days" } }]; each message arm's QA checkout and launch happen in the dashboard.

Landing page tools

These tools mirror apex landing-pages for pages built outside Apex. Files travel inline as { path, content, encoding }, with encoding utf8 (default) or base64. See Build landing pages with your own tools.

Tool	Purpose	Inputs	Output
create_landing_page	Create a landing page to build outside Apex.	name: required; slug, idea_key: optional.	JSON page record.
pull_landing_page	Read the page checkout.	id: landing page id; paths: optional list of at most 32 file paths to read.	JSON manifest, file list with sha256, and context; with paths, those files' contents.
plan_landing_page	Show what an apply would change, without writing.	id; manifest: the apex-landing-page.json object; files: every page file.	JSON plan: added, changed and removed files, manifest and goal changes, deploy target.
apply_landing_page	Apply files and manifest as a new current version.	id; manifest; files; optional base_version_id from pull_landing_page, so a concurrent change is refused.	JSON version number, version id, signed preview URL and goal changes. Only files the plan names are uploaded.
preview_landing_page	Get a signed preview URL (24 hours).	id; optional version number.	JSON preview URL and expiry.
deploy_landing_page	Deploy a version live.	id; optional version_id (default: current), host (a domain the shop holds; default: the manifest host, else <shop>.apex-page.com), path.	JSON live URL, host, path and version.
list_landing_page_versions	List versions, newest first.	id.	JSON versions with current and live flags.
rollback_landing_page	Deploy an older version to the page's current address.	id; version_number or version_id.	JSON live URL and version.
create_landing_page_experiment	Create a draft test that splits the page between two versions.	id; control and variant version numbers; optional name, primary_goal (a manifest goal key).	JSON draft experiment. Start it in the dashboard.
list_landing_page_domains	List the shop's landing-page domains.	Optional host.	JSON domains with mode, status and DNS target.
claim_landing_page_domain	Claim a client hostname for landing pages.	host.	JSON domain with the CNAME record to add at the DNS provider.
register_landing_page_domain (local stdio only)	Register a new domain on the Drip Cloudflare account. Billable and non-refundable. Unavailable through the hosted connector.	name; optional years (1 to 10); confirm_price { amount, currency }.	Without confirm_price, an error carrying the price quote; with the quoted total, the registered domain.
check_landing_page_domain	Check one hostname against Cloudflare and DNS now.	host.	JSON domain status.
remove_landing_page_domain	Remove a landing-page domain from Apex. Refused while a published page serves it.	host.	JSON removed domain. A registered domain stays on the Drip account.

Idea tools

Tool	Purpose	Inputs	Output
create_idea	Create a backlog idea.	title: required; description, page_url, and hypothesis: optional strings.	Created idea ID and Apex backlog key.
list_ideas	List backlog ideas, optionally filtered by status.	status: optional; limit: optional 1–100; cursor: optional continuation token.	JSON page of the full backlog records returned by /api/v1/backlog (including scores, visual references, custom fields, linked experiments and decisions), with the owner's email removed, plus has_more/next_cursor pagination and the returned filters when present.
get_idea	Read one backlog idea.	idea: idea UUID or Apex backlog key.	The same full backlog record, with the owner's email removed.

Goal and brand tools

Tool	Purpose	Inputs	Output
list_goals	List conversion goals for the active shop behind the API key.	None.	Markdown bullet list with goal name, type, and ID, or "No goals found."
get_brand_context	Read the shop brand context before writing customer-facing copy.	None.	Pretty-printed JSON containing the brand context returned by /api/v1/brand-context unchanged (the route already excludes internal notes): hasProfile, mode, status, summary, voice, guardrails, proofRequirements, clientNotes, clientAssetExcerpts, guidelinesText and promptBlock where available.

Preview tools

Tool	Purpose	Inputs	Output
generate_preview_url	Build a forced QA URL for a variation on a store where the Apex SDK is installed.	experiment_id: required UUID or slug; store_url: optional absolute storefront URL override; variation_name: optional exact variation name.	Markdown block with experiment name, selected variation, and a URL containing drip_force, drip_experiment_id, drip_variation_id, drip_qa=1, and drip_debug=1.
create_preview_session	Create a proxy preview for a prospect or store without the Apex SDK.	experiment_id: experiment UUID or slug; variation_id: optional variation UUID, public ID, slug, or unique name; target_url: optional absolute storefront URL, defaults to the experiment's store URL; ttl_hours: optional integer from 1 to 168, default 168.	Proxy preview URL and expiry timestamp.

When variation_name is omitted, generate_preview_url selects the first non-control variation and falls back to the first variation. The experiment must have a store_url or the caller must pass store_url.

Shop setup

• create_shop creates a self-serve shop through Apex provisioning and binds the connector to it once. Pass name, domain, platform and optionally currency and origin. Requires shops:write. It calls shop creation directly, so a key with only shops:write can create a shop. A domain-binding conflict reuses an authorized, unarchived owner with the same normalized domain in your key organization. If binding fails after creation, it returns the shop id and asks you to retry with the same domain. A bound connector returns its existing shop instead of creating another. Output includes shop_id, domain, platform, message, and provisioning setup when known; unknown domain or platform is null. Existing-shop recovery without setup returns setup_status: "existing" and: "Existing shop reused; setup steps were not re-run. Call get_install_status for the current install state." Concurrent calls share provisioning only for the same credential, normalized domain and platform; a binding race returns the shop that won the binding.
• get_install_instructions returns plain installation steps and structured snippet fields. Shopify shops include the app connection link once public installation is confirmed; WooCommerce shops include plugin steps and a link to the installation token panel. Requires read access. A key without a bound shop can select its shop with X-Apex-Shop.
• assess_storefront takes url and optional shop_id, assesses the public storefront, and returns platform, consent, bot protection, CSP, testing tools, an installation kit and a forwardable Markdown guide. Read-only; loads the page and probes /cart.js.
• get_install_status checks the same installation telemetry as onboarding. It returns shop_id, overall (verified, partial, missing or unavailable), last_event_time (a timestamp or null), connected, receivingData, optional domains, and next_action. Unavailable telemetry is reported explicitly. The top-level status and last event fields use only overall and last_event_time.

These tools are shared by stdio and the remote connector. Shop-bound tools ask you to call create_shop when the remote connector has no shop. QA approval and launch stay in the Apex app.

Shopify instructions include shopify_oauth_url only when Apex operators have set SHOPIFY_PUBLIC_INSTALL_CONFIRMED=1 in Vercel after confirming public distribution in the Shopify Partner Dashboard. This variable defaults off. Until enabled, Shopify shops receive snippet instructions and “The Shopify app link follows once Apex enables it.”

Related pages

• Install and configure the Apex MCP server
• Experiment lifecycle commands
• Webhooks

Configuration and diagnostics

get_runtime_settings, set_data_layer_triggers and apply_integration_recipe return the complete public API response unchanged, including every runtime-settings field, version fields, precompile compile/publication outcomes and warnings when present.

set_data_layer_triggers accepts data_layer_triggers (up to 20 trigger objects) and optional expected_version: the ISO datetime version returned by get_runtime_settings, or null when no prior settings exist. It forwards that value as expectedVersion to the PATCH endpoint so concurrent edits return the API conflict error unchanged. Read the settings again before retrying a conflict.

discover_tracking_schema returns aggregate event/field types, timing, storage and trigger diagnoses with observation-window, consent and coverage fields; it does not return raw events.

build_variation returns the build result as the API reports it (status, build counts and byte sizes, attached goal IDs, metrics source, publication status, diagnostics and warnings when available); only stack and trace fields inside diagnostics are removed.

Live page inspection

These read-only tools load the selected shop's public page through Apex's Browserbase browser. They need no experiment, variation, or installed SDK. Use them before writing variation code; generate_preview_url and create_preview_session show an existing variation instead.

Tool	Inputs	Result
inspect_page	url, optional viewport (desktop or mobile)	Page map and section candidates
inspect_dom	url, selector or text, optional viewport	Matching elements and their computed styles
screenshot	url, optional viewport and CSS selector	PNG or JPEG image and a short text summary

Desktop uses 1280 × 900 and mobile uses 390 × 844. URLs must match the shop's domain, origin, or an experiment's store URL. Off-host redirects are refused. User keys need shops:read, an authorized selected shop, and experiment-read permission; shop keys need experiments:read.

Each tool call consumes one inspection from the shop's UTC-day allowance (default 10). inspect_page runs page map and sections in one browser session; inspect_dom runs DOM context and styles in one session. The 11th tool call is refused. Inspection shares the remote preview limit of two sessions per shop, with a 10-minute session TTL. The API returns a plain reason when the allowance is exhausted, inspection is disabled, or no usable browser result is available. Screenshots use image/png for selector captures and may use image/jpeg for full-page frame captures. They are limited to 3,500,000 characters including the data URL prefix. A failed browser attempt still consumes its inspection.

Launch stays in the app

Assistants can build, preview, and collect QA evidence. Approving QA and starting a test remain your clicks on the experiment page in Apex.

The launch-handoff widget declares an OpenAI widget CSP with no fetch domains and image resource domains limited to the app origin and, on the remote server, the configured Supabase screenshot storage origin.

run_qa

Capture screenshots for an experiment and attach them to its QA run. Pass experiment_id, optional devices (desktop, mobile, default both), and optional notes. A completed call returns status: "completed", the QA run ID, signed per-device screenshot URLs, evidence checksum, and changed readiness items. If capture outlasts the call, it returns status: "pending", screenshot_job_id, progress, and a retry delay without attaching evidence or writing notes. Call run_qa again with the same experiment_id and screenshot_job_id; the resume call ignores devices and finishes that existing job instead of starting another capture.

request_launch

Read an experiment's launch checklist without changing it. Pass experiment_id. Returns the remaining human steps, readiness items, latest QA screenshots, preview URL, and a link to open Apex to approve QA and launch. ChatGPT can display the shared launch-handoff widget.

lookup_commerce_catalog

Search active Shopify products with query, or retrieve one exact product with handle or product_id. Product lookup returns live base-currency prices, costs, and price-test exclusions. The tool is read-only and accepts optional cursor and search-only limit.