> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.pivolio.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pivolio.com/_mcp/server. # Connect an AI assistant (MCP) Pivolio runs a [Model Context Protocol](https://modelcontextprotocol.io) server, so an AI assistant can answer questions about your data directly — "how did conversions trend last week?", "who are my most recent identified customers?", "is my Meta destination healthy?" — by reading it on your behalf. It is **read-only** and scoped to the workspaces you already have access to. Nothing an assistant does through it can change your configuration or send events. **Server URL** ``` https://api.pivolio.com/mcp ``` ## Connect it The first time you connect, you'll be sent to sign in to Pivolio and authorize the assistant — the same login you use for the dashboard. After that it stays connected. #### Claude (web & desktop) Open **Settings → Connectors → Add custom connector**, then paste the server URL: ``` https://api.pivolio.com/mcp ``` Claude opens a Pivolio sign-in window, you approve the access, and the Pivolio tools appear in your chats. #### Claude Code ```bash claude mcp add --transport http pivolio https://api.pivolio.com/mcp ``` The first tool call opens your browser to sign in and authorize. #### MCP Inspector For testing the connection directly: ```bash npx @modelcontextprotocol/inspector ``` Choose **Streamable HTTP**, enter `https://api.pivolio.com/mcp`, and connect. > **Note** > > Authorization uses standard OAuth 2.1 (PKCE) with dynamic client registration, so any > spec-compliant MCP client can connect without a pre-shared key — you never paste a > token. Access is a real sign-in, and you can revoke it from your identity provider. ## What it can do Every workspace belongs to an **account**, and your access spans all of your account's workspaces. Because of that, most tools take a `workspace_id` — so the assistant should call `list_workspaces` first to see which ids it can use. #### Pick a workspace `list_workspaces` returns every workspace you belong to, with your role in each. #### Ask about its data Every other tool takes that workspace's id and reads customers, events, reporting, attribution, or traffic quality. ### Available tools The assistant discovers this list automatically on connect; it's reproduced here for reference. | Tool | What it returns | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `list_workspaces` | Lists every workspace you belong to, each annotated with your role in it. | | `list_customers` | Returns a paginated list of resolved customers with search, segment and attribute filters, and sorting. | | `get_customer` | Returns a customer's full profile, including traits, resolved identifiers, and recent events. | | `get_customer_journey` | Returns the ordered marketing touchpoints and conversions for a single customer. | | `list_events` | Returns a paginated list of recorded events with filters, free-text search, and column sorting, including each event's delivery results. | | `get_event` | Returns the full detail for a single event, including its properties, consent snapshot, click IDs, and per-platform delivery results. | | `overview` | Returns headline KPIs and per-destination health for the overview page. | | `event_volume` | Returns event counts bucketed over the selected window, split into browse, intent, and conversion categories. | | `event_breakdown` | Returns event counts grouped by event name over the selected window. | | `top_pages` | Returns the most active page URLs ranked by event count over the selected window. | | `top_sources` | Returns the top UTM sources ranked by event count over the selected window. | | `person_stats` | Returns total person counts split into identified and anonymous. | | `delivery_stats` | Returns delivery counts grouped by platform and status over the selected window. | | `destination_delivery` | Returns a throughput time-series plus summary stats for one destination over the selected window. | | `destination_match_quality` | Returns the match-readiness score, signal coverage, trend, and recommendations for one destination. | | `attribution_report` | Returns attributed conversions and revenue broken down by the chosen dimension under one model. | | `attribution_compare` | Returns per-dimension conversions computed under all attribution models side by side. | | `journeys_report` | Returns the top conversion paths along with path-length and time-lag histograms. | | `traffic_quality_report` | Returns clean, suspicious, and flagged event volume with a reason breakdown over the selected window. | ## Permissions & data * **Read-only.** There are no tools that write, send events, or change settings. * **Scoped to your membership.** A tool call for a workspace you don't belong to is rejected — the assistant can't reach another account's data through your connection. * **Same roles as the dashboard.** What each tool can read follows your account role, and it's re-checked on every call, so removing your access takes effect immediately. ## Troubleshooting #### The assistant can't see any data / everything is empty Ask it to call `list_workspaces` first, then use one of those ids. Most tools need a `workspace_id`, and without one they have nothing to read. #### Sign-in fails or loops back to login Make sure you complete the Pivolio sign-in window the client opens and approve the access. If you were already signed in elsewhere, the whole thing is usually a single approval click. #### Connection is refused before any sign-in Confirm the URL is exactly `https://api.pivolio.com/mcp` and that your client uses the **Streamable HTTP** transport.