Funnel MCP brings your marketing data, field definitions and workspace context into the AI products you already use.

The Model Context Protocol (MCP) is an open standard for connecting apps to external tools and data. Many apps support MCP, so you can use Funnel MCP in the client that fits your workflow.

Funnel MCP authenticates with OAuth 2.0. Read tools get data, definitions and settings from your account. Write tools make changes, such as creating custom fields, exports, data sources and client portals, but only after you approve each change in the conversation. Funnel MCP is available for all plans. Using Funnel MCP doesn't consume Flexpoints. Data sources and exports that you create or turn on through Funnel MCP consume Flexpoints in the same way as in Funnel. See Flexpoints.

Funnel MCP is a good fit if your team wants to work with Funnel data from an MCP-compatible client, for example an AI assistant or IDE.

Compatible MCP clients

Funnel MCP works with the following MCP clients:

Anthropic Claude (listed in the Claude connector directory): See Connect Funnel MCP to Claude for setup.
ChatGPT (listed in the ChatGPT plugin directory): See Connect Funnel MCP to ChatGPT for setup.
Claude Code: See Connect Funnel MCP to Claude Code for setup.
OpenAI Codex
Cursor
Gemini CLI and Google Antigravity
GitHub Copilot in VS Code
Lovable
Perplexity
Other MCP-compatible clients (manual setup)

Copy connection details from AI > MCP. See Connect Funnel MCP from Funnel AI.

Before you begin

You have a Funnel account with access to at least one workspace.
At least one data source is connected in that workspace, so MCP queries return real results.
To use write tools, you have the matching edit permission in that workspace. Each tool group under Available tools lists the permission it needs.

Authentication and regions

Funnel MCP requires OAuth 2.0 authentication.
Sign in with the Funnel account that has access to your workspaces.
Funnel runs MCP on regional infrastructure. Use the MCP server URL or region based on where your data resides.

Where does your data reside?	Funnel subscription URL	Funnel MCP server URL
Global (default)	`https://app.funnel.io/`	`https://mcp.ai.funnel.io/mcp`
EU	`https://app.eu.funnel.io/`	`https://mcp.eu.ai.funnel.io/mcp`

Note: Copy the server URL from your client's card on the Connect Funnel MCP page. The card uses the URL for your Funnel region.

Available tools

Funnel MCP has read tools and write tools. Your MCP client calls them on your behalf. You describe the outcome in natural language, and the client selects the tools. To compare what you can do in Funnel MCP and in Funnel AI, see Funnel AI and Funnel MCP cheatsheet.

Read tools look up data, definitions and settings. They don't change anything in Funnel.
Write tools change your Funnel account, for example by creating a custom field, an export or a data source.

Write tools never change anything without your approval:

The client first prepares the change and shows you what will change. Nothing changes yet.
The change runs only after you approve it in the conversation. Each approved change runs once.
Prepared changes expire. Changes to exports, data source creation, client portals, brands and budgets expire after 30 minutes. Custom field previews expire after 1 hour. If a change expires, ask the client to prepare it again.
For changes to an existing data source, such as renaming or deleting it, the client checks the data source first and asks you to approve the exact change. If the data source changed after the check, Funnel refuses the change.
Your MCP client may also ask for its own approval before it runs a write tool.

You can only do what your Funnel role allows. If your role doesn't include the permission a tool needs, Funnel MCP tells you, and you can ask a subscription owner for access. Each article under Manage your workspace lists the permission it needs.

Workspace preparation

Tool	Type	Description
`list_workspaces`	Read	Lists Funnel workspaces you can access, grouped by subscription. Use the returned workspace IDs in later tools.
`load_workspace`	Read	Loads connected platforms, field counts, reporting currency and data source health for one workspace. Required before you search fields or query data.
`get_workspace_context`	Read	Returns administrator-authored conventions, business rules and domain terminology for the workspace. Call once after `load_workspace`.

load_workspace can report sources that are unauthorized, delayed or invalid. Ask the client to summarize source health when a query returns less data than you expect.

Field discovery

Tool	Type	Description
`search_fields`	Read	Finds dimensions, measures and metrics in the loaded workspace.
`get_dimension_values`	Read	Returns actual values for a dimension in a date range, for example campaign names or countries.
`list_guides`	Read	Returns Funnel's guide to the rules for custom fields.

search_fields has three modes:

Mode	When to use it
semantic	Preferred for discovery. Ask in natural language (for example, spend on Facebook or cross-platform performance metrics).
browse	Explore a known platform, category or group, or list data sources and their IDs.
search	Exact field name or label only.

Some custom metrics appear with partial availability. Results are correct for the platforms that report the underlying data and can be empty for platforms that don't.

Pull and analyze data

Tool	Type	Description
`query_data`	Read	Queries advertising data from connected platforms and returns a table for further analysis.
`prepare_data`	Read	Loads raw, row-level data without aggregation.

query_data modes:

Mode	When to use it
query	Fetch fresh data by dimensions and measures for a date range.
compare_channels	Compare metrics across platforms using cross-platform fields only.
aggregate	Re-slice a table you already loaded, without fetching again.
compute_metric	Calculate a ratio such as CPC, CTR or ROAS on a loaded table.
restore	Check whether a table from earlier in the session is still available. It doesn't run the query again.

Manage your workspace

Funnel MCP also has tools to work with your workspace, not only your data. Each article below covers what you can do, the permission you need and the tools the client uses.

