Copy as markdown[View .md](https://docs.funnelfizz.com/ai-agents/mcp "View the raw markdown for this page")[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fdocs.funnelfizz.com%2Fai-agents%2Fmcp.md%20and%20help%20me%20with%20this%20FunnelFizz%20topic%3A%20MCP "Open this page in Claude with context")[Open in ChatGPT](https://chat.openai.com/?q=Read%20https%3A%2F%2Fdocs.funnelfizz.com%2Fai-agents%2Fmcp.md%20and%20help%20me%20with%20this%20FunnelFizz%20topic%3A%20MCP "Open this page in ChatGPT with context")

# MCP

The FunnelFizz MCP server (`https://mcp.funnelfizz.com`) gives your agent **tools** instead of just docs. Your agent can do everything you can do in the dashboard — set up workspaces, build funnels, send emails, activate automations, manage teams and billing — through a single MCP connection.

## What it can do[​](#what-it-can-do "Direct link to What it can do")

**Workspace setup** (FREE+):

* Register tracking sites, install snippets, verify install.
* Register sender DOMAINS (DNS verification) and sender ADDRESSES (auto-trusted for workspace members; 6-digit code for outsiders).
* Validate Stripe restricted keys, OAuth into providers (X, YouTube, LinkedIn, Instagram, TikTok, Reddit, GSC, Google Ads).
* Register custom events.

**Funnel content & structure** (HOBBY+):

* Create funnels, splits (incl. nested + extension + nested-extension), and extension stages.
* Draft email campaigns and drip sequences; send live or schedule; A/B-test subject lines (PRO).
* Build automations with multi-step DAGs; activate, pause, resume.
* Update email templates, senders, brand library assets.
* Delete tracking sites, templates, senders, domains, integrations (with confirmation).

**Reads** (HOBBY+ for metrics, PRO for full profile data):

* Funnel overviews, metrics, conversion trends, retention, comparisons.
* Stage drilldowns: paths, sources, referrers, recent users (PRO), revenue, churn, mentions, ad/SEO performance.
* AI report generation + history.
* Email campaign analytics, automation runs, audit logs.

**Workspace administration** (ADMIN role only):

* Invite/remove team members, change roles.
* Cancel, resume, or change subscription plan; checkout via browser handoff.
* Create + revoke API keys.
* Transfer ownership, delete workspace.

## Safety tiers[​](#safety-tiers "Direct link to Safety tiers")

Every tool falls into one of three tiers:

| Tier             | What it covers                                                    | How it's gated                                                                                                                  |
| ---------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **T0 reads**     | All `list_*` / `get_*` / `*.drilldown` tools                      | Plan + scope. Hidden from `tools/list` if your key can't use it.                                                                |
| **T1 mutations** | Funnel structure, drafts, sends, activations, high-impact deletes | A short-lived `target_token` minted after the user explicitly confirms the target (a funnel, a template, a tracking site, etc.) |
| **T2 admin**     | Team, billing, API keys, workspace transfer/delete                | 6-digit code emailed to the API-key-holder. User pastes it back; agent gets an `admin_token` valid for 10 minutes.              |

See [Safety tiers](https://docs.funnelfizz.com/ai-agents/safety-tiers.md) for the full flow with examples.

## Connecting[​](#connecting "Direct link to Connecting")

### 1. Generate an API key[​](#1-generate-an-api-key "Direct link to 1. Generate an API key")

[Settings → Developer → New API key](https://funnelfizz.com/settings/developer). Name it after the agent ("Claude Desktop on my MacBook"). Pick scopes from the four available:

* **`setup`** — register tracking sites, email domains/senders, integrations, custom events. Available on FREE+.
* **`read`** — list and read every workspace resource. HOBBY+. PRO behaviors enforced inside the tool.
* **`write`** — create/edit funnels, send emails, activate automations, manage all non-admin resources. HOBBY+. Requires MANAGER role.
* **`admin`** — team, billing, API keys, workspace administration. Any plan; requires ADMIN role.

Keys are workspace-scoped, hashed at rest (SHA-256), revocable, and tied to a workspace member's role — if your role changes, your key's effective scopes change immediately.

### 2. Add to your agent's MCP config[​](#2-add-to-your-agents-mcp-config "Direct link to 2. Add to your agent's MCP config")

Most agents (Claude Desktop, Cursor, Windsurf, ChatGPT, Zed):

```
{

  "mcpServers": {

    "funnelfizz": {

      "type": "streamable-http",

      "url": "https://mcp.funnelfizz.com",

      "headers": { "Authorization": "Bearer ff_YOUR_KEY_HERE" }

    }

  }

}
```

Claude Code (commit a `.mcp.json` at the repo root, key from env):

```
{

  "mcpServers": {

    "funnelfizz": {

      "type": "http",

      "url": "https://mcp.funnelfizz.com",

      "headers": { "Authorization": "Bearer ${FUNNELFIZZ_API_KEY}" }

    }

  }

}
```

For agents with deep links: `claude://mcp/install?url=https://mcp.funnelfizz.com&name=funnelfizz&authType=bearer` (Claude Desktop) · `cursor://install-mcp?name=funnelfizz&url=https://mcp.funnelfizz.com` (Cursor) · `windsurf://install-mcp?name=funnelfizz&url=https://mcp.funnelfizz.com` (Windsurf).

## Tool taxonomy[​](#tool-taxonomy "Direct link to Tool taxonomy")

Tools are dot-prefixed by domain so you can scan one prefix at a time. Full per-tool reference at [Tool reference](https://docs.funnelfizz.com/ai-agents/tool-reference.md).

### Workspace[​](#workspace "Direct link to Workspace")

| Tool                                                                 | Tier       | What it does                                                |
| -------------------------------------------------------------------- | ---------- | ----------------------------------------------------------- |
| `workspace.get_setup_status`                                         | T0         | Workspace checklist; call first to decide setup next steps. |
| `workspace.get_overview`                                             | T0         | Cross-funnel rollup: counts, recent activity, top funnels.  |
| `workspace.get_brand` · `workspace.update_brand`                     | T0 / write | Brand colors, logo, name.                                   |
| `workspace.get_profile` · `workspace.update_profile`                 | T0 / write | Workspace name, timezone, defaults.                         |
| `workspace.complete_onboarding`                                      | write      | Mark onboarding done.                                       |
| `workspace.delete` · `workspace.transfer_ownership`                  | **T2**     | Destructive; require admin code-paste.                      |
| `workspace.custom_event.list` · `.register` · `.update` · `.archive` | T0 / write | Custom event registry.                                      |

### Team[​](#team "Direct link to Team")

| Tool                                                             | Tier   |
| ---------------------------------------------------------------- | ------ |
| `team.list_members` · `team.list_invites`                        | T0     |
| `team.invite_member` · `team.remove_member` · `team.change_role` | **T2** |

### Billing[​](#billing "Direct link to Billing")

| Tool                                                                                  | Tier            |
| ------------------------------------------------------------------------------------- | --------------- |
| `billing.list_plans` · `billing.get_subscription` · `billing.list_invoices`           | T0              |
| `billing.start_checkout` → `billing.poll_checkout`                                    | browser handoff |
| `billing.open_portal`                                                                 | browser handoff |
| `billing.cancel_subscription` · `billing.resume_subscription` · `billing.change_plan` | **T2**          |

See [Browser handoffs](https://docs.funnelfizz.com/ai-agents/browser-handoffs.md) for the checkout flow.

### API keys[​](#api-keys "Direct link to API keys")

| Tool                                    | Tier                                                  |
| --------------------------------------- | ----------------------------------------------------- |
| `api_key.list` · `api_key.get_activity` | T0                                                    |
| `api_key.create` · `api_key.revoke`     | **T2** (self-revoke allowed with `confirmSelf: true`) |

### Funnel structure & content[​](#funnel-structure--content "Direct link to Funnel structure & content")

| Tool                                                                                                                                                     | Tier                   |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `funnel.list` · `funnel.list_stages` · `funnel.list_tracks` · `funnel.get_overview` · `funnel.get_metrics` · `funnel.get_connections` · `funnel.compare` | T0                     |
| `funnel.resolve_by_name` · `funnel.confirm_target`                                                                                                       | mints T1 target\_token |
| `funnel.create` · `funnel.rename` · `funnel.archive`                                                                                                     | T1                     |
| `funnel.split.create` · `funnel.split.archive` · `funnel.split.recommend`                                                                                | T1                     |
| `funnel.extension.add`                                                                                                                                   | T1                     |
| `funnel.stage.link_provider` · `.unlink_provider` · `funnel.link_tracking_site` · `funnel.link_stripe`                                                   | T1                     |
| `funnel.replay_history`                                                                                                                                  | T1                     |
| `funnel.feature_flags.update`                                                                                                                            | write                  |

### Email[​](#email "Direct link to Email")

| Tool                                                                                                    | Tier                                        |
| ------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `email.draft.create` · `.update` · `.list` · `.archive` · `.send_test` · `.schedule` · `.create_drip`   | T1                                          |
| `email.draft.send_now`                                                                                  | T1                                          |
| `email.template.list` · `.create` · `.update` · `.preview`                                              | T0 / write                                  |
| `email.template.delete`                                                                                 | T1 entity-token (if linked to active sends) |
| `email.sender.add` · `.list` · `.update` · `.verify_with_code` · `.resend_confirmation` · `.get_status` | setup / write                               |
| `email.sender.delete` · `email.domain.delete`                                                           | T1 entity-token                             |
| `email.domain.add` · `.verify` · `.list`                                                                | setup                                       |
| `email.asset.request_upload_url` · `.list` · `.delete`                                                  | write                                       |
| `email.campaign.list` · `.get` · `.get_analytics` · `.list_recipients`                                  | T0                                          |

### Automation[​](#automation "Direct link to Automation")

| Tool                                                                            | Tier |
| ------------------------------------------------------------------------------- | ---- |
| `automation.draft.create` · `.list` · `.archive` · `.add_step` · `.remove_step` | T1   |
| `automation.activate` · `.pause` · `.resume`                                    | T1   |
| `automation.canvas.get` · `automation.list_runs` · `automation.get_stats`       | T0   |
| `automation.canvas.update`                                                      | T1   |

### Tracking & integrations[​](#tracking--integrations "Direct link to Tracking & integrations")

| Tool                                                                         | Tier            |
| ---------------------------------------------------------------------------- | --------------- |
| `tracking.site.add` · `.check` · `.list` · `.get_metrics`                    | setup / T0      |
| `tracking.site.update`                                                       | write           |
| `tracking.site.delete`                                                       | T1 entity-token |
| `integration.list` · `integration.check_connection` · `integration.stripe.*` | setup / T0      |
| `integration.start_oauth` · `integration.poll_oauth`                         | browser handoff |
| `integration.configure`                                                      | write           |
| `integration.disconnect`                                                     | T1 entity-token |

### Drilldowns[​](#drilldowns "Direct link to Drilldowns")

| Tool                                   | Notes                                                                                                                                |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `stage.drilldown({ stageId, axis })`   | Axis enum: `paths`, `sources`, `referrers`, `users`, `revenue`, `churned`, `mentions`, `ad_envelopes`, `seo_envelopes`, `dashboard`. |
| `funnel.drilldown({ funnelId, axis })` | Axis enum: `retention`, `conversion_trend`, `split_options`, `stage_metrics`.                                                        |
| `discover_drilldown_axes`              | Returns the full axis catalog with descriptions and example payloads.                                                                |

### Profile data (PRO only)[​](#profile-data-pro-only "Direct link to Profile data (PRO only)")

| Tool                                     | Tier               |
| ---------------------------------------- | ------------------ |
| `profile.search` · `profile.get_journey` | T0 (PRO plan only) |

### Reports[​](#reports "Direct link to Reports")

| Tool                                              | Tier  |
| ------------------------------------------------- | ----- |
| `report.list` · `report.get` · `report.get_quota` | T0    |
| `report.generate`                                 | write |

### Change feed + revert[​](#change-feed--revert "Direct link to Change feed + revert")

| Tool                                     | Tier       |
| ---------------------------------------- | ---------- |
| `mcp.list_changes` · `mcp.revert_change` | T0 / write |

### Generic confirmation[​](#generic-confirmation "Direct link to Generic confirmation")

| Tool                                                                                                | Tier                     |
| --------------------------------------------------------------------------------------------------- | ------------------------ |
| `confirm_target({ targetType, targetId, action })`                                                  | mints T1 entity-token    |
| `admin.request_action({ action, subject?, summary })` · `admin.confirm_action({ requestId, code })` | T2 code-paste primitives |

## Pre-baked prompts[​](#pre-baked-prompts "Direct link to Pre-baked prompts")

Pre-canned workflows your agent can run:

* `setup_funnelfizz`, full onboarding walk
* `connect_tracking` · `connect_stripe` · `connect_email_sending` · `connect_provider` · `setup_seo`
* `weekly_review`, multi-funnel summary
* `diagnose_funnel`, pinpoint why a funnel is underperforming
* `find_dropoff`, locate the biggest conversion leak

## Authentication & limits[​](#authentication--limits "Direct link to Authentication & limits")

* Format: `ff_…` + 48 base64url chars. SHA-256 hashed at rest; cleartext shown once.
* Per-key scopes: `setup`, `read`, `write`, `admin` (see above).
* Per-plan rate limits: FREE 30/min + 5k/month · HOBBY 60/min + 50k/month · PRO 300/min + 500k/month.
* Per-call audit log in **Settings → Developer → Activity**.

## Related[​](#related "Direct link to Related")

* [Safety tiers](https://docs.funnelfizz.com/ai-agents/safety-tiers.md) — T0/T1/T2 explainer.
* [Browser handoffs](https://docs.funnelfizz.com/ai-agents/browser-handoffs.md) — checkout, portal, OAuth flows.
* [Admin actions](https://docs.funnelfizz.com/ai-agents/admin-actions.md) — code-paste handshake walkthrough.
* [Revert changes](https://docs.funnelfizz.com/ai-agents/revert-changes.md) — `mcp.list_changes` + `mcp.revert_change`.
* [Tool reference](https://docs.funnelfizz.com/ai-agents/tool-reference.md) — every tool with signature + example.
* [Setup with an agent](https://docs.funnelfizz.com/ai-agents/setup.md) — paste-prompt flow.
* [Reading docs](https://docs.funnelfizz.com/ai-agents/read-docs.md) — `llms.txt`, `llms-full.txt`, Context7.
* [MCP homepage](https://modelcontextprotocol.io) — protocol spec.