MCP server

MCP server for RetaFunnel: the tools an AI agent uses to connect a landing page, VSL or quiz to RetaFunnel (create the site and funnel, instrument the HTML, verify every event in test mode, create retargeting segments) and to read analytics afterwards. The same tool definitions are served over Streamable HTTP by the edge Worker at https://mcp.retafunnel.com/mcp and over stdio by the retafunnel-mcp binary in this package.

• 51 tools (CONTRACTS §6 and §14): setup (ensure_site, instrument_html, validate_html, …), testing (set_test_mode, get_test_plan, simulate_session, verify_test_session, …), analytics (get_overview, run_readonly_sql, create_segment, …), launch (list_funnel_templates, create_funnel_from_template, get_launch_checklist, launch_funnel, get_ad_url_templates, sync_ad_entities) and growth (get_ads_report, get_page_report, compare, get_sales_report, list_annotations, add_annotation, list_experiments, create_experiment, get_experiment_report, list_persons, import_outcomes_csv). ensure_funnel accepts a template.
• 6 resources: onboarding://start, testing://guide, docs://instrumentation, docs://segments, docs://schema, docs://sales-matching.
• Typed REST client (createClient) with injectable fetch, usable from Cloudflare Workers.
• Connect-page renderers (renderConnectPage, renderConnectJson) for https://mcp.retafunnel.com/connect/<token>.

Using the hosted server (recommended)#

Get an AI setup link from the dashboard (Integrations → AI setup link). The link page shows the commands below with your token filled in.

Claude Code

claude mcp add --transport http retafunnel https://mcp.retafunnel.com/mcp --header "Authorization: Bearer <token>"

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "retafunnel": {
      "url": "https://mcp.retafunnel.com/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Then tell the agent: "Integrate RetaFunnel on this page using https://mcp.retafunnel.com/connect/". It reads onboarding://start and follows the procedure.

The agent's loop (iteration 2)#

1. Template first. list_funnel_templates → create_funnel_from_template(site_id, template, base_url) (or ensure_funnel(site_id, name, template)) creates the funnel in draft, its default retargeting segments and the recommended page sequence with page types and test hints.
2. Build, instrument, test as before (instrument_html, validate_html, register_page, set_test_mode, verify_test_session).
3. Checklist and launch. get_launch_checklist(funnel_id) returns the shared Checklist (tracker receiving, pages registered and valid, passing test session, every step reached, test mode off; warnings for Meta, segment sync, outcome source) with a fix per failing item; launch_funnel(funnel_id) sets it live and writes a campaign annotation. force: true only when the user accepts the failing items.
4. Afterwards. add_annotation(kind: "page_change") on every change; create_experiment + get_experiment_report (uplift and two-proportion z-test p-value after 100 sessions per variant); get_ads_report by campaign / ad set / ad with names, spend, CPL and ROAS (get_ad_url_templates for the URL parameters to paste, sync_ad_entities to resolve names); compare two funnels or pages; get_page_report for the 5% scroll heatmap; get_sales_report with first / last / linear attribution and import_outcomes_csv for offline sales (read docs://sales-matching).

Every report tool accepts compare: true (previous period of the same length + deltas), variant and the include_test / test_only switches (demo data is test data).

Local stdio wrapper (Claude Desktop and stdio-only clients)#

The wrapper talks to the REST API with your token; nothing runs locally except the MCP protocol.

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

Add this to claude_desktop_config.json (Claude Desktop → Settings → Developer → Edit Config) and restart Claude Desktop. Node 20+ is required.

Flags override the environment: retafunnel-mcp --token <token> --api https://api.retafunnel.com.

Programmatic use (edge Worker)#

import { createClient, createRetaFunnelMcpServer } from '@retafunnel/mcp'

const client = createClient({
  baseUrl: 'https://api.retafunnel.com',
  token,
  fetch: (req) => app.fetch(req, env, ctx), // call the Hono routes in-process
})
const server = createRetaFunnelMcpServer({
  client,
  baseUrls: { app: 'https://app.retafunnel.com', api: 'https://api.retafunnel.com', mcp: 'https://mcp.retafunnel.com' },
})
// connect `server` to a Streamable HTTP transport

RetaFunnelClient is an interface: the Worker may also implement it directly against the database.

The connect page:

import { renderConnectPage, renderConnectJson } from '@retafunnel/mcp'
renderConnectPage({ token, mcpUrl, apiUrl, appUrl, workspaceName, scopes: ['setup', 'read'], expiresAt })
renderConnectJson({ ... }) // for Accept: application/json

Development#

pnpm --filter @retafunnel/mcp build typecheck test

Tests run the server end to end through the SDK's in-memory transport against a fake of the REST API (test/fake-api.ts), so no Worker is needed.