Create custom fields using Funnel MCP: Create or update custom dimensions and metrics.
Manage exports using Funnel MCP: Find, create, turn on or off and run exports.
Manage data sources using Funnel MCP: Add, change, delete and restore data sources.
Manage portals and brands using Funnel MCP: Create and change client portals and brands.
Check Flexpoint usage using Funnel MCP: Check Flexpoint usage by subscription, workspace and connector.
Manage budgets using Funnel MCP: Rename, archive and restore budgets.
View conventions using Funnel MCP: View active and archived conventions.

Measurement

If your subscription has the Measurement add-on, Funnel MCP also includes measurement_* tools. They cover marketing mix modeling (MMM), measurement reports, incrementality tests, media plans and forecasting. Many of them are write tools, for example the tools that create media plans, incrementality tests or forecast what-ifs.

Measurement tools use your Funnel access. They're part of the Funnel MCP listing in the Claude and ChatGPT directories, so there is nothing extra to set up.

Tool search

Tool	Type	Description
`search_tools`	Read	Finds the right Funnel MCP tool for a task by meaning. It hides Measurement tools that your subscription doesn't include.

How MCP clients typically use these tools

Select a workspace: Run list_workspaces, then run load_workspace for the workspace you need.
Load workspace context: Run get_workspace_context once after load_workspace so answers use your team's conventions and terminology.
Explore fields and dimension values: Run search_fields to find fields to query. Run get_dimension_values when you need values for a specific dimension.
Pull and analyze data: Use query_data for aggregated analysis and cross-channel comparisons. Use prepare_data if you need raw, row-level data for custom slicing.
Make a change (optional): When you ask for a change, the client prepares it and shows you what will change. Approve it in the conversation, and the client makes the change.

Note: Your MCP client decides the order of the tools. Describe the outcome you want in natural language. The client selects and runs the tools.

If query_data returns a truncated table, ask the client to re-slice the result (for example, a coarser breakdown, a filter or a shorter date range) instead of raising the row limit. query_data returns up to 500 rows by default. The full result stays on the server.

Connection examples

Copy the snippet from the matching card on the Connect Funnel MCP page. The examples below use the global region. For EU data residency, use https://mcp.eu.ai.funnel.io/mcp in place of https://mcp.ai.funnel.io/mcp. The card already inserts the URL for your account.

Claude Code

claude mcp add --transport http funnel https://mcp.ai.funnel.io/mcp

Run any command afterward. A browser opens so you can authorize Funnel. Leave out --client-id and a pinned callback port. Claude Code registers its own OAuth identity.

OpenAI Codex

codex mcp add funnel \
  --url https://mcp.ai.funnel.io/mcp \
  --oauth-client-id 4HiYmsg53mSStXa3UqfStADOhZ1tF6Y0 \
  -c mcp_oauth_callback_port=8765

Run any command afterward. A browser opens so you can authorize Funnel.

Cursor

Open Settings > MCP and add:

{
  "mcpServers": {
    "funnel": {
      "url": "https://mcp.ai.funnel.io/mcp",
      "auth": {
        "CLIENT_ID": "4HiYmsg53mSStXa3UqfStADOhZ1tF6Y0"
      }
    }
  }
}

Cursor opens a browser so you can sign in to Funnel on first use.

Antigravity IDE

Open Manage MCP Servers > View raw config and add:

{
  "mcpServers": {
    "funnel": {
      "serverUrl": "https://mcp.ai.funnel.io/mcp",
      "oauth": {
        "clientId": "4HiYmsg53mSStXa3UqfStADOhZ1tF6Y0"
      }
    }
  }
}

Use serverUrl. Antigravity rejects url for this server.

Antigravity CLI

agy plugin install https://github.com/funnel-io/funnel-mcp

Then run /mcp in Antigravity CLI to authenticate and inspect the Funnel server.

Other clients

A subscription owner creates the client from Create an MCP client on the Connect Funnel MCP page, then copies the server URL and OAuth values from System user details. See Connect Funnel MCP using OAuth client registration.

Example use cases

Use these prompts as starting points. Replace workspace names, date ranges and field names to match your setup.

Cross-channel marketing performance

Get a trusted cross-channel view of what is driving performance, from high-level channel comparison down to specific campaigns, ads, creatives and keywords.

Show me the trends for spend, impressions, clicks, CPC and revenue. Break it down by traffic source for the last six months.
Compare attribution models between the platforms and Google Analytics. How do they compare for the last month?
Give me an executive weekly report of my KPIs with sessions, transactions, revenue, AOV and CVR.

Pacing toward budget and targets

Stay on top of how spend is pacing against budget and how KPIs such as revenue are performing against targets.

Show month-to-date spend by channel against monthly budget. Flag any channel pacing more than 10% over.
Which traffic sources will overspend their budget by month-end if current pace continues?
At current pace, will we hit our Q2 revenue target? Show the gap and where it is coming from. What should I do about it?

Data exploration and deep-dives

Drill into a specific channel, campaign, product or market. Surface anomalies, find underperformers and get recommendations for further analysis or action.

CPA on Google Ads spiked last week. Which campaigns and keywords are driving the change?
Break down conversions on Facebook by campaign and creative for the last 30 days.
Drill into our top five campaigns by transaction volume. Which paid channels are feeding them? What is the split between organic and paid traffic?

Workspace changes and usage

Create fields, set up exports and check usage from the same conversation. The client shows you each change before it runs, and nothing changes until you approve it.

Create a custom metric called Blended CPA: total spend divided by total conversions across all paid channels.
Create a daily export of spend, clicks and conversions by campaign for the last 30 days to a new Google Sheets spreadsheet.
How many Flexpoints do we have left? Which connectors use the most?

Security and support

Read the Funnel privacy notice for privacy practices, including AI-related topics described there.
For support guidelines, the AI support assistant and how to contact the team, read Funnel support 101.

Quick start guide: Using Funnel MCP