# Maven documentation

> Automated client reporting for agencies: client portals, reports built in Claude and ChatGPT through the MCP, and tag management, at $500 a month per workspace, with per-client pricing for agencies by quote. Maven is built and run by MetricMaven. Every page below is also available on its own at <page URL>.md.

# Maven documentation

> How to set up automated client reporting with Maven, connect Claude, ChatGPT and other AI tools through the MCP, run client portals and manage tracking.

Source: https://mavendata.ai/docs

Maven is automated client reporting for agencies. Each client gets its own **workspace** with their connected sources, a client portal, reports, and the tracking behind them.

These docs are written for people and for AI agents. Every page is also available as plain Markdown: add `.md` to the URL (for example [/docs/mcp.md](https://mavendata.ai/docs/mcp.md)), or use **Copy as Markdown** at the top of any page. The whole set is in one file at [/llms-full.txt](https://mavendata.ai/llms-full.txt).

## The three parts of Maven

| Part | What it does | Start here |
|---|---|---|
| Tag management | Audits each client's Google Tag Manager or Piwik PRO Tag Manager, stages changes for your approval, sends conversions server-side and checks tracking health daily. | [Tag management](https://mavendata.ai/docs/tag-management) |
| The MCP | Connects Claude, ChatGPT, Claude Code, Cursor and other AI tools to each client's data, so your team builds reports, decks and alerts by asking. | [Connect your AI tools](https://mavendata.ai/docs/mcp/connect) |
| Client portal | A portal per client where they open their reports. It can run on your own domain with your branding. | [Client portal](https://mavendata.ai/docs/client-portal) |

## Quick start

1. [Create a workspace](https://mavendata.ai/docs/getting-started) for one of your clients.
2. [Connect their sources](https://mavendata.ai/docs/getting-started/connect-sources): ad platforms, analytics, CRM and their tag manager (Google Tag Manager or Piwik PRO).
3. [Check their tracking](https://mavendata.ai/docs/tag-management) and approve any staged changes.
4. [Connect Claude or ChatGPT](https://mavendata.ai/docs/mcp/connect) and ask for their first report.
5. [Publish it to their portal](https://mavendata.ai/docs/client-portal).

## For developers and agents

- [MCP overview](https://mavendata.ai/docs/mcp): what an assistant can do once Maven is connected.
- [Agent workflows](https://mavendata.ai/docs/mcp/workflows): complete MCP calls for common jobs.
- [Operation reference](https://mavendata.ai/docs/mcp/reference): every operation, its scopes and input schema. Machine-readable JSON is at [/docs/mcp.json](https://mavendata.ai/docs/mcp.json).
- MCP endpoint: `https://mcp.metricmaven.io/mcp` (Streamable HTTP, OAuth or a Maven API key).

---

# Create a client workspace

> Set up a Maven workspace for each client, with its own sources, reports, portal access and tracking, then add the context Maven uses when it builds reports.

Source: https://mavendata.ai/docs/getting-started

In Maven, every client gets their own **workspace**. A workspace holds that client's connected sources, reports, budgets and tracking, and it decides which of your team and which client users can see them. Each workspace is kept separate from every other client. Create one workspace per client, then connect their sources.

Only account admins can create workspaces.

## Create the workspace

1. Open the **New Workspace** page. If your account has no workspaces yet, Maven opens it for you when you sign in. You can also choose **Create a workspace** on the welcome checklist, or search for **Add New Workspace** in the command palette.
2. Enter a **Workspace Name**. This is the client-facing name, shown in the app, in reports and on the client portal.
3. Optionally enter the client's **Website**, for example `https://acme.com`.
4. Select **Create Workspace**.

If adding the workspace changes your subscription, the button shows the price instead, and Maven asks you to confirm before it creates the workspace. See [Plans and pricing](https://mavendata.ai/docs/account/plans).

When the workspace is created, Maven opens **Reports** for it. To switch between clients, use the workspace selector in the sidebar (**Search workspaces...**).

## Check the workspace settings

Open the user menu at the bottom of the sidebar and choose **Settings**. With a workspace selected, **Workspace** settings come first.

| Section | What it's for |
|---|---|
| **Workspace profile** | The workspace name and website. Select **Save changes** after editing. |
| **Default currency** | The currency used for labels and defaults. Reported spend always keeps each ad account's own currency. Enter a code such as `USD` and select **Save currency**, or select **Use automatic** to let Maven detect it. |
| **Agent context** | What Maven knows about this client. Maven uses it when it builds reports and answers questions. |

## Tell Maven about the client

Maven builds most of a workspace's context from connected data and conversations. You can add to it directly:

1. In **Agent context**, find **Tell the agent anything**.
2. Write the client's goals, definitions, caveats or preferences, for example "Leads means qualified form fills, not newsletter sign-ups". Maven keeps your words exactly.
3. Select **Save context**.

If Maven has open questions about the client, they appear under **A few things to clarify**. Short answers help it fill gaps it can't infer from the data.

Under **What the agent knows**, you'll see structured facts such as **Business type**, **Industry**, **Priority KPIs**, **Cadence**, **Primary platforms** and **Fiscal year starts**. These are read-only. Maven maintains them from your data and conversations, so correct them by telling the agent.

```prompt
Remember for the Acme workspace that "leads" means qualified form fills, not newsletter sign-ups.
```

## What happens next

1. [Connect the client's sources](https://mavendata.ai/docs/getting-started/connect-sources).
2. [Set budgets and alerts](https://mavendata.ai/docs/getting-started/targets-and-alerts).
3. [Set up the client portal](https://mavendata.ai/docs/client-portal) and invite the client.
4. [Connect your AI tools](https://mavendata.ai/docs/mcp/connect) to build reports for the workspace.

## FAQ

**Can one workspace cover several brands?** A workspace is one client. If you report on brands separately, give each its own workspace.

**Who on my team can see a workspace?** Admins have full access to the account. Other team members and client users need access to at least one workspace, which you choose when you invite them. See [Client logins and sharing](https://mavendata.ai/docs/client-portal/sharing-and-access).

---

# Connect a client's sources

> Connect a client's ad platforms, analytics, CRM and commerce tools to their Maven workspace, or send the client a connect link so they can authorize an account themselves.

Source: https://mavendata.ai/docs/getting-started/connect-sources

Sources are the platforms Maven pulls a client's data from: ad platforms, analytics, CRM, commerce, email, SEO and more. You connect them per workspace, and Maven models the data into clean, documented tables you can report on. Most sources connect by signing in to the platform. Some ask for an API key or other credentials instead.

## Connect a source

1. Select the client's workspace in the sidebar, then open **Sources**.
2. Select **Add a source** and search for the platform, for example Google Ads, Facebook Ads, LinkedIn Ads, TikTok Ads, Google Analytics 4, HubSpot CRM or Shopify.
3. Check **What Maven will access**, then select **Connect** followed by the platform name.
4. Sign in to the platform in the window that opens and approve access. If nothing opens, allow pop-ups for Maven and try again.
5. Choose the accounts to pull from, such as the ad account, GA4 property or CRM portal, and confirm your selection.

The source then appears in the **Sources** table with its **Status**, **Result**, **Last sync** and **Schedule**.

If you have already connected the same platform for another workspace, Maven may offer to reuse that sign-in. Each connection is labelled either **Shared across your workspaces** or **This workspace**. To add another account on a platform that is already connected, open it in **Sources** and select **Add account**.

```prompt
Connect Google Ads to the Acme workspace.
```

## Let the client authorize an account

You might not have access to a client's account yourself. In that case, send the client a link and let them authorize it.

1. In **Sources**, start connecting the platform for the client's workspace.
2. Select **Copy shareable connect link**.
3. Send the link to the client. They open it, sign in to the platform and choose the accounts. The connection is added to the workspace.

Connect links expire. If the client sees "This connect link has expired. Please request a new one.", copy a fresh link. Not every platform supports connect links. Maven tells you when one doesn't.

## Connect the client's tag manager

Maven works with Google Tag Manager and Piwik PRO Tag Manager. If the client uses Piwik PRO, connecting Piwik PRO as a source also covers its Tag Manager.

Connect Google Tag Manager the same way: **Add a source**, then **Google Tag Manager**. When you choose accounts, tick every GTM container the client's site uses. All containers share the same Google connection. See [Tag management](https://mavendata.ai/docs/tag-management) for what Maven does with it.

## Manage a connection

Open the actions menu on a source in the **Sources** table to:

- **Sync now**: pull new data immediately.
- **Reauthenticate**: sign in again when a platform's access has expired or been revoked.
- **Remove**: disconnect the source and delete its connection data.

```prompt
Which platforms are connected in the Acme workspace, and what should I connect next?
```

## What happens next

After you connect a source, Maven runs a first sync and builds the workspace's tables. This usually takes tens of minutes. You can start building reports once that finishes. If a first sync fails, the source shows the error in **Sources**, and you can reauthenticate or reconnect it.

You can also connect and check sources from Claude or ChatGPT through the MCP. The `integration` tool lists the available platforms, starts a connection and reports each source's readiness. See the [MCP overview](https://mavendata.ai/docs/mcp).

Next, [set budgets and alerts](https://mavendata.ai/docs/getting-started/targets-and-alerts) for the workspace.

---

# Budgets, goals and alerts

> Set monthly media budget targets for a client workspace, track pacing, record the client's KPIs and goals, and create alerts that post to Slack or email.

Source: https://mavendata.ai/docs/getting-started/targets-and-alerts

When a workspace's sources are connected, tell Maven what the client is aiming for. Monthly **media budget targets** drive pacing: spend to date, projected month-end spend, and over- or under-pacing flags. **KPIs and goals** go into the workspace's agent context, so reports use the client's own definitions. **Alerts** watch a metric and tell you in Slack or email when it crosses a line.

## Set media budget targets

Budget targets are monthly amounts per ad platform. You can also set them for individual campaigns, ad groups (Meta ad sets) or ads.

### Choose the budget type

Each workspace has one **Budget type**. It decides what the budget means and which spend pacing compares with it:

| Budget type | Use it when | The budget is | Pacing compares it with |
|---|---|---|---|
| **Fee on top** (default) | You charge your agency fee on top of media | Ad cost only (**Ad cost target**) | Spend before commission |
| **Fee included** | Your fee comes out of the client's budget | The client's total (**Budget incl. agency fee**) | Spend including the fee |
| **Just a budget** | The workspace is not an agency client, so there is no fee | The budget | Spend |

With **Fee included**, spend including the fee is spend ÷ (1 − commission % ÷ 100), worked out per platform with that platform's **Commission %** for the month. A platform with no commission counts at spend. **Just a budget** hides commission in the budget editors and leaves it out of pacing; any rates you entered before are kept, so switching back restores them.

The budget type is a workspace setting, not part of the monthly budgets. To change it, select the workspace, open **Workspace** > **Profile** under **Setup** in the sidebar, pick an option in **Budget type**, then select **Save budget type**. Only workspace admins can change it; everyone else sees it read-only. The new type applies to every month at once. The budget editors show the current type with a link to this setting.

### Enter targets

You can set targets in three ways.

**In Maven.** On **Pacing**, select **Edit budgets** (or **Set budgets**). Enter each channel's amount for the month and, unless the type is **Just a budget**, its **Commission %**.

**From Claude or ChatGPT.** Ask for it in plain English, for example "Set the Google Ads budget for December to $12,000 for Acme". The assistant uses the `workspace` tool's `set_media_budgets` operation. Maven first shows a before-and-after plan of the changes. Nothing is saved until you approve that exact plan. See [Connect your AI tools](https://mavendata.ai/docs/mcp/connect).

**In a pacing report.** If a client's report includes budget pacing, it has a **Media Budget** page next to **Pacing**:

1. Open the report and select **Media Budget**.
2. Pick the **Year**.
3. For each platform and month, enter the target. With **Fee on top** it's the **Ad cost target**, and an optional **Commission %** shows **Spend with commission**. With **Fee included** it's the **Budget incl. fee**, and the **Commission %** shows the **Ad cost after fee**. With **Just a budget** there is only the **Budget**.
4. Select **Save year**.

When it saves, Maven shows "Saved to the governed media budget table. Pacing refreshed."

```prompt
Set Acme's Google Ads budget to $12,000 a month for every month of 2027.
```

## Track pacing

Pacing compares each month's spend with its targets: spend to date, pace, projected month-end spend, and flags for platforms that are over or under. Spend follows the workspace's budget type: with **Fee included**, the spend that **Pacing** and your AI assistant's pacing answers compare with the budget includes the agency fee, and Maven labels it that way. Cross-client pacing tables and budget alerts still compare spend before commission. Ask your AI assistant "How is Acme pacing this month?" and it reads the workspace's pacing. Budget pacing is also part of the [daily brief](https://mavendata.ai/docs/tag-management/tracking-health).

Maven doesn't flag projections until it has at least 3 days of spend data for the month. If a platform has spend but no target, or a target but no spend yet, pacing says so instead of guessing.

```prompt
How is Acme's ad spend pacing against budget this month, and which platforms will overspend?
```

## Record KPIs and goals

Maven has no separate goals form. Record the client's KPIs and goals in the workspace's agent context instead:

1. Open **Settings** from the user menu, then **Workspace**.
2. In **Agent context**, use **Tell the agent anything** to write the goals and how they're defined, for example "Primary KPI is cost per qualified lead; target under $85".
3. Select **Save context**.

Maven keeps your words exactly. It also maintains a read-only **Priority KPIs** fact under **What the agent knows**. See [Create a client workspace](https://mavendata.ai/docs/getting-started).

```prompt
Remember that Acme's main KPI is cost per qualified lead, with a goal of under $45.
```

## Create an alert

Alerts are on the **Scheduled** page, on its **Alerts** tab.

1. Select **New alert** and choose the **Workspace**.
2. Describe what you want to watch, for example "Warn me when ROAS drops below 2 for 3 days in a row", and select **Draft my alert**.
3. Maven drafts the rule and replays it over the workspace's history. You see when it **Would have fired**, the **Fire dates**, and **What it will say when it fires**.
4. Adjust the rule if you need to. You can set the **Severity**, how often to **Check** (**Daily** or **Hourly**), the **Metric**, and when it **Fires when**. Budget alerts take a **Budget ($)**, a **Period** and an **Alert at (%)** threshold. Anomaly alerts use a **Deviation from rolling average (%)**, and flatline alerts use **Consecutive flat days**.
5. Choose where it goes: **Slack** (optionally with a webhook URL), **Email**, or both.
6. Select **Set live**.

You can also create and preview alerts from your AI assistant with the `notification` tool. See the [MCP overview](https://mavendata.ai/docs/mcp).

```prompt
In the Acme workspace, alert me on Slack when ROAS drops below 2 for 3 days in a row.
```

## Related

- [Connect a client's sources](https://mavendata.ai/docs/getting-started/connect-sources)
- [Tracking health and the daily brief](https://mavendata.ai/docs/tag-management/tracking-health)
- [Plans and pricing](https://mavendata.ai/docs/account/plans)

---

# MCP overview

> Use your clients' Maven data from Claude, ChatGPT, Claude Code, Cursor and other AI tools. Ask questions, build reports and decks, and set up alerts in plain language.

Source: https://mavendata.ai/docs/mcp

The Maven MCP server connects your clients' marketing data to AI assistants. Once it's connected, your team can ask questions, build reports and decks, and set up alerts in plain language, then publish the results to the client's portal.

- **Endpoint:** `https://mcp.metricmaven.io/mcp` (a standard remote MCP server over Streamable HTTP)
- **Sign-in:** each person signs in with their own Maven account (OAuth). You never copy a password or token.
- **Clients:** Claude (Team, Enterprise and individual plans), ChatGPT, Claude Code, Cursor and any client that supports Streamable HTTP.

Next: [connect your AI tools](https://mavendata.ai/docs/mcp/connect).

## Your first questions

Start a new chat and try these. The assistant picks the right Maven tools on its own.

1. "Which Maven workspaces can you see for me?"
2. "Is my data up to date?"
3. "Are we on track to hit this month's media budget?"
4. "How did my paid channels perform last month compared with the month before?"
5. "Build a dashboard of those results."

## What you can do

Your connection may include only some of these. Each links to its technical details in the [operation reference](https://mavendata.ai/docs/mcp/reference).

### Ask about performance

Totals, comparisons, rankings, funnels, attribution and customer journeys across your connected platforms. Reference: `query_metrics`.

- "How did paid search do last month versus the month before?"
- "Rank campaigns by cost per lead over the last 30 days."

### Build reports and decks

Create, edit and publish dashboards and slide decks, and export them to PDF or PowerPoint. Reference: `report`.

- "Build a monthly dashboard for my paid channels."
- "Turn last quarter's results into a 6-slide deck."

### Get alerts and briefs

A daily brief on tracking health and budget pacing, plus alerts and scheduled report emails. Reference: `notification`.

- "Give me today's tracking-health and budget-pacing brief."
- "Alert me if cost per lead goes above $80."

### Check your data

See your workspaces, which sources are connected and how fresh the data is. Reference: `workspace`.

- "Is my data up to date?"

### Track budget pacing

Spend to date against your monthly media budget, projected month-end spend and pacing by platform. Uses the budget targets saved in Maven. Reference: `workspace`.

- "How is ad spend pacing against budget this month?"
- "Which platforms will overspend by month end?"

### Manage connections

See which platforms are connected, and connect or disconnect data sources. Reference: `integration`.

- "Which platforms are connected?"
- "What should I connect next?"

### Teach Maven about the client

Save facts about the client's business, site and goals so answers and reports reflect them. Reference: `context`.

- "Remember that this client's fiscal year starts in July."

### Explore available metrics

Find out which metrics and dimensions exist, so answers use real names rather than guesses. Reference: `describe_schema`.

- "What conversion metrics do I have?"

### Get help from the Maven team

Ask for help, report a bug or check on a request you already made. Reference: `request`.

- "Report that the Acme dashboard isn't loading."

### See your access

Shows who you're connected as and what you're allowed to do. Reference: `whoami`.

- "What can you do in Maven for me?"

## Tips and troubleshooting

- **Name the workspace** if you have more than one, for example "in the Acme workspace…".
- **Give a date range**, like "last 30 days" or "Q3 versus Q2", to get comparable numbers.
- **Assistant can't see a tool you expect?** Your connection may not include it. Ask "what can you do in Maven?" to get your exact permissions.
- **Seeing old or missing Maven tools?** Disconnect and reconnect Maven in your client to load the current tool list.
- **Need a person?** Ask the assistant to "send this to the Maven team". That files a request for you.

---

# Connect Claude, ChatGPT, Claude Code and Cursor

> Step-by-step setup for connecting Maven's MCP server to Claude Team and Enterprise, Claude individual plans, ChatGPT, Claude Code, Cursor and other MCP clients.

Source: https://mavendata.ai/docs/mcp/connect

Every client uses the same server address: `https://mcp.metricmaven.io/mcp`. You sign in with your Maven account the first time. You never need to copy a password or token.

## Claude Team and Enterprise

An organization owner adds Maven once, and then everyone on the team can connect.

1. An owner opens **Organization settings → Connectors**, selects **Add**, then **Custom → Web**.
2. Paste `https://mcp.metricmaven.io/mcp` as the server URL and select **Add**. Leave the advanced OAuth fields empty.
3. Each team member opens **Customize → Connectors**, finds Maven (marked *Custom*) and selects **Connect**, then signs in with their own Maven account.

Every member signs in separately, so each person only sees the Maven workspaces their own account can access.

## Claude (individual plans)

1. Open **Customize → Connectors**, select **+** and choose **Add custom connector**.
2. Paste `https://mcp.metricmaven.io/mcp` as the server URL and select **Add**.
3. Select **Connect** and sign in with your Maven account.

## ChatGPT

ChatGPT calls MCP connections *apps*, and custom apps need developer mode, on the web only. On Business, Enterprise and Edu plans a workspace admin adds Maven once for everyone. Pro plans can add it for themselves, but ChatGPT limits Pro to reading data, so creating reports or alerts needs a business plan.

1. Turn on developer mode under **Settings → Apps → Advanced settings**. On Enterprise and Edu, an admin first allows it under **Workspace settings → Permissions & Roles**.
2. Business, Enterprise and Edu admins open **Workspace settings → Apps → Create**. Pro users open **Settings → Apps → Create**.
3. Name it *Maven*, paste `https://mcp.metricmaven.io/mcp` as the server URL, choose **OAuth**, then select **Scan Tools** and sign in with your Maven account. Select **Create**.
4. On business plans, the admin publishes it from **Workspace settings → Apps → Drafts** so the team can connect with their own Maven accounts.
5. In a new chat, choose Maven from the tools menu or @mention it.

ChatGPT keeps a snapshot of Maven's tools from when the app was published. If Maven calls start failing after we release changes, an admin can refresh the app's actions (Enterprise and Edu) or recreate and republish it (Business).

## Claude Code

```bash
claude mcp add --transport http maven https://mcp.metricmaven.io/mcp
```

Then run `/mcp` inside Claude Code and choose Maven to sign in.

## Cursor and other MCP clients

Add Maven as a remote (Streamable HTTP) server. In Cursor, that goes in `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "maven": {
      "url": "https://mcp.metricmaven.io/mcp"
    }
  }
}
```

## Choosing which clients to share

When you sign in, Maven asks which workspaces the assistant may use. Agencies usually choose **All workspaces**, which also covers workspaces you add later. You can pick a single client's workspace instead, and change it anytime by disconnecting and connecting again.

## Clients without browser sign-in

Clients that can't sign in with a browser can use a Maven API key (it starts with `mvd_live_`) as a bearer token instead. The client sends it as `Authorization: Bearer <key>` on every request. An API key carries the scopes it was issued with.

Next: [what a connection can and can't do](https://mavendata.ai/docs/mcp/security).

---

# MCP access and security

> What an AI assistant connected to Maven can see and do, what it can't, how your data is handled, and how to revoke access.

Source: https://mavendata.ai/docs/mcp/security

## What a connection can do

- Read reporting data: metrics, comparisons, attribution, data freshness and budget pacing.
- Create and edit Maven reports and decks, and set up alerts and scheduled deliveries. Publishing and other changes happen only when you ask, and the assistant confirms with you first.
- Save notes about the client's business and send requests to the Maven team.

## What it can't do

- Change tracking or tag-manager (GTM) settings, or run tracking diagnostics. Tag changes go through [staged changes you approve](https://mavendata.ai/docs/tag-management) in Maven.
- Start data syncs or pipeline runs.
- See anything outside the workspaces you granted when you signed in.

## How your data is handled

- Each person signs in with their own Maven account. The assistant gets a token limited to the workspaces and permissions that account allows, never your password.
- Answers come from the reporting data Maven already holds for your workspaces. The assistant sees only the results of the requests it makes.
- What the assistant does with those results, such as keeping chat history, is governed by your AI provider's own terms and your plan's settings.

## Revoking access

You can revoke access anytime in Maven under **Settings → Connections**, or by disconnecting Maven in your AI client.

See the [privacy policy](https://mavendata.ai/privacy) and [security overview](https://mavendata.ai/security) for more.

---

# MCP agent workflows

> Connect an agent, query metrics, author reports and follow requests with complete MCP calls.

Source: https://mavendata.ai/docs/mcp/workflows

Connect your remote MCP client to `https://mcp.metricmaven.io/mcp` using OAuth or a Maven API key. The client sends its bearer credential on every request.

Use the [public operation reference](https://mavendata.ai/docs/mcp/reference.md) for every customer operation, required scopes, nested input schemas, and complete argument examples. Your connection's authenticated reference is `https://mcp.metricmaven.io/docs.md`; add `?family=report` to narrow it. Fetch it only with the same credential your MCP client uses. If your host keeps its token private, use the public reference and your advertised tools instead.

## Every call has four fields

Invoke the **family tool** (for example, `report`) with `target`, `operation`, `options`, and `context`. The JSON blocks below are tool arguments, not separate REST requests. Empty `target` and `options` objects are still required. Unknown fields are rejected.

`target` identifies the workspace or record; `options` contains that operation's payload. Top-level `context` records the verbatim user request, this call's goal, a stable turn ID, and fidelity. A request's `options.context` is separate business context. For a new user turn, use a new turn ID and the new verbatim request.

Replace angle-bracket placeholders with actual values from prior responses. Numeric revision examples are illustrative: always use the returned revision. Never invent workspace IDs, metric names, checkpoints, or digests.

## 1. Identify the connection and workspace

Tool: `whoami`. Read authorization, scopes, and documentation links before acting.

```json
{
  "target": {},
  "operation": "inspect",
  "options": {},
  "context": {
    "user_request": "Compare paid media efficiency with qualified pipeline by month.",
    "agent_goal": "Inspect the connection and granted scopes.",
    "turn_id": "turn_example_001",
    "fidelity": "exact"
  }
}
```

For topic guidance (report authoring, reconciliation entity scoping, cross-client freshness, canonical vs compatibility metrics, data readiness), call `whoami` with `operation: "docs"` and `options.topic`; omit the topic to list the topics and documentation links.

Tool: `workspace`. Operation: `list`. Select an allowed workspace ID from the result. Customer-wide credentials need a workspace for workspace-bound work; only omit it where the operation permits a workspace-bound credential to supply it.

```json
{
  "target": {},
  "operation": "list",
  "options": {},
  "context": {
    "user_request": "Compare paid media efficiency with qualified pipeline by month.",
    "agent_goal": "Find the workspace authorized for this analysis.",
    "turn_id": "turn_example_001",
    "fidelity": "exact"
  }
}
```

## 2. Discover metrics before querying

Tool: `describe_schema`. Operation: `schema`. Read the returned metric identifiers, supported dimensions, and compatible grains. Use `metrics` for metric discovery and `dimension_values` before filtering categorical values.

```json
{
  "target": {
    "workspace_id": "<workspace_id>"
  },
  "operation": "schema",
  "options": {},
  "context": {
    "user_request": "Compare paid media efficiency with qualified pipeline by month.",
    "agent_goal": "Discover available metrics and compatible dimensions.",
    "turn_id": "turn_example_001",
    "fidelity": "exact"
  }
}
```

Tool: `query_metrics`. Operation: `aggregate`. Use exact discovered identifiers. Start with compatible metrics from one source; cross-source queries require the documented `allowCrossTable` conditions. Maven computes totals and comparisons.

```json
{
  "target": {
    "workspace_id": "<workspace_id>"
  },
  "operation": "aggregate",
  "options": {
    "metrics": [
      "<metric_from_schema>"
    ],
    "timeDimension": {
      "granularity": "month",
      "range": {
        "start": "2026-07-01",
        "end": "2026-08-31"
      }
    },
    "groupByTime": true
  },
  "context": {
    "user_request": "Compare paid media efficiency with qualified pipeline by month.",
    "agent_goal": "Query monthly performance over the requested period.",
    "turn_id": "turn_example_001",
    "fidelity": "exact"
  }
}
```

Use `compare` for two explicit periods and `rank` for ranked results. Preserve provenance and coverage warnings from the response. Do not silently join incompatible grains or calculate replacement totals from record reads.

## 3. Author a report directly

The `report` family supports creating reports, presentations, and custom drafts; editing source files; governed data bindings; previews; exports; and explicit publication. A durable request is another workflow, not a prerequisite for direct authoring.

Report authoring uses four operations, each selecting what it does with `options.action`: `draft` (create, find, import, restore, abandon), `read` (published reports, state, context, files, history, collaboration), `edit` (source files and bindings), and `check` (validate, resolve, verify, open). Before creating, find existing work: `read` with `options.action: "list_reports"` lists the workspace's published reports with their `assignment_id`; `draft` with `options.action: "open_draft"` and that `assignment_id` resumes the draft based on the current live version (or creates one), and `read` with `options.action: "inspect_state"` returns its `drafts.resume_session_id`. `draft` with `options.action: "list_drafts"` lists open drafts; never resume a row marked `stale: true`, because it was opened from an older published version and cannot be published. Tool: `report`; operation: `draft` with `options.action: "create"` for a new draft:

```json
{
  "target": {
    "workspace_id": "<workspace_id>"
  },
  "operation": "draft",
  "options": {
    "action": "create",
    "format": "report",
    "title": "Monthly performance"
  },
  "context": {
    "user_request": "Create a monthly performance report for this workspace.",
    "agent_goal": "Create the requested report draft.",
    "turn_id": "turn_example_001",
    "fidelity": "exact"
  }
}
```

Keep the returned draft session identity. Call `read` with the actions `inspect_state`, `inspect_context`, and `list_files` to read its current revision, source structure, and design context before editing. Call `edit` with the action `apply_changes`, `write_file`, or `edit_file` and the current `expected_revision`.

For a governed query binding, tool: `report`; operation: `edit` with `options.action: "upsert_binding"`. The binding's `request.timeSlot` is different from the analytics call's `timeDimension`. Fill its metric and time field from schema discovery:

```json
{
  "target": {
    "workspace_id": "<workspace_id>",
    "session_id": "<session_id>"
  },
  "operation": "edit",
  "options": {
    "action": "upsert_binding",
    "expected_revision": 1,
    "binding": {
      "key": "monthly_performance",
      "label": "Monthly performance",
      "source": "query-metrics",
      "grain": "trend",
      "request": {
        "metrics": [
          "<metric_from_schema>"
        ],
        "groupByTime": true,
        "timeSlot": {
          "field": "<time_field_from_schema>",
          "granularity": "month"
        }
      }
    }
  },
  "context": {
    "user_request": "Create a monthly performance report for this workspace.",
    "agent_goal": "Bind the report to governed monthly metrics at the current revision.",
    "turn_id": "turn_example_001",
    "fidelity": "exact"
  }
}
```

Every successful source or binding edit can change the revision. Re-read state after a conflict instead of retrying against an invented revision.

| Next call on `report` | Required input beyond workspace and session | What to carry forward |
| --- | --- | --- |
| `check`, action `validate` | `options.expected_revision` | Validation issues to fix |
| `check`, action `resolve` | `options.expected_revision` | Frozen checkpoint identity |
| `check`, action `verify` | `options.expected_revision`, `options.checkpoint_id` | Verification result; resume with returned tokens when needed |
| `check`, action `open` | `options.expected_revision`, `options.checkpoint_id` of a verified checkpoint | Viewer identity/link for human review |
| `export`, action `export_start` | Revision, checkpoint, `format` (`pdf` or `pptx`) | Export ID; poll `export`, action `export_get` |

Read each operation's complete example in the reference and include `context` on every call. Validation, verification, preview, and export do not publish.

## 4. Publish an exact reviewed checkpoint

Tool: `report`; operation: `publish` with `options.action: "publish"` (a call that omits the action also publishes). First prepare against the verified revision, checkpoint, and current live version. For a first publication with no live version, use `null`; otherwise use the actual live version ID from state.

```json
{
  "target": {
    "workspace_id": "<workspace_id>",
    "session_id": "<session_id>"
  },
  "operation": "publish",
  "options": {
    "action": "publish",
    "phase": "prepare",
    "expected_revision": 2,
    "checkpoint_id": "<checkpoint_id>",
    "expected_live_version_id": null,
    "idempotency_key": "publish-example-001"
  },
  "context": {
    "user_request": "Create a monthly performance report for this workspace.",
    "agent_goal": "Prepare the verified checkpoint for review without publishing.",
    "turn_id": "turn_example_001",
    "fidelity": "exact"
  }
}
```

Review the returned effects with the user. After explicit authorization for that checkpoint, call `publish` (action `publish`) with `phase: "confirm"`, the exact returned action ID and digest, `approved: true`, and an authorization statement. Do not copy a sample digest or infer consent from the original request to create a report.

Continue with the documented `execute` phase if execution remains pending, and inspect `phase: "status"` using the same action ID. If the execution outcome is unknown, use `phase: "reconcile"` with the exact action ID and digest before retrying. Report success only when the returned receipt confirms publication. Changes to source or the live version require fresh preparation and review.

## 5. Submit and follow a durable request

Use the `request` family for report or tagging work handled through Maven's durable request workflow. Customer tagging work uses this workflow; do not assume staff tracking operations are available.

Tool: `request`; operation: `submit`; `options.action`: `submit`:

```json
{
  "target": {
    "workspace_id": "<workspace_id>"
  },
  "operation": "submit",
  "options": {
    "action": "submit",
    "kind": "report",
    "request": "Compare paid media efficiency with qualified pipeline by month.",
    "context": "Use approved KPI definitions and call out missing coverage.",
    "idempotency_key": "request-example-001"
  },
  "context": {
    "user_request": "Compare paid media efficiency with qualified pipeline by month.",
    "agent_goal": "Submit the report request for durable processing.",
    "turn_id": "turn_example_001",
    "fidelity": "exact"
  }
}
```

Keep the returned request identity. Reuse the idempotency key for a retry of the same submission.

Tool: `request`; operation: `status`; `options.action`: `inspect`:

```json
{
  "target": {
    "workspace_id": "<workspace_id>",
    "request_id": "<request_id>"
  },
  "operation": "status",
  "options": {
    "action": "inspect"
  },
  "context": {
    "user_request": "Compare paid media efficiency with qualified pipeline by month.",
    "agent_goal": "Read the request status and next required action.",
    "turn_id": "turn_example_001",
    "fidelity": "exact"
  }
}
```

Every `request` operation takes `options.action`. The action names are the operation names used before consolidation; those old names are retired as operations and return `OPERATION_RETIRED` naming the replacement below.

| Next call on `request` | `options.action` | Inputs and purpose |
| --- | --- | --- |
| `status` | `list` | Workspace target; optional `options.cursor` and `limit` |
| `submit` | `add_context` | Request target; `options.context` and a new `idempotency_key` for the clarification |
| `prepare` | `prepare` | Request target; `expected_revision`; defaults to `dry_run: true` (read-only inspection). Set `dry_run: false` with an idempotency key to enqueue preparation; this may run the agent, browser journeys, provider checks, staging, and QA, but never authorizes publication |
| `review` | `review` | Request target; read the exact checkpoint, staged changes, and QA evidence |
| `decide` | `decide` | Request target; reviewed `expected_revision`, `checkpoint_id`, `artifact_revision`, `approved`, and `confirm: true`, after explicit user approval |
| `prepare` | `prepare_provider` | Provider preflight/preparation where supported; see the exact required event fields in the reference |
| `decide` | `decide_provider` | Confirm an explicitly approved provider action using its returned action ID and digest; tag-manager publication is separate |
| `decide` | `decide_action` | Pending-action target (`pending_action_id`); `confirmation_digest`, `approved`, and `authorization_statement`, after the user explicitly decides that pending action |
| `help` | `request_help` or `submit_bug` | Workspace target; a confirmed support request or a reproducible platform bug |

Include the same four-field envelope on these calls. Use current returned revisions, not the sample report revisions above. A timeout or closed connection is not proof of completion; inspect the same request after reconnecting.

## 6. Report on a CRM custom field

Custom fields from your CRM (GoHighLevel, HubSpot, and other connected CRMs) can be grouped and filtered like any other dimension once they are promoted. A connection with `write:reports` (standard customer keys) can run every step; `write:context` or `admin` also works.

1. Store the value on the CRM record. For GoHighLevel, create a contact custom field (for example `contact.cta_button`) and map your form or webhook value into it. A value that only exists in a webhook payload is not visible to Maven. Maven reads the field as `cf_<field key>`, so `contact.cta_button` becomes `cf_cta_button`.
2. Wait for the next CRM sync so the field reaches the lead and deal tables.
3. Discover it. Tool: `describe_schema`. Operation: `custom_fields` with `refresh: true`. New keys appear as `suggested`. On workspaces with many fields the scan can outlast the call; the response then says the scan is still running and shows the current inventory. List `custom_fields` again without `refresh` after a minute to see the new keys.
4. Check the values. Operation: `custom_field_values` with the `cf_key`.
5. Promote it. Tool: `context`. Operation: `promote_custom_field` (`options.action` may be omitted; it defaults to `promote_custom_field`). Promotion is workspace-wide and immediate. Fields classified restricted (password, secret, SSN, or card-like names) need `write:context`. Field names containing `id`, `email`, `name`, or similar are classified sensitive and can still be promoted. Email-, phone-, and SSN-shaped sample values are masked in discovery output.

```json
{
  "target": {
    "workspace_id": "<workspace_id>"
  },
  "operation": "promote_custom_field",
  "options": {
    "action": "promote_custom_field",
    "cf_key": "cf_cta_button",
    "display_name": "CTA button"
  },
  "context": {
    "user_request": "Show leads by which CTA button they clicked.",
    "agent_goal": "Make the CTA button custom field a queryable dimension.",
    "turn_id": "turn_example_002",
    "fidelity": "exact"
  }
}
```

6. Query it. Tool: `query_metrics`. Operation: `aggregate`. Use the `cf_key` as a dimension or filter with a lead metric such as `lead_count`.

```json
{
  "target": {
    "workspace_id": "<workspace_id>"
  },
  "operation": "aggregate",
  "options": {
    "metrics": [
      "lead_count"
    ],
    "dimensions": [
      "cf_cta_button"
    ],
    "timeDimension": {
      "range": {
        "last": 30,
        "unit": "days"
      }
    }
  },
  "context": {
    "user_request": "Show leads by which CTA button they clicked.",
    "agent_goal": "Break down leads by CTA button over the last 30 days.",
    "turn_id": "turn_example_002",
    "fidelity": "exact"
  }
}
```

Promoted fields also work in report bindings. Leads created before the field existed have no value and group as null.

## Other available capabilities

The reference also covers integration discovery and connections (`integration`), alerts and scheduled deliveries (`notification`), workspace business context, notes, and site context (`context`), plus freshness, users, and media-budget pacing (`workspace`). Each operation lists its scopes and approval requirements. Only call operations authorized for your connection.

## Errors and recovery

- `CONTEXT_REQUIRED`: resend with valid top-level context; the rejected call did not run.
- `INVALID_OPERATION_INPUT`: check the exact target/options split, required fields, nested schema, and chosen phase.
- `OPERATION_DENIED`: inspect scopes; do not retry unchanged credentials expecting access.
- `UNKNOWN_OPERATION`: refresh the reference and advertised tools. Use family operations, not historical standalone tool names.
- Revision conflicts: inspect current state and reconcile changes before preparing again.
- Uncertain writes: inspect status and use documented reconciliation/idempotency instead of creating a duplicate action.
- `RATE_LIMITED` (`retryable: true`, `retry_after` seconds): Maven or an upstream provider such as a Google API quota (`upstream_code: GOOGLE_API_RATE_LIMITED`) is throttling. Wait at least `retry_after` seconds, then retry the same call unchanged; do not retry immediately.
- `PUBLISHED_BRAND_THEME_REQUIRED` (`retryable: false`): the published customer Brand Theme version could not be loaded. Call `brand operation=inspect`, then propose again. A customer that has never published a theme does not get this error: `brand operation=propose` starts from the `fallback` that inspect returns, and publishing that proposal with `expected_live_version_id: null` makes it the first published theme.

Check `isError` and the returned content even when the transport succeeds. Keep opaque IDs, pagination cursors, resume tokens, and digests unchanged. The operation reference includes output schemas where declared; an open object schema does not promise particular fields.

Refresh `tools/list` or reconnect if your host cached an older catalog. The initialized connection and tool-list metadata carry a catalog fingerprint.

---

# MCP operation reference

Every operation on Maven's customer MCP surface with required scopes, input schemas and complete argument examples. Generated from the MCP catalog.

Full page (large): https://mavendata.ai/docs/mcp/reference.md

---

# Set up a client portal

> Give your clients a branded portal where they sign in to view their reports. Set the portal's name and address, then add your logo, favicon, colours and brand theme.

Source: https://mavendata.ai/docs/client-portal

The client portal is where your clients sign in to see the reports you publish for them. You run one portal for your account. Each client user sees only the workspaces you give them access to. Setup has two parts. On **Portal** settings you set the portal's name and web address. On **General** settings you add your brand assets and theme.

You need to be an account admin to change portal settings.

## Set the portal name and address

1. Open the user menu at the bottom of the sidebar, choose **Settings**, then **Portal**.
2. Under **Portal identity & domain**, enter a **Portal display name** and select **Save changes**. If you leave the name blank, the portal uses your company name.
3. In **Subdomain**, enter the address you want, for example `your-company`. Maven shows the full Maven-hosted address next to it.
4. Select **Check availability**. Subdomains must be 3 to 63 characters, using only letters, numbers and hyphens, and can't start or end with a hyphen. Some names are reserved.
5. When Maven confirms the address is available, select **Update address**. The subdomain is saved separately from the rest of the page, and Maven shows the new **Portal URL**.

Once a subdomain is saved, the header shows **Portal Live** (otherwise **Subdomain needed**).

You can also serve the portal from your own domain. See [Use your own domain](https://mavendata.ai/docs/client-portal/custom-domain).

## Add your logo and favicon

1. In **Settings**, open **General** and find **Brand assets**.
2. Select **Upload Logo**. Use a PNG or JPG up to 2MB. SVG and WebP aren't accepted, because the logo also appears in emails.
3. Select **Upload Favicon**. Use a PNG, JPG or WebP up to 2MB. Without a favicon, the browser tab shows your company's initial.

To change either file later, select **Replace Logo** or **Replace Favicon**.

## Set colours and brand theme

Your **Brand theme** is the visual system that the portal, reports and decks inherit.

1. On **General** settings, go to **Brand theme**.
2. Start from your existing brand. Enter your website (for example `acme.com`) and select **Extract from website**, or select **Use existing reports & decks**.
3. Review the **Palette**. Each colour has a role: **Accent** (buttons, links, brand moments), **Ink** (primary text), **Muted** (secondary text), **Surface** (cards and containers), **Canvas** (page background) and **Line** (borders and dividers). Maven derives the remaining colours from your palette when you save.
4. Adjust the fonts if you need to, then select **Save draft** to keep working, or **Publish theme** to apply it.

When you publish, the portal and all workspaces use the theme for new reports and decks. To update existing decks as well, select **Re-theme all decks**. Earlier theme versions can be brought back with **Restore**.

## Choose a portal template

**Portal template**, at the top of **Portal** settings, shows the two starting points for what clients see after they sign in, and which one your live portal runs:

- **Report library**: clients sign in to a library of the reports you share with them. This is the standard portal.
- **Client app**: clients sign in straight to live data for their workspace, with **Overview**, **Attribution** and **Pacing** pages, and still reach their reports.

The client app needs a workspace whose data is on Maven's current data model. Where a workspace is not yet on it, the app's Overview page says the figures are not available for that workspace, and the agent applying the template tells you before anything is published. Contact Maven support about a workspace in that state.

A template is a base to alter, not a fixed design. Each card has a prompt to copy for an AI agent connected to Maven. The agent applies the template in a draft, shows you a preview and asks before publishing, so nothing changes for your clients until you approve it. Sign-in, password and profile pages always stay on the standard portal.

## Other portal settings

**Portal** settings also include:

- **Report card previews**: show report images and data sources on the portal's report cards.
- **Loading screens**: what clients see while pages and reports load.

The emails the portal sends to your clients (**Email sender** and **Email templates**) and **Client sign-in security** (whether client users can turn on MFA, see [Client logins and sharing](https://mavendata.ai/docs/client-portal/sharing-and-access)) are under **General** settings.

## What happens next

1. [Invite your client](https://mavendata.ai/docs/client-portal/sharing-and-access) and give them access to their workspace.
2. [Publish a report](https://mavendata.ai/docs/client-portal/sharing-and-access#publish-a-report-to-the-portal) to the portal.
3. Optionally, [move the portal to your own domain](https://mavendata.ai/docs/client-portal/custom-domain).

---

# Use your own domain

> Serve your Maven client portal from your own subdomain, such as reports.youragency.com, verified through DNS with SSL issued automatically. Included in the workspace price.

Source: https://mavendata.ai/docs/client-portal/custom-domain

The client portal can run on a hostname you own, such as `reports.youragency.com`. You connect the domain in Maven and then add DNS records at your DNS provider. Maven verifies the records through Cloudflare for SaaS and issues an SSL certificate automatically. Once verified, your domain serves the same portal as your Maven-hosted address. It doesn't expose the Maven admin app. The white-label portal is included in the workspace price. See [Plans and pricing](https://mavendata.ai/docs/account/plans).

## Before you start

- Set up the portal's Maven-hosted subdomain first. See [Set up a client portal](https://mavendata.ai/docs/client-portal).
- Choose a **subdomain** of a domain you control, for example `reports.youragency.com` or `analytics.example.com`. Root domains such as `youragency.com` aren't supported yet.
- Make sure you, or someone on your team, can add DNS records for that domain.

## Connect the domain

1. Open **Settings** from the user menu, then **Portal**.
2. Under **Portal identity & domain**, enter the hostname in **Custom Domain (optional)**.
3. Select **Connect Domain**. Maven starts verification and shows the DNS records to add.
4. At your DNS provider, add each record exactly as Maven shows it. Every record has a **Host** and a **Value**, each with a **Copy** button:
   - **Portal CNAME**: points your hostname at Maven. It routes the portal and lets Cloudflare issue SSL.
   - **Hostname pre-validation**: a TXT record that proves you own the domain. It only appears when it's needed.
   - Other certificate validation records, if Maven lists any.
5. Return to **Portal** settings. While verification is in progress, the domain shows **Pending**. Select **Refresh** to check again.

When the domain is live, it shows **Verified**. Maven only treats a domain as verified once the hostname and its certificate are active and plain HTTP visits redirect to HTTPS.

Don't copy record values from anywhere else, including this page. The values are generated for your portal, and Maven always shows the current ones.

## What happens next

- **You don't need to stay on the page.** Maven keeps checking in the background and activates the domain on its own once DNS is in place.
- **DNS can take up to 48 hours to propagate.** Each record shows **Required** until Maven sees it, then **Active**. The page also shows the raw **Verification status** and **SSL** status from Cloudflare.
- **Your Maven-hosted address keeps working.** Changing the subdomain and connecting a custom domain are separate settings.

## Troubleshooting

| Message | What to do |
|---|---|
| "Use a subdomain like analytics.example.com. Root domains are not supported yet." | Use a hostname such as `reports.youragency.com` rather than the bare domain. |
| "Cannot use a Maven domain as a custom domain" | Enter a domain you own, not a Maven address. |
| "Domain is already in use by another Maven product or customer" | Choose a different hostname. |
| "Custom domain is not active yet. Confirm the CNAME below…" | Check the CNAME host and value at your DNS provider, wait for propagation, then select **Refresh**. |

If your DNS is on Cloudflare, the **Open Cloudflare DNS** link takes you to your DNS records.

## Related

- [Set up a client portal](https://mavendata.ai/docs/client-portal)
- [Client logins and sharing](https://mavendata.ai/docs/client-portal/sharing-and-access)

---

# Client logins, MFA and publishing reports

> Invite clients to their Maven portal, control which workspaces they see, let them protect their login with an authenticator app, and publish reports to the portal.

Source: https://mavendata.ai/docs/client-portal/sharing-and-access

Clients see their reports by signing in to your portal. Each client user has a role and access to specific workspaces, and they only see live reports in those workspaces. This page covers inviting client users, optional MFA, and publishing reports to the portal. Publishing to the portal is available on every plan.

## Invite a client user

You need to be an account admin to invite users.

1. In the sidebar, open **Users** and select **Invite**.
2. Enter the person's **Email** and, optionally, their **Name**.
3. Choose a **Role**:

   | Role | Access |
   |---|---|
   | **Admin** | Full access: manage team, billing and integrations. |
   | **User** | Can view and interact with assigned workspaces. |
   | **Viewer** | Read-only: reports and workspace data. |

   For clients, **Viewer** is usually the right choice.
4. Under **Workspace Access**, pick the client's workspace. Anyone who isn't an admin needs access to at least one workspace.
5. Select **Send Invite**.

The client receives an email to set up their account. They sign in to the portal with their email and password ("Sign in to access your reports"). If they forget it, they can select **Forgot your password?** on the sign-in page.

If you see "User created, but invitation email failed to send", the account exists but the email didn't go out. Check the address and try again.

## Let clients turn on MFA

MFA for client users is optional and off by default. When you turn it on, clients can protect their login with an authenticator app.

1. Open **Settings**, then **General**.
2. In **Client sign-in security**, turn on **Allow portal users to enroll in MFA**.
3. Select **Save changes**.

Client users then see a prompt in the portal ("Protect your … account.") with **Set up** and **Not now**. They can also add an authenticator later from their profile, under **Two-Step Verification**, and add a backup authenticator.

This setting only controls new enrollment. If you turn it off again, anyone who has already enrolled must still use their authenticator every time they sign in.

## Publish a report to the portal

A report has one of three statuses:

| Status | Who can see it |
|---|---|
| **Private** | Only you. |
| **Internal** | Your team in Maven. It doesn't appear on the client portal. |
| **Live** | On the client portal, for everyone with access to the workspace. |

To publish a report:

1. Open **Reports** with the client's workspace selected.
2. Select the settings (cog) button on the report and, under **Status**, choose **Live**.
3. Review the confirmation, **Make report live**, and select **Go live**.

Maven confirms that the report is now live. Client users with access to that workspace can open it in the portal straight away.

To take a report off the portal, change its status to **Internal** or **Private**. Reports that combine several workspaces can't be published to a client portal.

You can also publish from Claude or ChatGPT with the `report` tool's `publish` operation. Maven shows what will change and publishes only after you approve it. See [Agent workflows](https://mavendata.ai/docs/mcp/workflows).

```prompt
Publish Acme's October report to their client portal.
```

## FAQ

**Can a client see another client's reports?** No. A client user only sees the workspaces you selected under **Workspace Access**.

**Can my team use MFA too?** Yes. Team members can add authenticator apps from their own profile in Maven.

## Related

- [Set up a client portal](https://mavendata.ai/docs/client-portal)
- [Use your own domain](https://mavendata.ai/docs/client-portal/custom-domain)
- [MCP security](https://mavendata.ai/docs/mcp/security)

---

# Connect your tag manager and check tracking

> Connect a client's Google Tag Manager to their Maven workspace with Google sign-in, choose their containers, and ask Maven to check their tags, pixels and conversion tracking.

Source: https://mavendata.ai/docs/tag-management

Maven manages tracking through each client's own tag manager: Google Tag Manager (GTM) or Piwik PRO Tag Manager. You connect it once per workspace and choose the client's containers or site. Maven can then check the client's tags, pixels and conversion events, and prepare container changes for you to review. Maven never publishes a container change you haven't approved. See [Review and approve staged changes](https://mavendata.ai/docs/tag-management/approvals).

## Connect GTM

1. Select the client's workspace, open **Sources** and select **Add a source**.
2. Search for **Google Tag Manager** and select **Connect Google Tag Manager**.
3. Sign in with a Google account that has access to the client's GTM account, and approve access.
4. When Maven lists the **Account / Container** options, tick every GTM container used by this workspace. All the containers share this one Google connection.
5. Confirm your selection.

Maven asks Google for permission to read containers, edit containers and container versions, and publish. It needs these so it can stage changes in GTM and, once you approve, publish them. Approval always happens in Maven first.

If someone at the client owns the GTM account, use **Copy shareable connect link** and send it to them instead. See [Connect a client's sources](https://mavendata.ai/docs/getting-started/connect-sources#let-the-client-authorize-an-account).

```prompt
Connect Google Tag Manager to the Acme workspace.
```

## Connect Piwik PRO Tag Manager

If the client uses Piwik PRO, connecting Piwik PRO also gives Maven access to its Tag Manager. There is no separate tag-manager connection.

1. Select the client's workspace, open **Sources** and select **Add a source**.
2. Search for **Piwik PRO** and connect it.
3. Choose the client's Piwik PRO site.

Maven stages tag, trigger and variable changes in Piwik PRO Tag Manager the same way it does in GTM, and publishes only after you approve them.

```prompt
Connect Piwik PRO to the Acme workspace.
```

## After connecting

After connecting, Maven syncs a snapshot of each container. To pull the latest version at any time, use **Sync now** on the source in **Sources**.

## Check the client's tracking

Ask from Claude, ChatGPT or another AI tool connected to Maven. If you haven't connected one yet, see [Connect your AI tools](https://mavendata.ai/docs/mcp/connect).

- **For a quick health check**, ask for the daily brief: "Give me today's tracking-health and budget-pacing brief for Acme." It lists tracking issues, one per pixel or event, labelled broken, degraded or stalled, with what changed and what to check. See [Tracking health and the daily brief](https://mavendata.ai/docs/tag-management/tracking-health).
- **For a full review or a fix**, describe the work as a tagging request, for example "Audit Acme's GTM container and fix any tags that aren't firing" or "Add a LinkedIn conversion for the demo form". Your assistant submits it with the `request` tool (`kind: "tagging"`). Maven then prepares the change, stages it, and runs QA.

Requests are processed asynchronously, so you can come back to them later. Ask your assistant for the request's status at any time.

```prompt
Check Acme's tracking and submit a tagging request to fix anything that's broken.
```

## What happens next

When a tagging request is ready, it pauses at a review checkpoint with the staged changes and QA evidence. Nothing goes live until you approve it. Continue with [Review and approve staged changes](https://mavendata.ai/docs/tag-management/approvals).

## FAQ

**Does Maven change our GTM container without asking?** No. Preparing a request stages changes and runs QA, but never authorizes publication. Only your explicit approval does.

**Do we need to give Maven a GTM admin login?** No. You connect with Google sign-in. You can disconnect at any time by removing the source in **Sources**.

**Which ad platforms can Maven send conversions to server-side?** Google Ads, Meta, LinkedIn and ChatGPT ads. See [Server-side conversions and consent](https://mavendata.ai/docs/tag-management/server-side).

## Related

- [MCP overview](https://mavendata.ai/docs/mcp)
- [Agent workflows: submit and follow a request](https://mavendata.ai/docs/mcp/workflows)
- [MCP security](https://mavendata.ai/docs/mcp/security)

---

# Review and approve staged changes

> How Maven stages Google Tag Manager changes for a client, what you see at the review checkpoint (the exact staged changes and QA evidence), and how to approve or reject them.

Source: https://mavendata.ai/docs/tag-management/approvals

Every tracking change Maven makes for a client goes through a review checkpoint. Maven prepares the change, stages it in the client's GTM container and runs QA. Then it stops and waits for you. Before anything is published, you see the exact staged changes and the QA evidence, and a person with the right permission has to approve that exact checkpoint. Maven never auto-publishes.

## How a change moves through Maven

| Step | What happens | Publishes anything? |
|---|---|---|
| Submit | You describe the work as a tagging request from your AI tool. | No |
| Prepare | Maven checks readiness, then does the work: stages the change, runs browser journeys and provider checks, and runs QA. | No. Preparation never authorizes publication. |
| Review | You read the checkpoint: the staged changes and the QA evidence. | No |
| Decide | You approve or reject that exact checkpoint. | Only on approval |

All of this runs through the `request` tool in Claude, ChatGPT or any AI tool connected to Maven. See [Agent workflows](https://mavendata.ai/docs/mcp/workflows) for the full calls.

## Review the checkpoint

1. Ask your assistant to show the request that's waiting for review, for example "Show me what's staged for Acme's tracking request." It reads the checkpoint with `request` → `review`.
2. Check the staged changes. Each entry shows the action (create or update), what kind of GTM item it is (such as a tag or trigger), and its ID and name.
3. Check the QA evidence:
   - The overall QA outcome: pass or fail.
   - Whether the change was confirmed at runtime.
   - Coverage: for each page and element tested, which vendor and event fired, where it was sent, and how many times.
   - Links to the evidence Maven collected.
4. If something looks wrong, don't approve it. Reject it, or add context to the request so Maven prepares it again.

Requests submitted this way never delete items from the client's container. Where a request needs to remove a tag, Maven stages it as paused instead.

```prompt
Show me what's staged for Acme's tracking request, with the QA evidence.
```

## Approve or reject

When you're satisfied, tell your assistant your decision in your own words, for example "Approved: publish the staged LinkedIn conversion for Acme." The assistant records it with `request` → `decide`. Your statement is kept in the approval audit trail.

- **Approve**: Maven publishes exactly the changes you reviewed.
- **Reject**: nothing is published, and the request doesn't go ahead.

The approval is tied to the exact checkpoint you reviewed. If the request changes after you looked at it (new context, a fresh preparation, or different staged changes), the old approval no longer applies, and you need to review the new checkpoint.

```prompt
Approve the staged tracking changes for Acme.
```

## Who can approve

Only a signed-in person whose Maven connection has tracking write access (or admin) can approve. An AI assistant can't approve on your behalf, and your assistant should never decide for you. Approvals are recorded against the person who made them. See [MCP security](https://mavendata.ai/docs/mcp/security).

## FAQ

**Can Maven publish a GTM change without approval?** No. Staging and QA happen without approval. Publishing never does.

**What if the QA fails?** The checkpoint shows the failed checks. Don't approve it. Ask Maven to fix the issue and prepare the request again.

**Can I see what's waiting across all my clients?** Yes. Ask your assistant to list requests and their status for each workspace.

## Related

- [Connect your tag manager and check tracking](https://mavendata.ai/docs/tag-management)
- [Server-side conversions and consent](https://mavendata.ai/docs/tag-management/server-side)
- [MCP operation reference](https://mavendata.ai/docs/mcp/reference)

---

# Server-side conversions and consent

> Send a client's conversions to Google Ads, Meta, LinkedIn and ChatGPT ads through server-side Google Tag Manager, under a strict advertising-consent policy or Google Consent Mode, with QA before anything goes live.

Source: https://mavendata.ai/docs/tag-management/server-side

Maven can send a client's conversions through a server-side Google Tag Manager container, as well as from the browser. The client's site sends one event. The server container forwards it to GA4 and to each ad platform you choose, with the same event ID so platforms can deduplicate browser and server conversions. Every deployment respects the visitor's consent and is QA'd before you approve it.

## Supported ad platforms

| Platform | How conversions are sent | What Maven needs |
|---|---|---|
| Google Ads | Server-side conversion tag | Conversion ID and conversion label |
| Meta | Conversions API | Pixel ID |
| LinkedIn | Conversions API | Conversion rule ID |
| ChatGPT ads | Browser pixel and server-side event | Pixel ID |

For each platform, you also choose which event to send, for example `purchase` or `generate_lead`.

## Consent policies

Each deployment records one of two consent policies: **strict advertising consent** (the default) or **Google Consent Mode**, for sites that run Consent Mode. Whichever you choose, the deployment follows the same consent rules:

- **Meta, LinkedIn and ChatGPT ads** only receive an event when the visitor has granted advertising consent. They never receive one when the visitor's browser sends a Global Privacy Control (GPC) signal.
- **Google Ads** only receives user data when the visitor has granted it. Otherwise it gets a restricted version of the conversion with no user data.

Maven reads consent from the client's consent management platform (CMP) through the data layer: the advertising consent category, the GPC signal and the ad user data signal. It works these out from the client's real CMP setup rather than assuming them.

## Set it up

1. Make sure both of the client's GTM containers are connected: the web container and the server-side container. The server container's tagging server must be reachable on an HTTPS URL. See [Connect your tag manager and check tracking](https://mavendata.ai/docs/tag-management).
2. From your AI tool, submit a tagging request describing what you want, for example "Send Acme's purchase conversions server-side to Google Ads and Meta under strict advertising consent." Include the conversion IDs, pixel IDs or conversion rule IDs if you have them.
3. Maven prepares the deployment. It works out the source event and consent fields, stages the server-side tags, and runs QA.
4. Review the staged changes and QA evidence, then approve or reject. See [Review and approve staged changes](https://mavendata.ai/docs/tag-management/approvals).

```prompt
Submit a tagging request to send Acme's purchase conversions to Google Ads and Meta through server-side GTM under Google Consent Mode.
```

## What the QA checks

Before you're asked to approve, Maven runs test journeys and records whether:

- The browser sends the source event once, and the tagging server receives it.
- GA4 receives the event once.
- Each selected ad platform receives the event once, with the same event ID as the browser.
- Before any consent choice, after the visitor rejects, and when GPC is set, non-Google platforms receive nothing.
- After the visitor accepts, every selected non-Google platform fires.
- Google Consent Mode is observed.

If any check fails, the QA outcome is a fail, and you'll see which check failed at the review checkpoint.

## FAQ

**Will this double-count conversions?** The browser and server events share one event ID, which the ad platforms use to deduplicate. The QA confirms the IDs match.

**Can we use our own consent banner?** Yes. Maven reads consent from the CMP's values in the data layer. It doesn't replace your banner.

## Related

- [Tracking health and the daily brief](https://mavendata.ai/docs/tag-management/tracking-health)
- [MCP security](https://mavendata.ai/docs/mcp/security)

---

# Tracking health and the daily brief

> Get a daily brief for each client covering tracking health (broken, degraded or stalled pixels and events) and monthly budget pacing, and schedule it in Claude or ChatGPT.

Source: https://mavendata.ai/docs/tag-management/tracking-health

The daily brief is a short, prioritized summary for a workspace. It has two parts: **tracking health**, which flags every pixel or event that's broken, degraded or stalled, and **budget pacing**, which shows how each platform's spend compares with its monthly target. Critical items come first. When nothing needs attention, the brief says so explicitly.

You get the brief from your AI tool. It's read-only, so asking for it never changes anything.

## Get the brief

1. Connect Claude, ChatGPT or another AI tool to Maven. See [Connect your AI tools](https://mavendata.ai/docs/mcp/connect).
2. Ask: "Give me today's tracking-health and budget-pacing brief for Acme." Leave out the client name to get one brief covering every workspace you have access to (up to 25).

Your assistant uses the `notification` tool's `brief` operation. You can ask for a past date too.

```prompt
Give me today's tracking-health and budget-pacing brief for Acme.
```

## Schedule it daily

Maven doesn't send the brief on a schedule itself. Instead, set up a daily scheduled task in your AI tool (for example a Claude or Cowork task) that asks for the brief each morning. That way it arrives wherever you already work, and it only covers the workspaces your own account can see.

## Tracking health

Each issue is one pixel or event, such as a Meta pixel or a GA4 key event. It shows its worst problem, the owner, what changed and what to check. Issues carry one of three labels:

| Label | Meaning |
|---|---|
| **Broken** | The latest reading is current and fails its threshold. For example, a tag stopped firing, a conversion is paused or unlinked, offline imports are failing, match quality is low, or deduplication keys are missing. The setup needs a fix. |
| **Degraded** | The latest reading is current but below where it should be, for example a recommended setting is off or server-side coverage is partial. Tracking still works, but it's worth fixing. |
| **Stalled** | The evidence stopped moving. Maven has no new reading, data or uploads are arriving late, or a tag has gone quieter than normal. Check the upstream source or connection before trusting the signal. |

The brief groups the checks behind each issue into areas: **Tag firing**, **Event volume**, **Match quality**, **Deduplication**, **Server-side coverage**, **Data freshness**, **Offline conversion imports** and **Configuration**.

Severity tells you how soon to act:

- **Critical**: act today. A signal is failing its threshold, or spend is projected well past the budget.
- **Warning**: check soon. A signal is below where it should be, or spend is pacing outside the expected range.

## Budget pacing

For the current month, the brief shows each platform's spend to date, pace and projected month-end spend against its target, plus a total. Platforms that are over or under pace are flagged. Projections aren't flagged until there are at least 3 days of spend data, and the brief notes when spend data is running behind. To set targets, see [Budgets, goals and alerts](https://mavendata.ai/docs/getting-started/targets-and-alerts).

## New workspaces

If a workspace's sources were connected recently, the brief tells you its data is still building rather than reporting false problems. If no sources are connected, it says that too. Run the brief once the first sync and build have finished.

## Fixing what the brief finds

When an issue needs a change in GTM, ask your assistant to submit a tagging request for it. Maven stages the fix and runs QA, and you approve it before anything is published. See [Review and approve staged changes](https://mavendata.ai/docs/tag-management/approvals).

For a metric you want watched continuously, such as conversions dropping to zero, set up an alert instead. See [Budgets, goals and alerts](https://mavendata.ai/docs/getting-started/targets-and-alerts#create-an-alert).

## Related

- [Connect your tag manager and check tracking](https://mavendata.ai/docs/tag-management)
- [MCP operation reference: notification](https://mavendata.ai/docs/mcp/reference)

---

# Plans and pricing

> Maven is $500 a month per workspace, with the white-label client portal included. Agency accounts are billed at the per-client rate in their agreement.

Source: https://mavendata.ai/docs/account/plans

Maven is priced per **workspace**: one client or one brand, with their sources, portal, reports and tracking. The price is flat. It doesn't scale with ad spend and there are no seat counts.

| Part | Price | What you get |
|---|---|---|
| Each workspace | $500 a month per workspace | Unlimited data sources and destinations (conversions to Google Ads, Meta, LinkedIn, Microsoft Ads and ChatGPT ads, and BigQuery), the MCP for reports, decks and alerts, tracking audit and GTM changes you approve, server-side conversions under Consent Mode, and KPIs, goals, budgets and tracking alerts. |
| White-label portal | Included | A client portal on your own subdomain or custom domain, your logo, colours, brand theme and custom CSS, private share links and optional client MFA. |

## Common questions

**What counts as a workspace?** One client or one brand. Each workspace is kept separate from every other client.

**We're an agency. How is our account priced?** Agencies get per-client pricing for their whole roster. Agency accounts are billed at the per-client rate in their agreement. [Book a demo](https://mavendata.ai/demo) for a quote.

**Do you offer services or implementation?** Yes. Maven is built and run by [MetricMaven](https://www.metricmaven.io), which can also set up tracking and run Maven for an agency's clients under the agency's brand.

Machine-readable pricing: [/pricing.md](https://mavendata.ai/pricing.md). To get started, [start a 14-day trial](https://mavendata.ai/signup): free, no credit card. Prefer a walkthrough? [Book a demo](https://mavendata.ai/demo).

---
