Docs Guides

Set up with an AI agent

Create a setup link, paste one line to Claude Code or Cursor, read the test report, launch.

If an AI agent writes or edits your pages (Claude Code, Claude Desktop, Cursor, or any tool that supports MCP), you do not need to install or configure anything by hand: you create one setup link in RetaFunnel, paste one line to the agent, and it does the whole job: creates the site and the funnel, adds the tracking attributes to your HTML, runs a test session, checks every event arrived, creates the default retargeting segments, runs the launch checklist and reports back. This guide shows how to create the link, what the agent does, how to read its report, and why none of this can touch your live data.

One word to know: MCP (Model Context Protocol) is the standard way an AI agent connects to an outside tool. RetaFunnel exposes an MCP server at https://mcp.retafunnel.com; the setup link gives the agent the address and a key to use it.

Step 1: create the setup link#

RetaFunnel → Integrations → card AI setup link → Create link.
Name: who or what will use it, for example Claude Code – spring launch.
Scopes (what the link allows):
- setup: create sites and funnels, register pages, switch test mode on and off, simulate sessions. Needed for onboarding.
- read: read reports, sessions, the data dictionary. Needed for the agent to verify its work and to answer questions about your data later.
- write: create segments, record outcomes, switch on Meta and Google syncs. Add it if you want the agent to create the retargeting segments and turn their syncs on; otherwise it only proposes them. The default setup + read is enough to onboard a funnel.
Expiry: 30 days by default; 90 days, 1 year or never. A link for a one-off setup can be short; a link an agent uses weekly for reporting can be longer.
Click Create link. The next screen is shown once: the Connect URL, the one-line prompt and the Claude Code command. Copy what you need now.

The link is a scoped key for this workspace only: an agent working on Brand X cannot see or touch Brand Y. Every call the agent makes is logged with the link's name, the tool used and the rows affected.

Revoking. On the same card the table lists every link with its scopes, expiry and status. Click Revoke when the work is done; the agent loses access immediately. Create a new one next time.

Step 2: paste the one-line prompt#

Open your agent in the folder that contains the page files and paste the prompt exactly as shown on the card:

Integrate RetaFunnel analytics on this page: https://mcp.retafunnel.com/connect/rfk_…  (workspace: Your Brand)

Add anything useful after it: which file is the page, the page type (landing, VSL, quiz, opt-in, lead form, checkout, thank-you), the public URL, and whether you want the retargeting segments synced to Meta. For example:

Integrate RetaFunnel analytics on this page: https://mcp.retafunnel.com/connect/rfk_…  (workspace: Acme Coaching)
The page is index.html (a VSL with a Calendly booking under the video), live at https://www.acme.com/apply.
Create the VSL funnel from the template and turn on Meta sync for the default segments.

The agent opens the connect URL, which explains the whole procedure to it, adds the RetaFunnel MCP server to its configuration and starts. If it does not do that by itself, give it the Claude Code command from Step 3.

Step 3: connecting the agent manually (Claude Code, Claude Desktop, Cursor)#

Claude Code (one command, shown on the card with your key filled in):

claude mcp add --transport http retafunnel https://mcp.retafunnel.com/mcp --header "Authorization: Bearer rfk_…"

Cursor: create or edit .cursor/mcp.json in the project:

{
  "mcpServers": {
    "retafunnel": {
      "url": "https://mcp.retafunnel.com/mcp",
      "headers": { "Authorization": "Bearer rfk_…" }
    }
  }
}

Claude Desktop (and other tools that only speak the local "stdio" protocol): Claude Desktop → Settings → Developer → Edit Config, add the block below to claude_desktop_config.json, save and restart Claude Desktop. It needs Node 20 or newer installed on your computer; nothing runs locally except the connector itself.

{
  "mcpServers": {
    "retafunnel": {
      "command": "npx",
      "args": ["-y", "@retafunnel/mcp"],
      "env": {
        "RETAFUNNEL_TOKEN": "rfk_…",
        "RETAFUNNEL_API_URL": "https://api.retafunnel.com"
      }
    }
  }
}

Then tell the agent: "Integrate RetaFunnel on this page using https://mcp.retafunnel.com/connect/rfk_…". Reference for developers: MCP server.

What the agent does#

In order, using RetaFunnel's tools (their names in brackets, so you recognise them in the agent's output):

