> For the complete documentation index, see [llms.txt](https://helps.ptengine.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helps.ptengine.com/en/ai/mcp.md).

# Ptengine MCP Server

Query your Ptengine data directly from AI assistants like Claude, ChatGPT, and Cursor via the MCP protocol. No coding required — authorize once, then analyze PV/UV, funnels, user journeys, A/B tests, and more in plain language, right inside the conversation.

{% hint style="warning" %}
Ptengine MCP is being rolled out gradually — query access must be **enabled per profile**. If a profile doesn't have it enabled yet, queries return no data even after a successful MCP connection and authorization. To request access, [submit the request form](https://ptmafia.notion.site/44c6643a9819839da6c8811bebe54403) or contact your account manager.
{% endhint %}

## Overview

The Ptengine MCP Server is a remote tool service built on the [Model Context Protocol](https://modelcontextprotocol.io/). Once your AI client is connected, it gains access to a set of **read-only** analytics tools that bring your Ptengine account data into the conversation.

Getting started takes four steps:

1. **Connect** — add the Ptengine MCP Server to your AI client
2. **Authorize** — complete a one-time OAuth authorization in the browser (the same flow as signing in with Google or GitHub)
3. **Ask** — ask about your data in plain language; the AI picks the right tool automatically
4. **Reuse** — credentials are cached and renewed automatically, so future sessions just work

## MCP Server URL

|                    | URL                                        |
| ------------------ | ------------------------------------------ |
| **MCP Server URL** | `https://mcp.ptengine.com/open-api/v1/mcp` |

## Available Tools

Every tool is **read-only**. Tools return aggregated analytics results only and never modify any settings in your account.

**Query & Analysis**

| Tool               | Purpose                                                                 |
| ------------------ | ----------------------------------------------------------------------- |
| `Run-Query`        | Unified query entry point; routes to a specific analysis by `queryType` |
| `List-Query-Types` | List all supported query types with one-line summaries                  |
| `Get-Query-Schema` | Get the parameter specification for a given query type                  |

**Data Discovery**

| Tool                    | Purpose                                                             |
| ----------------------- | ------------------------------------------------------------------- |
| `List-Profiles`         | List the profiles (sites) you can access                            |
| `List-Pages`            | List a profile's top pages by traffic                               |
| `List-Events`           | List a profile's event catalog (including business-term aliases)    |
| `List-Event-Properties` | List event properties (for grouping / filtering by property)        |
| `List-User-Properties`  | List user properties (built-in + synced from CRM / data connectors) |
| `List-Experiences`      | List A/B tests / engagements (including goals and versions)         |

**Single User & Reports**

| Tool                    | Purpose                                                                                                                                   |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `Get-User-Journey`      | View a single user's cross-session journey (summaries of the 20 most recent sessions)                                                     |
| `Get-Experience-Report` | Full report for one A/B test: impression / click / submission users, conversion rates, time on page, bounce, and attainment for each goal |

### Supported Query Types (`Run-Query`)

| queryType                      | Purpose                                                                                                                                                 | Example prompt                                                                        |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `page_insight`                 | Break down a single page's metrics by one dimension (device / source / visit type / UTM / by day / by week)                                             | "Break it down by device / source / day"                                              |
| `page_block_metrics`           | Block-level heatmap metrics for one page (impressions / exits / time), bucketed by device                                                               | "Impressions and exits for each above-the-fold block"                                 |
| `experience_abtest_report`     | Version × goal results plus lift for one A/B test; can be split by dimension                                                                            | "How much did test X lift conversions? Which version won on mobile?"                  |
| `experiment_attributed_funnel` | Attributed impact of a set of tests on an event funnel (first / last / all)                                                                             | "How did tests A/B/C move the sign-in → purchase funnel?"                             |
| `traffic_insight`              | Sitewide baseline performance: 12 fixed metrics (visits, new-visitor rate, bounce, time, PV, clicks, exits, etc.), optionally split by one dimension    | "How did the whole site do over the last 30 days? Split by source"                    |
| `event_insight`                | Event-level behavior: trigger count, unique users, conversion rate; aggregate event properties (sum / average, etc.); optionally split by one dimension | "How many add-to-cart events in the last 7 days, by how many users? Split by channel" |
| `funnel_insight`               | Ordered event funnel: step-by-step conversion and drop-off, average time per step; optionally split by one dimension                                    | "Where does the view → add-to-cart → purchase funnel leak?"                           |
| `path_insight`                 | In-session path flow anchored on a page or event (where users went next / came from)                                                                    | "Where did users go after viewing this page?"                                         |
| `page_transitions`             | Unanchored page-to-page transition edges (which pages feed traffic to each other)                                                                       | "Show me how pages link to each other across the site"                                |
| `page_element_metrics`         | Element-level impressions / clicks / click rate plus goal conversions for one page                                                                      | "Click rate and conversions for each element on the page"                             |
| `experience_search`            | Search the test catalog (by name keyword / status / creation time); returns name + id + status                                                          | "Find tests with X in the name / which tests are running?"                            |
| `user_overview`                | Profile overview for a single user                                                                                                                      | "Who is this user? Give me an overview"                                               |
| `user_timeline`                | A single user's recent activity timeline (summaries of the 20 most recent sessions)                                                                     | "What has this user been doing lately?"                                               |
| `user_session_detail`          | The event sequence within one of a user's sessions                                                                                                      | "What exactly did this user do during that visit?"                                    |
| `user_benchmark`               | Compare a single user against the sitewide benchmark                                                                                                    | "How does this user compare to the site average?"                                     |

## Permissions & Security

* **Read-only** — queries only; no changing settings, creating tests, or modifying delivery
* **Least privilege** — every tool currently requires just one scope: `query:read`
* **Data scope** — the AI sees only **the profiles your account already has access to**; MCP never expands your permissions
* **Per-user authorization** — tokens are bound to your account, so don't share them; have each teammate authorize individually

## Connecting

### Claude Code

Official docs: [Claude Code MCP docs](https://code.claude.com/docs/en/mcp)

```bash
claude mcp add ptengine --transport http https://mcp.ptengine.com/open-api/v1/mcp
```

Then run `/mcp` inside Claude Code and complete the Ptengine OAuth flow in your browser (the authorization page also opens automatically on the first tool call).

### Claude

Official docs: [Claude custom connectors guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) (the steps are the same in the web and desktop apps)

Go to **Settings → Connectors → Add custom connector**, set Name to `Ptengine` and URL to `https://mcp.ptengine.com/open-api/v1/mcp`, then click **Connect** and complete authorization in the browser.

{% hint style="info" %}
On Team / Enterprise accounts, an organization Owner must add the connector first under **Organization settings → Connectors**; each member then clicks **Connect** to authorize.
{% endhint %}

### ChatGPT

Official docs: [ChatGPT developer mode](https://developers.openai.com/api/docs/guides/developer-mode)

1. Go to **Settings → Security and login** and turn on **Developer mode** (if the toggle is unavailable, ask your workspace admin)
2. Go to **Settings → Plugins** (or visit `chatgpt.com/plugins`), click **+** to create a connector: set Name to `Ptengine`, MCP Server URL to `https://mcp.ptengine.com/open-api/v1/mcp`, and Authentication to **OAuth**
3. Complete the Ptengine OAuth flow in the browser (optionally, publish the connector to your workspace so teammates can add it directly)

### Cursor

Official docs: [Cursor MCP docs](https://cursor.com/docs/mcp)

Edit `~/.cursor/mcp.json` (or create a new MCP server under Cursor Settings → **Tools & Integrations**):

```json
{
  "mcpServers": {
    "ptengine": {
      "url": "https://mcp.ptengine.com/open-api/v1/mcp",
      "transport": "http"
    }
  }
}
```

Save, restart Cursor, then click **Login** next to Ptengine under **Tools & Integrations** (or trigger it via the first tool call) and complete authorization in the browser.

## How Authorization Works

Ptengine MCP uses standard **OAuth 2.0 + PKCE**, the same flow as mainstream SaaS products:

1. On the client's first call, the authorization endpoint is discovered and registered automatically (nothing for you to do)
2. The browser opens the Ptengine authorization page → you confirm the authorization
3. Back in the client, an access token is issued
4. Tokens are short-lived and renewed automatically before expiry — no repeated authorization needed

## Example Prompts

* **"Show me how <https://example.com/landing> performed over the past week"** → returns the page's PV/UV, bounce rate, conversions, and more
* **"Break it down by traffic source"** → splits the same page's metrics by source for comparison
* **"PV trend over the past 30 days"** → returns a day-by-day time series
* **"How are my top 5 pages doing over the last 30 days?"** → lists the top pages by traffic first, then queries and compares each
* **"How is test X performing?"** → finds the matching A/B test, then returns its full report

## Troubleshooting

* **Connected and authorized successfully, but queries return no data** — check that MCP query access has been enabled for the profile (it's being rolled out gradually; [submit the request form](https://ptmafia.notion.site/44c6643a9819839da6c8811bebe54403) or contact your account manager to enable it).
* **Authorization spins forever / redirect fails** — clear the client's auth cache and retry: for Claude Code run `rm -rf ~/.claude/mcp-auth/ptengine`; for Cursor, quit the app and delete `~/.cursor/mcp-auth/`.
* **Calls return 401** — the token expired and renewal failed; trigger authorization once more.
* **Calls return 403 `insufficient_scope`** — a permission checkbox was unchecked during authorization; re-authorize with the permission checked.
* **A profile is missing** — confirm your Ptengine account itself has access to that profile; MCP never expands permissions.
* **Can my teammates use it?** — each person authorizes individually. Don't share tokens; have them complete their own OAuth flow.