> For the complete documentation index, see [llms.txt](https://docs.roivenue.com/roivenue-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roivenue.com/roivenue-resources/roivenue-mcp-connector-user-guide.md).
# Roivenue MCP connector — user guide
Connect Roivenue to your AI assistant and ask questions about your marketing performance in plain language. The connector (`roivenue-mcp`) is built on the open **Model Context Protocol (MCP)**, so it works with any MCP-compatible assistant — Claude, ChatGPT, Microsoft Copilot, and others. It provides access to the Roivenue data your own login can already see — performance metrics, attribution, customer journeys, data-source health — plus the Roivenue product documentation. It can also create a dashboard or a custom dimension in your Roivenue app, but only when you explicitly ask for one.
* **Server URL:** `https://mcp.dq.roivenue.com/mcp` (MCP, streamable HTTP)
* **Authentication:** OAuth 2.1 — you sign in with your own Roivenue credentials
* **Access:** read-only for your marketing data; the only writes are dashboard and custom-dimension creation (both on your explicit request) and an optional feedback tool
* **Privacy policy:**
* **Support:**
## Before you connect
* A **Roivenue account** — the same email and password you use to sign in to the Roivenue app (`app.roivenue.com`), with access to at least one Roivenue account.
* An **AI assistant that supports remote MCP connectors with OAuth** (check your assistant's plan and documentation).
The connector never uses a shared or administrative login: it acts as *you*, so it can only see the accounts and data your Roivenue permissions allow.
## Connect
1. Add the connector in your assistant's settings — in Claude, **Settings → Connectors → Roivenue** (or **Add custom connector** with the server URL above); in other MCP clients, add a remote MCP server with the same URL.
2. Your browser opens the Roivenue sign-in page. Log in with your Roivenue credentials and approve the connection.
3. Start a chat, make sure the Roivenue connector is enabled, and ask a question.
If your login has access to more than one Roivenue account, the assistant will list them and ask which one to explore. Everything after that is scoped to your choice.
To disconnect, remove the connector in your assistant's settings. The gateway supports token revocation, so an assistant that calls it on removal deletes the stored connection immediately; otherwise the stored session expires on its own. You can reconnect at any time by signing in again.
## What you can ask
Performance and attribution:
* *"How did my paid channels perform last month?"*
* *"Compare ROMI by platform for this quarter, using the AI Data Driven attribution model."*
* *"Which campaigns had spend but no attributed revenue in the last 30 days?"*
Customer journeys:
* *"What does a typical customer journey look like before a purchase?"*
* *"How often do Google Ads and Meta appear in the same converting path?"*
* *"How many days do customers take to convert?"*
Data health:
* *"When was my data last refreshed?"*
* *"Are any of my data sources failing?"*
Dashboards and custom dimensions:
* *"Create a dashboard with ROMI by platform and monthly revenue for this year."*
* *"Help me design a custom dimension that groups our traffic into paid search, paid social and organic — show me what it would look like before creating it."*
Product knowledge:
* *"What's the difference between last-touch and the AI Data Driven model in Roivenue?"*
* *"How does Roivenue handle cross-device journeys?"*
Answers use **your own Roivenue defaults** — the attribution model, currency, and date window you have selected in the Roivenue app — so the numbers match what you see there unless you ask for something different. Where it helps, the assistant can also hand you a **deep link that opens the exact Roivenue app page** with the same scope.
## Tools
All tools are read-only (annotated `readOnlyHint: true`) except three: `create_dashboard` and `create_custom_dimension`, which add a dashboard or a custom dimension to your own Roivenue app and run only on your explicit request, and `submit_feedback`, which appends a feedback record. No tool can modify or delete your marketing data.
### Roivenue documentation
| Tool | What it does |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Search knowledge base** (`search_knowledge`) | Searches Roivenue's product documentation and returns matching excerpts with their source paths. |
| **Read knowledge doc** (`read_doc`) | Reads the full text of one documentation page found by the search. |
### Account & setup
| Tool | What it does |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **List accounts** (`list_accounts`) | Lists the Roivenue accounts your login can access, so you can pick which one to explore. |
| **My settings** (`my_settings`) | Reads your Roivenue app defaults — attribution model, currency, date window, time granularity — so answers match what you see in the app. |
| **Account overview** (`account_overview`) | One-call orientation for a chosen account: its queryable measures, dimensions, attribution models, and connector health. |
| **Describe metrics** (`describe_metrics`) | The account's full queryable catalog: measures, dimensions, and attribution model codes. |
| **Account markets** (`account_markets`) | The account's markets with each one's reporting currency and data coverage. |
### Performance data
| Tool | What it does |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Query performance** (`query_performance`) | The core reporting query: aggregates measures (revenue, cost, ROMI, conversions, …) by dimensions over a date range, with attribution models, filters, currencies, and period comparisons. Results are capped at 150 rows. |
| **List dimension values** (`list_dimension_values`) | Lists the distinct values of a dimension (sites, platforms, conversion types, …) ranked by a measure. |
### Data health
| Tool | What it does |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Connector health** (`connector_health`) | Status of the account's data sources: active/inactive counts, coverage windows, failing sources with their last error. |
| **Data freshness** (`data_freshness`) | Per-pipeline refresh status: when each data job last completed, what's still processing, and any error with a fix hint. |
### Customer journeys (path analysis)
| Tool | What it does |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Path analysis KPIs** (`path_kpis`) | Journey KPIs: average path length, days to convert, attribution redistribution share, touchpoint-type mix. |
| **Path analysis histogram** (`path_histogram`) | Distribution of days-to-convert or touchpoints-to-convert across converting paths. |
| **Channel overlap** (`path_overlap`) | How often two or three channels appear in the same converting journeys (the channel-overlap Venn diagram from the Roivenue app). |
| **Customer journeys** (`path_journeys`) | The converting-path table: which journeys drive conversions, touch by touch, grouped by a dimension. |
| **Transaction history** (`transaction_history`) | The order/conversion list for a date range — one row per conversion with revenue figures. |
| **Conversion detail** (`conversion_detail`) | The full touchpoint journey behind one specific conversion. |
Journey and transaction tools **never return customer identifiers** — names, emails, and other customer-identifying columns are removed by design.
### Dashboards & custom dimensions
| Tool | What it does |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Create dashboard** (`create_dashboard`) | Creates a custom dashboard in your Roivenue app — KPI cards, charts, and tables over the metrics and dimensions you choose, with relative date windows so it stays current. Runs only when you explicitly ask for a dashboard; the result is private to you until you share it, and the assistant hands you the link to open it. |
| **Preview custom dimension** (`preview_custom_dimension`) | Designs and dry-runs a custom (derived) dimension draft against your live data — showing how much of your traffic each rule would catch, what stays unmatched, and any conflicting rules — **without writing anything**. Works for every role, so you can design a dimension and hand it to an account Operator. |
| **Create custom dimension** (`create_custom_dimension`) | Creates the previewed custom dimension and its rules in your Roivenue account. Runs only on your explicit request and requires the Operator role. It will not create while the account's data-refresh jobs are running (the assistant asks you to wait and retry), and at most 5 custom dimensions can be created per account per hour. Roivenue then recalculates the affected data (up to a year back), so numbers using the new dimension take a while to fill in — the assistant tells you and links you to the Dimensions page. |
### Utilities
| Tool | What it does |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Resolve date range** (`resolve_date_range`) | Turns a relative window ("year to date", "last 13 weeks") into the exact dates the Roivenue app's date picker would use. Today is always excluded, matching the app. |
| **Open in Explorer link** (`explorer_link`) | Builds a deep link that opens a page in the Roivenue app (`app.roivenue.com`) pre-scoped to the answer's account, dates, attribution model, and filters. |
| **Load task guidance** (`get_skill`) | Loads Roivenue-specific analysis guidance for the assistant (e.g. how to reconcile a number, or read path metrics). Fetches methodology text only — no customer data. |
### Feedback
| Tool | What it does |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Submit feedback** (`submit_feedback`) | Records a thumbs-up/-down on an answer, with an optional comment, so the Roivenue team can improve the connector. Writes only this feedback note — never your Roivenue data. |
## How your data is handled
* **Your permissions govern.** Every call runs with your own Roivenue login; the connector can never show you an account or a number your Roivenue access wouldn't.
* **Your marketing data is never modified.** No tool changes or deletes your Roivenue data. The write actions all happen only at your request and touch nothing else: `create_dashboard` adds a dashboard to your own app, `create_custom_dimension` adds a new dimension (your existing data and dimensions are untouched), and `submit_feedback` appends a feedback note.
* **Tokens are protected.** Your Roivenue access token is stored encrypted; your AI assistant only ever holds a connector-issued token, never your Roivenue credentials or token.
* **No customer PII in journey data.** Customer- and email-identifying fields are stripped from transaction and journey results before they leave Roivenue.
* **Operational audit log.** The connector keeps a log of tool calls (which tool, with which parameters) for reliability and support. It does not read your conversations, memory, or files in the assistant.
Full details: .
## Troubleshooting
* **"Please sign in again" / session expired.** Reconnect the connector in your assistant's settings — it re-runs the Roivenue login. Your chats are unaffected.
* **An account you expect is missing.** The connector only sees accounts your Roivenue login can access; ask your Roivenue administrator to grant access, then reconnect.
* **A number looks wrong or is unexpectedly zero.** Ask the assistant to double-check the attribution model and dimension it used — spend with zero attributed revenue usually means a different dimension or model than the app page you're comparing against. The assistant can list the valid options and re-query.
* **Data looks stale.** Ask *"when was my data last refreshed?"* — the freshness tools show per-source refresh times and any failing pipeline with a fix hint.
* **The assistant refused to create a custom dimension.** Either a data refresh is running right now (wait for it to finish — ask about data freshness — and retry) or the account hit the 5-per-hour creation limit.
* **Anything else:** .