# MCP Server URL: https://pieowl.com/docs/mcp Pieowl runs an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server. It lets AI assistants like Claude, Cursor and Windsurf query your analytics data right in the conversation. This is how you ask questions about your data: there is no chat inside Pieowl. The server is hosted, so there is nothing to install, and it shows up in your client as **Pieowl**. Endpoint [#endpoint] ``` https://api.pieowl.com/mcp ``` Authentication [#authentication] Pass the token in an `Authorization` header: ``` Authorization: Bearer YOUR_TOKEN ``` If your client can't set headers, pass it as a query parameter instead: ``` https://api.pieowl.com/mcp?token=YOUR_TOKEN ``` Both work. Prefer the header: query strings end up in browser history, shell history and proxy logs, so a token in the URL is easier to leak by accident. Token format [#token-format] The token is your client ID and client secret, joined by a colon and **base64-encoded**: ``` base64(clientId:clientSecret) ``` From the dashboard [#from-the-dashboard] The easiest way to get your MCP token is from the dashboard, no terminal needed: * **AI assistants** — in **Settings → Developers → AI assistants**, pick your client (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code or Raycast) and click **Create token**. Pieowl makes a read-data key for the site and puts the token straight into a ready-made config. Copy it right away: it is shown only once. * **New key** — when you create a read-data key in **Settings → Developers → Keys**, the success screen shows a **Token for AI assistants** field ready to copy. Use **Download** to save your key ID, secret and token as `credentials.txt`. From the terminal [#from-the-terminal] ```bash echo -n "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" | base64 ``` Then send it with every request: ``` Authorization: Bearer ``` Or, for clients that can't set headers, add it to the MCP URL: ``` https://api.pieowl.com/mcp?token= ``` Required client type [#required-client-type] Only `read` and `root` clients can use MCP. Write-only clients are rejected. | Client type | Access | | ----------- | ---------------------------------------- | | `read` | One site (the one the client belongs to) | | `root` | Any site in your team | Use a `read` client to limit the AI assistant to one site. Use a `root` client if you need access across sites or want to list all sites. Create keys in **Settings → Developers** in your dashboard. See the [Authentication guide](/docs/api/authentication) for details. Connecting to Claude Desktop [#connecting-to-claude-desktop] Add this to your `claude_desktop_config.json`: ```json { "mcpServers": { "pieowl": { "type": "streamable-http", "url": "https://api.pieowl.com/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } } ``` If your client doesn't read `headers`, drop that block and put the token in the URL instead: `"url": "https://api.pieowl.com/mcp?token=YOUR_TOKEN"`. Connecting with Claude Code CLI [#connecting-with-claude-code-cli] Use the `--header` flag to pass the token as `Authorization: Bearer`: ```bash claude mcp add --transport http pieowl https://api.pieowl.com/mcp \ --header "Authorization: Bearer YOUR_TOKEN" ``` Or with the token in the URL: ```bash claude mcp add --transport http pieowl "https://api.pieowl.com/mcp?token=YOUR_TOKEN" ``` Connecting to Cursor [#connecting-to-cursor] Add this to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (one project): ```json { "mcpServers": { "pieowl": { "url": "https://api.pieowl.com/mcp", "transport": "streamable-http", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } } ``` For other clients, copy the config from **Settings → Developers → AI assistants** in your dashboard. Available tools [#available-tools] Site access [#site-access] | Tool | Description | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_projects` | List all sites your credentials can access, with their site IDs (`projectId`). Root clients see every site in the team; read clients see only their own. | | `get_dashboard_urls` | Get dashboard links for the current site — overview, events, profiles, sessions, and deep links to specific items. | Dashboards & reports [#dashboards--reports] | Tool | Description | | ----------------- | --------------------------------------------------------------------------- | | `list_dashboards` | List all dashboards for a site. | | `get_dashboard` | Get a dashboard with its full report settings and saved layouts. | | `list_reports` | List all reports in a dashboard with their chart types and tracked events. | | `get_report_data` | Run a saved report and return its data (time series, funnel, metric, etc.). | Dashboard management (root clients) [#dashboard-management-root-clients] | Tool | Description | | ------------------------ | ----------------------------------------------------------------------------- | | `create_dashboard` | Create a dashboard for a site. | | `update_dashboard` | Rename a dashboard. | | `delete_dashboard` | Delete an empty dashboard, or delete it with its reports using `forceDelete`. | | `create_report` | Add a saved chart to a dashboard. | | `update_report` | Replace a saved chart's settings. | | `delete_report` | Delete a saved chart. | | `duplicate_report` | Duplicate a saved chart in its dashboard. | | `update_report_layout` | Set a saved chart's grid position and size on the dashboard. | | `reset_dashboard_layout` | Remove all saved chart layouts from a dashboard. | Discovery [#discovery] | Tool | Description | | --------------------------- | -------------------------------------------------------------------------------------------------------- | | `list_event_names` | Get the 50 most common event names on the site. Call this first if you don't know the exact event names. | | `list_event_properties` | List all property keys tracked for an event (or across all events). | | `get_event_property_values` | Get all distinct values for one event property. | Events & sessions [#events--sessions] | Tool | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `query_events` | Query raw events with optional filters. Returns single records with path, device, country, referrer and custom properties. | | `query_sessions` | Query sessions with optional filters. Each session includes duration, entry and exit pages, bounce status and attribution data. | Profiles (users) [#profiles-users] | Tool | Description | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `find_profiles` | Search and filter user profiles by name, email, location, inactivity, session count, or whether they did a specific event. | | `get_profile` | Get one user profile with their most recent events. | | `get_profile_sessions` | Get all sessions for a user profile, newest first. | | `get_profile_metrics` | Get lifetime metrics for a user: sessions, page views, bounce rate, revenue and more. | Groups (B2B) [#groups-b2b] | Tool | Description | | ------------------ | -------------------------------------------------------------------------------------------- | | `list_group_types` | List all group types on the site (e.g. `company`, `team`). Call this before querying groups. | | `find_groups` | Search for groups by name, ID or type. | | `get_group` | Get one group with its properties and member profiles. | Aggregated metrics [#aggregated-metrics] | Tool | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------- | | `get_analytics_overview` | Key metrics for a date range: visitors, page views, sessions, bounce rate and average session duration. | | `get_rolling_active_users` | Active users over time with a rolling window: daily (DAU), weekly (WAU) or monthly (MAU). | | `get_top_pages` | Most visited pages, ranked by page views. | | `get_page_performance` | Bounce rate, average session duration, sessions and page views per page. | | `get_page_conversions` | Pages ranked by how many visitors went on to convert after viewing them. | | `get_entry_exit_pages` | Most common entry pages (session start) or exit pages (session end). | | `get_top_referrers` | Top traffic sources by referrer name and type. | | `get_country_breakdown` | Visitor counts by country, region or city. | | `get_device_breakdown` | Visitor counts by device type, browser or OS. | User behavior [#user-behavior] | Tool | Description | | --------------------------------- | ------------------------------------------------------------------------------------------------------ | | `get_funnel` | Analyze a conversion funnel between 2 or more events — sign-up flows, checkout, onboarding. | | `get_retention_cohort` | Weekly retention cohort table that shows how well users stick around. | | `get_weekly_retention_series` | Week-over-week retention as a time series. | | `get_user_last_seen_distribution` | How recently users were last active, grouped into fresh, stale and churned. Useful for churn analysis. | | `get_user_flow` | User navigation flows as a Sankey diagram (before, after or between events). | Google Search Console [#google-search-console] These tools need Google Search Console connected for the site. Connect it in the dashboard on the **Google search** page. | Tool | Description | | ----------------------------- | -------------------------------------------------------------------------------- | | `gsc_get_overview` | Search performance over time: clicks, impressions, CTR and average position. | | `gsc_get_top_pages` | Top pages from Search Console, ranked by clicks. | | `gsc_get_page_details` | Search performance for one page, including all queries that bring traffic to it. | | `gsc_get_top_queries` | Top search queries, ranked by clicks. | | `gsc_get_query_opportunities` | Quick SEO wins: queries ranking 4–20 with meaningful search volume. | | `gsc_get_query_details` | Data for one search query, with every page that ranks for it. | | `gsc_get_cannibalization` | Queries where several of your pages compete with each other in Google. | Rate limiting [#rate-limiting] 60 requests per minute, counted per IP address.