1.1.1 • Published 2 months agoCLI
gainsight-px-mcp-server
Licence
MIT
Version
1.1.1
Deps
1
Size
81 kB
Vulns
0
Weekly
7
Gainsight PX MCP Server
An MCP (Model Context Protocol) server that connects AI tools like Claude, Cursor, and Windsurf to the Gainsight PX REST API.
Query and manage your PX data — users, accounts, engagements, features, segments, events, surveys, and more — directly from your AI assistant.
Prerequisites
- Node.js 18 or later
- A Gainsight PX API key (how to generate one)
Quick Start
Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"gainsight-px": {
"command": "npx",
"args": ["-y", "gainsight-px-mcp"],
"env": {
"PX_API_KEY": "your-api-key-here"
}
}
}
}Claude Code
Add to your project's .mcp.json:
{
"mcpServers": {
"gainsight-px": {
"command": "npx",
"args": ["-y", "gainsight-px-mcp"],
"env": {
"PX_API_KEY": "your-api-key-here"
}
}
}
}Cursor
Add to your Cursor MCP settings:
{
"mcpServers": {
"gainsight-px": {
"command": "npx",
"args": ["-y", "gainsight-px-mcp"],
"env": {
"PX_API_KEY": "your-api-key-here"
}
}
}
}Configuration
| Environment Variable | Required | Default | Description |
|---|---|---|---|
PX_API_KEY |
Yes | — | Your Gainsight PX API key |
PX_ENV |
No | us |
Data center region (see table below) |
PX_API_BASE_URL |
No | — | Custom base URL — overrides PX_ENV if set |
Data Centers (PX_ENV)
| Value | Base URL |
|---|---|
us |
https://api.aptrinsic.com (default) |
us2 |
https://api-us2.aptrinsic.com |
eu |
https://api-eu.aptrinsic.com |
dev |
https://api-dev.aptrinsic.com |
EU example:
{
"env": {
"PX_API_KEY": "your-api-key-here",
"PX_ENV": "eu"
}
}Common Concepts
Filter Syntax
List tools support filtering with the format fieldName{operator}value. Pass multiple filters as an array — they are combined with AND logic.
| Operator | Description | Example |
|---|---|---|
== |
Equals | email==john@example.com |
!= |
Not equals | status!=INACTIVE |
< |
Less than | lastSeenDate<1700000000000 |
<= |
Less than or equal | score<=50 |
> |
Greater than | signUpDate>1700000000000 |
>= |
Greater than or equal | score>=80 |
~ |
Contains | email~@example.com |
!~ |
Does not contain | name!~test |
Pagination
Two modes are used depending on the resource:
- Scroll-based (users, accounts, events, surveys): The response includes a
scrollId. Pass it to the next call to get the next page. - Page-number-based (engagements, features, segments, KC bots): Use
pageSizeandpageNumber(0-indexed).
fetchAll — Auto-pagination
Set fetchAll: true to automatically paginate through all results without managing scrollId manually. Caps at 10,000 records or 50 pages. Defaults pageSize to 1,000 when enabled. Available on users, accounts, events, and surveys.
Aggregation
Available on tools that support fetchAll. Computes aggregations across all pages without holding all records in memory.
| Field | Type | Description |
|---|---|---|
operation |
"count" | "sum" |
Aggregation function |
field |
string | Field to sum (required for sum). Supports dot notation, e.g. attributes.statusCode |
groupBy |
string[] | Fields to group by. Supports dot notation, e.g. ["eventName", "identifyId"] |
CSV Export
All list and query tools support a csvExportPath parameter. When set, the server fetches the data from the PX API and writes it to a local CSV file on your machine (the PX API itself has no CSV export — this is implemented in the MCP server layer).
- Nested fields are flattened — e.g.
location.city,globalContext.role.adminbecome separate columns. - Arrays are JSON-stringified into a single column.
- Works with or without
fetchAll. Combine both to export all records at once. - Cannot be combined with
aggregation— aggregation returns summary data, not individual records.
The tool returns the normal response plus a csvExported object:
{
"csvExported": {
"exported": 1523,
"path": "/tmp/users.csv"
}
}Date Ranges
All date values are epoch milliseconds. The current day is always excluded from default ranges (e.g. "last 7 days" = 7 full days ending at midnight UTC today, not including today). If no dates are provided, defaults to yesterday. Maximum historical range for events: 190 days.
Example Prompts
This server is used through an AI assistant. You type natural language — the AI calls the right tool with the right parameters. Below are many examples organized by category.
Tip: Words like "all", "every", "complete list", "entire" trigger
fetchAll: trueand auto-paginate through all results. Without them, only the first page is returned.
Users
| What you type | What it does |
|---|---|
List my PX users |
Returns first page of users (25) |
List all my PX users |
Auto-paginates, returns all users |
Get every PX user |
Auto-paginates, returns all users |
Show me all users sorted by last seen date |
All users, sorted by lastSeenDate:desc |
Find the user with email john@example.com |
Filters by email==john@example.com |
Get user with identifyId abc-123 |
Fetches single user by ID |
List all users who signed up after January 2025 |
Filters by signUpDate>=<epoch ms> |
Show users from account acme-corp |
Filters by accountId==acme-corp |
How many users do I have in total? |
fetchAll + count aggregation |
How many users per account? |
fetchAll + count aggregation, groupBy accountId |
List all users sorted by number of visits descending |
fetchAll, sorted by numberOfVisits:desc |
Delete user with identifyId abc-123 |
Calls px_delete_user |
Create a user with email jane@example.com and identifyId jane-1 |
Calls px_create_user |
Update user abc-123, set their role to admin |
Calls px_update_user |
What custom attributes does the user model have? |
Calls px_get_model_attributes with type=user |
Accounts
| What you type | What it does |
|---|---|
List my PX accounts |
Returns first page of accounts (25) |
List all my PX accounts |
Auto-paginates, returns all accounts |
Get every account in PX |
Auto-paginates, returns all accounts |
Show all accounts sorted by name |
All accounts, sorted by name:asc |
Find account with ID acme-corp |
Fetches single account by ID |
List all accounts that contain "enterprise" in the name |
Filters by name~enterprise |
How many accounts do I have? |
fetchAll + count aggregation |
Show me accounts with a score above 80 |
Filters by score>=80 |
Delete account acme-corp |
Calls px_delete_account (cascading — also deletes associated users) |
Create an account with ID acme-corp and name Acme Corp |
Calls px_create_account |
What custom attributes does the account model have? |
Calls px_get_model_attributes with type=account |
Events
| What you type | What it does |
|---|---|
Show me pageView events from yesterday |
Queries pageView events, default date range |
Get all click events from last 7 days |
fetchAll for click events, 7-day range |
How many page views happened last week? |
fetchAll + count aggregation on pageView |
How many page views per user last month? |
fetchAll + count, groupBy identifyId |
Show page views grouped by account last 30 days |
fetchAll + count, groupBy accountId |
Get all identify events for user abc-123 |
Filters identify events by identifyId==abc-123 |
How many sessions were initialized last week? |
fetchAll + count on sessionInitialized |
Show me engagement views for engagement xyz |
Filters engagementView by engagement ID |
List all feature match events from this month |
fetchAll on feature_match for the month |
Get custom events named "app_error" from last 3 days |
px_get_custom_events with eventName=app_error |
Get all custom events from yesterday |
fetchAll on px_get_custom_events |
How many app_error events per user last week? |
fetchAll + count, groupBy identifyId, eventName=app_error |
What are the most common error status codes in app_error events? |
fetchAll + count, groupBy attributes.requestErrorStatusCode, eventName=app_error |
Create a custom event called "user_upgraded" for user abc-123 |
Calls px_create_custom_event |
Engagements
| What you type | What it does |
|---|---|
List my PX engagements |
Returns first page of engagements |
List all active engagements |
Filters by status==ACTIVE |
Show me all DIALOG engagements |
Filters by contentTypes=["DIALOG"] |
List all active guides |
Filters by contentTypes=["GUIDE"] and status==ACTIVE |
Get engagement with ID eng-123 |
Fetches single engagement |
Pause engagement eng-123 |
Calls px_set_engagement_state with state=PAUSE |
Start engagement eng-123 |
Calls px_set_engagement_state with state=START |
Delete engagement eng-123 |
Calls px_delete_engagement |
List engagements sorted by last updated date |
Sorted by lastUpdatedDate:desc |
Show all slider engagements that are paused |
contentTypes=["SLIDER"], status==PAUSED |
Features
| What you type | What it does |
|---|---|
List my PX features |
Returns first page of features |
List all features for product key prod-1 |
Filters by propertyKey=prod-1 |
Get feature with ID feat-123 |
Fetches single feature |
Show me adoption stats for feature feat-123 last month |
Calls px_get_feature_adoption with date range |
What's the adoption of feature feat-123 for product prod-1 last 30 days? |
Full adoption query |
Segments
| What you type | What it does |
|---|---|
List my PX segments |
Returns first page of segments |
Get segment with ID seg-123 |
Fetches single segment |
Knowledge Center
| What you type | What it does |
|---|---|
List my Knowledge Center bots |
Returns first page of KC bots |
List all KC bots for product prod-1 |
Filters by productId=prod-1 |
Get Knowledge Center bot kc-123 |
Fetches single KC bot |
Surveys
| What you type | What it does |
|---|---|
Show me survey responses from last week |
Returns first page of survey responses |
Get all survey responses from last month |
fetchAll on survey responses |
How many survey responses did I get last week? |
fetchAll + count aggregation |
Show survey responses sorted by date descending |
Sorted by date:desc |
Admin
| What you type | What it does |
|---|---|
Show my PX subscription details |
Calls px_get_subscription |
What fields does the user model have? |
Calls px_get_model_attributes with type=user |
What custom attributes exist on accounts? |
Calls px_get_model_attributes with type=account |
CSV Export
| What you type | What it does |
|---|---|
Export all users to /tmp/users.csv |
fetchAll + csvExportPath, writes all users to CSV |
Export all accounts to /tmp/accounts.csv |
fetchAll + csvExportPath, writes all accounts to CSV |
Save all pageView events from last week to /tmp/pageviews.csv |
fetchAll + csvExportPath on pageView events |
Export all click events from last 30 days to /tmp/clicks.csv |
fetchAll + csvExportPath on click events |
Export all custom events named app_error to /tmp/errors.csv |
fetchAll + eventName + csvExportPath |
Save all survey responses from last month to /tmp/surveys.csv |
fetchAll + csvExportPath on survey responses |
Export all active engagements to /tmp/engagements.csv |
filter status==ACTIVE + csvExportPath |
Save all features to /tmp/features.csv |
csvExportPath on feature list |
Export all segments to /tmp/segments.csv |
csvExportPath on segment list |
Export all KC bots to /tmp/kc_bots.csv |
csvExportPath on KC bot list |
Export users from account acme-corp to /tmp/acme_users.csv |
filter accountId==acme-corp + fetchAll + csvExportPath |
Export all users who signed up in 2025 to /tmp/signups_2025.csv |
filter signUpDate range + fetchAll + csvExportPath |
Save all identify events for user abc-123 to /tmp/user_events.csv |
filter identifyId + fetchAll + csvExportPath |
Tools Reference
Admin
px_get_subscription
Get PX subscription details for the authenticated account.
No parameters.
px_get_model_attributes
Get user or account model attributes (custom and standard fields).
| Parameter | Type | Required | Description |
|---|---|---|---|
type |
"user" | "account" |
Yes | Model type to retrieve attributes for |
Users
px_list_users
List PX users with optional filtering, sorting, and scroll-based pagination.
| Parameter | Type | Required | Description |
|---|---|---|---|
filter |
string[] | No | Filter expressions, e.g. ["email==john@example.com"] |
sort |
string | No | Sort field and direction, e.g. "lastSeenDate:desc" |
pageSize |
number | No | Results per page (default 25, max 1000) |
scrollId |
string | No | Scroll ID from previous response for next page |
fetchAll |
boolean | No | Auto-paginate through all results |
aggregation |
object | No | Server-side aggregation |
px_get_user
Get a single PX user by their identifyId.
| Parameter | Type | Required | Description |
|---|---|---|---|
identifyId |
string | Yes | The user's identifyId |
px_create_user
Create a new PX user. Required fields in userData: identifyId, propertyKeys (with at least one product ID).
| Parameter | Type | Required | Description |
|---|---|---|---|
userData |
object | Yes | User object JSON with identifyId, propertyKeys, etc. |
px_update_user
Update an existing PX user by identifyId.
| Parameter | Type | Required | Description |
|---|---|---|---|
identifyId |
string | Yes | The user's identifyId |
userData |
object | Yes | Fields to update |
px_delete_user
Delete a PX user by identifyId.
| Parameter | Type | Required | Description |
|---|---|---|---|
identifyId |
string | Yes | The user's identifyId |
Accounts
px_list_accounts
List PX accounts with optional filtering, sorting, and scroll-based pagination.
| Parameter | Type | Required | Description |
|---|---|---|---|
filter |
string[] | No | Filter expressions |
sort |
string | No | Sort field and direction, e.g. "name:asc" |
pageSize |
number | No | Results per page (default 25, max 1000) |
scrollId |
string | No | Scroll ID from previous response |
fetchAll |
boolean | No | Auto-paginate through all results |
aggregation |
object | No | Server-side aggregation |
px_get_account
Get a single PX account by ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
accountId |
string | Yes | The account ID |
px_create_account
Create a new PX account.
| Parameter | Type | Required | Description |
|---|---|---|---|
accountData |
object | Yes | Account object JSON with id, name, propertyKeys, etc. |
px_update_account
Update an existing PX account by ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
accountId |
string | Yes | The account ID |
accountData |
object | Yes | Fields to update |
px_delete_account
Delete a PX account by ID. Cascading delete — associated users are also deleted.
| Parameter | Type | Required | Description |
|---|---|---|---|
accountId |
string | Yes | The account ID |
Events
px_get_events
Query PX built-in events by type with filtering, sorting, and scroll-based pagination.
| Parameter | Type | Required | Description |
|---|---|---|---|
eventType |
enum | Yes | One of: pageView, identify, click, email, formSubmit, lead, sessionInitialized, segmentMatch, engagementView, feature_match |
filter |
string[] | No | Filter expressions |
sort |
string | No | Sort field and direction |
pageSize |
number | No | Results per page (default 25, max 1000) |
scrollId |
string | No | Scroll ID for next page |
dateRangeStart |
number | No | Start date as epoch ms (defaults to yesterday midnight UTC) |
dateRangeEnd |
number | No | End date as epoch ms (defaults to today midnight UTC, excluding today) |
fetchAll |
boolean | No | Auto-paginate through all results |
aggregation |
object | No | Supports groupBy on globalContext fields (e.g. globalContext.role.admin) and any top-level field (e.g. identifyId, accountId) |
px_get_custom_events
Query PX custom events with filtering, sorting, and scroll-based pagination.
| Parameter | Type | Required | Description |
|---|---|---|---|
eventName |
string | No | Filter to a specific custom event name (e.g. app_error). Required when grouping by attributes.* since attribute schemas differ between event types |
filter |
string[] | No | Filter expressions |
sort |
string | No | Sort field and direction |
pageSize |
number | No | Results per page (default 25, max 1000) |
scrollId |
string | No | Scroll ID for next page |
dateRangeStart |
number | No | Start date as epoch ms (defaults to yesterday midnight UTC) |
dateRangeEnd |
number | No | End date as epoch ms (defaults to today midnight UTC, excluding today) |
fetchAll |
boolean | No | Auto-paginate through all results |
aggregation |
object | No | Supports groupBy on globalContext fields, top-level fields (e.g. eventName, identifyId), and custom attributes (e.g. attributes.requestErrorStatusCode) |
px_create_custom_event
Create a custom event in PX.
| Parameter | Type | Required | Description |
|---|---|---|---|
eventData |
object | Yes | Custom event JSON with identifyId, propertyKey, eventName, date, attributes, etc. |
Engagements
px_list_engagements
List PX engagements with optional filtering, sorting, and page-based pagination.
| Parameter | Type | Required | Description |
|---|---|---|---|
contentTypes |
string[] | No | Filter by content types, e.g. ["DIALOG", "SLIDER", "GUIDE"] |
filter |
string[] | No | Filter expressions, e.g. ["status==ACTIVE"] |
sort |
string | No | Sort field and direction, e.g. "lastUpdatedDate:desc" |
pageSize |
number | No | Results per page (default 200, max 500) |
pageNumber |
number | No | Page number (0-indexed) |
px_get_engagement
Get a single PX engagement by ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
engagementId |
string | Yes | The engagement ID |
px_set_engagement_state
Start or pause a PX engagement.
| Parameter | Type | Required | Description |
|---|---|---|---|
engagementId |
string | Yes | The engagement ID |
state |
"START" | "PAUSE" |
Yes | Target state |
envs |
string[] | No | Environments to apply to |
px_delete_engagement
Delete a PX engagement by ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
engagementId |
string | Yes | The engagement ID |
Features
px_list_features
List PX features with page-based pagination.
| Parameter | Type | Required | Description |
|---|---|---|---|
pageSize |
number | No | Results per page (default 25, max 200) |
pageNumber |
number | No | Page number (0-indexed) |
propertyKey |
string | No | Filter by product ID |
px_get_feature
Get a single PX feature by ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
featureId |
string | Yes | The feature ID |
px_get_feature_adoption
Get feature adoption statistics for a given date range.
| Parameter | Type | Required | Description |
|---|---|---|---|
featureId |
string | Yes | The feature ID |
dateRangeStart |
number | Yes | Start date as epoch milliseconds |
dateRangeEnd |
number | No | End date as epoch milliseconds (defaults to now) |
propertyKey |
string | Yes | Product ID |
Segments
px_list_segments
List PX segments with page-based pagination.
| Parameter | Type | Required | Description |
|---|---|---|---|
pageSize |
number | No | Results per page (default 25, max 200) |
pageNumber |
number | No | Page number (0-indexed) |
px_get_segment
Get a single PX segment by ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
segmentId |
string | Yes | The segment ID |
Knowledge Center
px_list_kc_bots
List PX Knowledge Center bots with page-based pagination.
| Parameter | Type | Required | Description |
|---|---|---|---|
productId |
string | No | Filter by product ID |
pageSize |
number | No | Results per page |
pageNumber |
number | No | Page number (0-indexed) |
px_get_kc_bot
Get a single PX Knowledge Center bot by ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
kcId |
string | Yes | The Knowledge Center bot ID |
Surveys
px_get_survey_responses
Query PX survey response events with filtering, sorting, and scroll-based pagination.
| Parameter | Type | Required | Description |
|---|---|---|---|
filter |
string[] | No | Filter expressions |
sort |
string | No | Sort field and direction |
pageSize |
number | No | Results per page (default 25, max 1000) |
scrollId |
string | No | Scroll ID for next page |
dateRangeStart |
number | No | Start date as epoch ms |
dateRangeEnd |
number | No | End date as epoch ms |
fetchAll |
boolean | No | Auto-paginate through all results |
aggregation |
object | No | Server-side aggregation |
All Tools at a Glance
| Tool | Category | Operation |
|---|---|---|
px_get_subscription |
Admin | Get subscription info |
px_get_model_attributes |
Admin | Get user/account field definitions |
px_list_users |
Users | List with filter/sort/pagination |
px_get_user |
Users | Get by identifyId |
px_create_user |
Users | Create |
px_update_user |
Users | Update |
px_delete_user |
Users | Delete |
px_list_accounts |
Accounts | List with filter/sort/pagination |
px_get_account |
Accounts | Get by ID |
px_create_account |
Accounts | Create |
px_update_account |
Accounts | Update |
px_delete_account |
Accounts | Delete (cascading) |
px_get_events |
Events | Query built-in events by type |
px_get_custom_events |
Events | Query custom events |
px_create_custom_event |
Events | Create a custom event |
px_list_engagements |
Engagements | List with filter/sort/pagination |
px_get_engagement |
Engagements | Get by ID |
px_set_engagement_state |
Engagements | Start or pause |
px_delete_engagement |
Engagements | Delete |
px_list_features |
Features | List with pagination |
px_get_feature |
Features | Get by ID |
px_get_feature_adoption |
Features | Get adoption stats |
px_list_segments |
Segments | List with pagination |
px_get_segment |
Segments | Get by ID |
px_list_kc_bots |
Knowledge Center | List bots |
px_get_kc_bot |
Knowledge Center | Get bot by ID |
px_get_survey_responses |
Surveys | Query survey responses |
Rate Limits
The PX API enforces rate limits of approximately 200 requests per second and 1 million requests per day per subscription.
License
MIT