Reads the onboarding instructions (onboarding://start) and the guide for your page type (get_onboarding_guide).
Finds or creates the site for your domain and gets the script tag (ensure_site).
Creates the funnel from the matching template, with its steps and default segments (create_funnel_from_template or ensure_funnel).
Edits your HTML (instrument_html): inserts the script tag, names every button (data-track="cta_hero"), every form (data-track-form="optin_main"), the video (data-video-id="vsl_main"), quiz steps, key sections, the hidden rf_* fields for sales matching, and the Stripe hook if it finds a checkout button. It shows you a change log. Then it checks the result (validate_html) until clean and registers the page (register_page).
After you deploy, switches the site into test mode for 30 minutes (set_test_mode), fetches the test plan (get_test_plan: every event the page should produce) and walks the page with its browser, or, when it has no browser, pushes a realistic simulated session through the pipeline (simulate_session) and says so.
Verifies (verify_test_session): for every expected event, received / missing / malformed, plus the facts computed for the session. Fixes the HTML and repeats until everything is green.
Creates the default segments (create_default_segments) and, with the write scope, turns on their sync (enable_sync). Optionally tests the sales path with a fake outcome (simulate_outcome) and shows what a sync would send without sending it (check_sync_dry_run).
Turns test mode off, runs the launch checklist (get_launch_checklist) and, when nothing required fails, launches the funnel (launch_funnel). It should ask you before launching; if it launched and you were not ready, pause the funnel on its page.
Reports back.

Everything the agent creates is ordinary data you can see and edit in the dashboard: the site under Sites, the funnel under Funnels, the segments under Segments.

How to read the agent's report#

A good report follows this shape:

Site: Acme Coaching (sk_…)   Page: https://www.acme.com/apply   Mode: browser
Expected 19 events · received 18 · missing 1 · malformed 0 → FAIL
Missing: click cta_footer (the footer button had no data-track) …
Fixes applied: added data-track="cta_footer"; re-deployed; re-tested → PASS
Facts: scroll 100%, video 75%, quiz –, lead yes
Funnels: "VSL funnel" reached step 6/8 (lead)
Test mode: disabled · test data: kept
Checklist: ready

Line by line:

Mode: browser means the agent really opened your page and clicked through it; simulation (scenario) means it only pushed synthetic data through RetaFunnel's pipeline. A simulation proves the connection works, not that your page is instrumented correctly, so ask for a browser run (or do the test visit yourself: Getting started, step 4) before launch.
Expected / received / missing / malformed: the heart of the report. missing events are elements the page does not track yet (usually a missing attribute). malformed means an event arrived with wrong data (for example a quiz step that is not a number). PASS only when both are zero.
Facts: what RetaFunnel computed for the test session. Scroll 100% means it reached the bottom; video 75% that it played past three quarters; "lead yes" that the form produced a lead. If a fact disagrees with what the agent did, something is off.
Funnels: how far the test session got in each funnel. It should reach the last step of what the agent could do (a real purchase cannot be made in a test, so purchase steps stay unreached; that is expected).
Test mode / test data: test mode must be disabled at the end, otherwise your real visitors are stored as test data. Test data can be kept (it is deleted after 7 days) or purged.
Checklist: ready or the list of failing required items.

Ask the agent to fix anything in Missing and run again. Do not accept "launched with force" unless you understand which check failed.

The launch checklist#

The agent runs the same checklist you see on the funnel page. Required items: tracker receiving live events, every URL step registered as a page, pages valid (no leftover data-test), a passing test session in the last 7 days, every step reached by a test session, steps defined, test mode off. Warnings: Meta connected, at least one segment syncing, an outcome source (Stripe, Calendly, CSV or webhook). The agent cannot do two of the warnings for you: pasting the Meta token (Connect Meta) and connecting Stripe or Calendly (Sales, CRM and attribution) need your accounts; it will tell you so.

Test mode: why nothing leaks into live data#

Everything the agent does to test is flagged as test at the moment it enters RetaFunnel, and that flag can never be removed afterwards:

A session is a test session when the page was opened with ?_rf_test=1, when the script tag has data-test="true" (staging), when the page called rf.testMode(true), when the site is in site-level test mode (what the agent switches on), or when it was created by a simulation.
Test rows are excluded from every report, every segment, every daily total and every Meta or Google sync. The Show test data switch at the top of the dashboard is the only way to see them.
Test outcomes (fake purchases with a …@retafunnel.test email) never reach Stripe matching, Meta or Google.
Test data older than 7 days is deleted automatically; Sites → Test mode → Purge test data deletes it now.
The one thing to check after an agent finishes: that site-level test mode is off (the funnel page's checklist and the banner at the top of the dashboard both show it). While it is on, real visitors are stored as test data too.

After the launch#

Keep the link (or create a read-only one) and ask the agent questions in plain language: "which campaign has the best lead rate this month?", "compare the old and the new VSL page", "show the retention curve of variant B", "import this CSV of sales". The same server answers with the reports you see in the dashboard. Ask it to add an annotation whenever it changes a page, so the charts explain themselves later.

Common problems#

The agent says it cannot connect / 401. The link expired or was revoked, or the key was pasted incomplete. Create a new link.

The agent says "insufficient scope". It tried to create a segment or switch on a sync with a link that has no write scope. Create a link with write, or do that step in the dashboard.

Everything is "missing" except pageview. The agent instrumented the file but the deployed page is the old one, or the script tag's data-site key belongs to another site. Deploy, then ask it to re-run the verification.

The report says PASS but the Install health shows no events. Install health counts live events only; the agent's events were test events. Open the page normally once, or wait for real visitors.

My page builder does not let the agent edit HTML. Give the agent the exported HTML or ask it for the list of attributes to add, then add them in the builder's settings for each element (most builders have an "attributes" box per element). The Instrumentation guide is the reference.

Last updated 7 November 2026