Ptengine MCP Server
Query your Ptengine data directly from AI assistants like Claude, ChatGPT, Codex, 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.
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 or contact your account manager.
Overview
The Ptengine MCP Server is a remote tool service built on the Model Context Protocol. 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:
Connect — add the Ptengine MCP Server to your AI client
Authorize — complete a one-time OAuth authorization in the browser (the same flow as signing in with Google or GitHub)
Ask — ask about your data in plain language; the AI picks the right tool automatically
Reuse — credentials are cached and renewed automatically, so future sessions just work
MCP Server 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
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
List-Profiles
List the profiles (sites) you can access
List-Catalog
Single entry point for profile-level catalogs; pick a catalog with kind
Get-Current-Account
Show which account the session is authorized as (whoami): account id, email, auth method, scopes
Supported kind values for List-Catalog:
pages
A profile's top pages by traffic (optionally filtered by URL keyword)
events
Event catalog (including business-term aliases)
event_properties
Event properties (for grouping / filtering by property)
user_properties
User properties (built-in + synced from CRM / data connectors)
experiences
A/B tests / engagements (including goals and versions)
goals
Combined catalog of goals and conversions
page_groups
Page groups (group id → name, as referenced by page-group conversions)
Tool changes: List-Pages, List-Events, List-Event-Properties, List-User-Properties, List-Experiences, and List-Goals have been consolidated into List-Catalog(kind=…). The old tools remain available (marked deprecated) for backward compatibility, but List-Catalog is recommended. List-Page-Groups has been removed — use List-Catalog(kind=page_groups) instead.
The standalone Get-User-Journey and Get-Experience-Report tools have also been removed; their capabilities are now the user_journey and experience_report query types of Run-Query (see the table below).
Supported Query Types (Run-Query)
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?"
experience_report
Whole-experiment totals for one test (not split by version, no lift), optionally sliced by one dimension
"How is test X doing overall? Show the trend by device"
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_journey
A single user's full cross-session, event-level journey
"What did this user do from start to finish?"
user_list
Search the user list (by name / email / userId) with paging and sorting
"Find the user with email xxx / who has been active lately?"
Permissions & Security
Read-only — queries only; no changing settings, creating tests, or modifying delivery
Least privilege — every tool currently requires just one scope:
query:readData 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
Official docs: Claude custom connectors guide (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.
On Team / Enterprise accounts, an organization Owner must add the connector first under Organization settings → Connectors; each member then clicks Connect to authorize.
Claude Code
Official docs: Claude Code MCP docs
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).
ChatGPT
Official docs: ChatGPT developer mode
Go to Settings → Security and login and turn on Developer mode (if the toggle is unavailable, ask your workspace admin)
Go to Settings → Plugins (or visit
chatgpt.com/plugins), click + to create a connector: set Name toPtengine, MCP Server URL tohttps://mcp.ptengine.com/open-api/v1/mcp, and Authentication to OAuthComplete the Ptengine OAuth flow in the browser (optionally, publish the connector to your workspace so teammates can add it directly)
Codex
Official docs: Codex MCP docs
Option A: from the UI
Go to Settings → MCP Servers → + Add Server, set Name to Ptengine, choose Streamable HTTP, enter https://mcp.ptengine.com/open-api/v1/mcp as the URL, and click Save.
Option B: from the config file
Edit ~/.codex/config.toml:
Save it, then authorize in the browser with:
Cursor
Official docs: Cursor MCP docs
Edit ~/.cursor/mcp.json (or create a new MCP server under Cursor Settings → Tools & Integrations):
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:
On the client's first call, the authorization endpoint is discovered and registered automatically (nothing for you to do)
The browser opens the Ptengine authorization page → you confirm the authorization
Back in the client, an access token is issued
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 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.
最終更新