gainsight-px-mcp 1.0.0

package/README.md

@@ -0,0 +1,180 @@
+# Gainsight PX MCP Server
+
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that connects AI tools like Claude, Cursor, and Windsurf to the [Gainsight PX REST API](https://support.gainsight.com/PX/API_for_Developers/Use_the_PX_REST_API).
+
+Query and manage your PX data — users, accounts, engagements, features, segments, events, and more — directly from your AI assistant.
+
+## Prerequisites
+
+- Node.js 18 or later
+- A Gainsight PX API key ([how to generate one](https://support.gainsight.com/PX/API_for_Developers/Use_the_PX_REST_API#Generate_an_API_Key))
+
+## Quick Start
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "gainsight-px": {
+      "command": "npx",
+      "args": ["-y", "@gainsight/px-mcp-server"],
+      "env": {
+        "PX_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "gainsight-px": {
+      "command": "npx",
+      "args": ["-y", "@gainsight/px-mcp-server"],
+      "env": {
+        "PX_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to your Cursor MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "gainsight-px": {
+      "command": "npx",
+      "args": ["-y", "@gainsight/px-mcp-server"],
+      "env": {
+        "PX_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Environment Variable | Required | Default | Description |
+|---------------------|----------|---------|-------------|
+| `PX_API_KEY` | Yes | — | Your Gainsight PX API key |
+| `PX_API_BASE_URL` | No | `https://api.aptrinsic.com` | API base URL for your data center |
+
+### Data Centers
+
+| Region | Base URL |
+|--------|----------|
+| US | `https://api.aptrinsic.com` (default) |
+| EU | `https://api-eu.aptrinsic.com` |
+| US2 | `https://api-us2.aptrinsic.com` |
+
+If your PX instance is in EU or US2, set the `PX_API_BASE_URL` environment variable accordingly.
+
+## Available Tools
+
+### Users
+| Tool | Description |
+|------|-------------|
+| `px_list_users` | List users with filtering, sorting, and pagination |
+| `px_get_user` | Get a user by identifyId |
+| `px_create_user` | Create a new user |
+| `px_update_user` | Update a user |
+| `px_delete_user` | Delete a user |
+
+### Accounts
+| Tool | Description |
+|------|-------------|
+| `px_list_accounts` | List accounts with filtering, sorting, and pagination |
+| `px_get_account` | Get an account by ID |
+| `px_create_account` | Create a new account |
+| `px_update_account` | Update an account |
+| `px_delete_account` | Delete an account |
+
+### Engagements
+| Tool | Description |
+|------|-------------|
+| `px_list_engagements` | List engagements with optional content type filter |
+| `px_get_engagement` | Get an engagement by ID |
+| `px_set_engagement_state` | Start or pause an engagement |
+| `px_delete_engagement` | Delete an engagement |
+
+### Features
+| Tool | Description |
+|------|-------------|
+| `px_list_features` | List features |
+| `px_get_feature` | Get a feature by ID |
+| `px_get_feature_adoption` | Get feature adoption statistics |
+
+### Segments
+| Tool | Description |
+|------|-------------|
+| `px_list_segments` | List segments |
+| `px_get_segment` | Get a segment by ID |
+
+### Events
+| Tool | Description |
+|------|-------------|
+| `px_get_events` | Query events by type (pageView, identify, click, email, formSubmit, lead, sessionInitialized, segmentMatch, engagementView, feature_match) |
+| `px_get_custom_events` | Query custom events |
+| `px_create_custom_event` | Create a custom event |
+
+### Survey
+| Tool | Description |
+|------|-------------|
+| `px_get_survey_responses` | Query survey responses |
+
+### Knowledge Center
+| Tool | Description |
+|------|-------------|
+| `px_list_kc_bots` | List Knowledge Center bots |
+| `px_get_kc_bot` | Get a Knowledge Center bot by ID |
+
+### Admin
+| Tool | Description |
+|------|-------------|
+| `px_get_subscription` | Get subscription details |
+| `px_get_model_attributes` | Get user or account model attributes |
+
+## Filtering and Pagination
+
+### Filter Syntax
+
+List tools support filtering with the format `fieldName{operator}fieldValue`:
+
+| 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 (like) | `email~@example.com` |
+| `!~` | Does not contain | `name!~test` |
+
+Pass multiple filters as an array — they are combined with AND logic.
+
+### Pagination
+
+- **Users, Accounts, Events**: Scroll-based — use the `scrollId` from the response to fetch the next page.
+- **Engagements, Features, Segments, KC Bots**: Page-number-based — use `pageSize` and `pageNumber` (0-indexed).
+
+## Rate Limits
+
+The PX API enforces rate limits of approximately 200 requests per second and 1 million requests per day per subscription.
+
+## License
+
+MIT

package/dist/__tests__/config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/config.test.js

@@ -0,0 +1,30 @@
+import { describe, it, expect, afterEach } from "vitest";
+describe("config", () => {
+    const originalEnv = { ...process.env };
+    afterEach(() => {
+        process.env = { ...originalEnv };
+        // Clear module cache so config re-reads env vars
+    });
+    it("validateConfig throws when PX_API_KEY is missing", async () => {
+        delete process.env.PX_API_KEY;
+        // Dynamic import to get fresh module with current env
+        const { validateConfig, config } = await import("../config.js?" + Date.now());
+        config.apiKey = "";
+        expect(() => validateConfig()).toThrow("PX_API_KEY environment variable is required");
+    });
+    it("validateConfig passes when PX_API_KEY is set", async () => {
+        const { validateConfig, config } = await import("../config.js?" + Date.now());
+        config.apiKey = "test-key";
+        expect(() => validateConfig()).not.toThrow();
+    });
+    it("defaults baseUrl to US data center", async () => {
+        delete process.env.PX_API_BASE_URL;
+        const { config } = await import("../config.js?" + Date.now());
+        expect(config.baseUrl).toBe("https://api.aptrinsic.com");
+    });
+    it("strips trailing slash from baseUrl", async () => {
+        process.env.PX_API_BASE_URL = "https://api-eu.aptrinsic.com/";
+        const { config } = await import("../config.js?" + Date.now());
+        expect(config.baseUrl).not.toMatch(/\/$/);
+    });
+});

package/dist/__tests__/http-client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/http-client.test.js

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "vitest";
+import { buildUrl, formatError, jsonResult } from "../http-client.js";
+describe("buildUrl", () => {
+    const base = "https://api.aptrinsic.com";
+    it("builds a simple path", () => {
+        expect(buildUrl(base, "/v1/users")).toBe("https://api.aptrinsic.com/v1/users");
+    });
+    it("appends scalar query params", () => {
+        const url = buildUrl(base, "/v1/users", { pageSize: 25, sort: "name:asc" });
+        const parsed = new URL(url);
+        expect(parsed.searchParams.get("pageSize")).toBe("25");
+        expect(parsed.searchParams.get("sort")).toBe("name:asc");
+    });
+    it("appends array query params (multiple filter values)", () => {
+        const url = buildUrl(base, "/v1/users", {
+            filter: ["email==a@b.com", "name~test"],
+        });
+        const parsed = new URL(url);
+        expect(parsed.searchParams.getAll("filter")).toEqual(["email==a@b.com", "name~test"]);
+    });
+    it("skips undefined params", () => {
+        const url = buildUrl(base, "/v1/users", { pageSize: 10, scrollId: undefined });
+        const parsed = new URL(url);
+        expect(parsed.searchParams.get("pageSize")).toBe("10");
+        expect(parsed.searchParams.has("scrollId")).toBe(false);
+    });
+    it("works with EU data center base URL", () => {
+        expect(buildUrl("https://api-eu.aptrinsic.com", "/v1/accounts")).toBe("https://api-eu.aptrinsic.com/v1/accounts");
+    });
+    it("handles encoded path params", () => {
+        const id = encodeURIComponent("user@example.com");
+        const url = buildUrl(base, `/v1/users/${id}`);
+        expect(url).toContain("user%40example.com");
+    });
+});
+describe("formatError", () => {
+    it("returns auth message for 401", () => {
+        expect(formatError(401, "Unauthorized")).toContain("Authentication failed");
+    });
+    it("returns rate limit message for 429", () => {
+        expect(formatError(429, "Too many requests")).toContain("Rate limit exceeded");
+    });
+    it("returns not found message for 404", () => {
+        expect(formatError(404, "Not found")).toContain("Resource not found");
+    });
+    it("returns generic message for other status codes", () => {
+        expect(formatError(500, { error: "Internal" })).toContain("API error 500");
+    });
+    it("stringifies object error data", () => {
+        expect(formatError(500, { message: "fail" })).toContain('"message":"fail"');
+    });
+    it("includes string error data as-is", () => {
+        expect(formatError(401, "Bad key")).toContain("Bad key");
+    });
+});
+describe("jsonResult", () => {
+    it("wraps data as MCP text content", () => {
+        const result = jsonResult({ name: "test" });
+        expect(result.content).toHaveLength(1);
+        expect(result.content[0].type).toBe("text");
+        expect(JSON.parse(result.content[0].text)).toEqual({ name: "test" });
+    });
+    it("pretty-prints JSON", () => {
+        const result = jsonResult({ a: 1 });
+        expect(result.content[0].text).toContain("\n");
+    });
+});

package/dist/__tests__/server.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/server.test.js

@@ -0,0 +1,57 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerUserTools } from "../tools/users.js";
+import { registerAccountTools } from "../tools/accounts.js";
+import { registerEngagementTools } from "../tools/engagements.js";
+import { registerFeatureTools } from "../tools/features.js";
+import { registerSegmentTools } from "../tools/segments.js";
+import { registerEventTools } from "../tools/events.js";
+import { registerSurveyTools } from "../tools/survey.js";
+import { registerKnowledgeCenterTools } from "../tools/knowledge-center.js";
+import { registerAdminTools } from "../tools/admin.js";
+describe("tool registration", () => {
+    let server;
+    beforeEach(() => {
+        server = new McpServer({ name: "test", version: "0.0.0" });
+    });
+    it("registers user tools without error", () => {
+        expect(() => registerUserTools(server)).not.toThrow();
+    });
+    it("registers account tools without error", () => {
+        expect(() => registerAccountTools(server)).not.toThrow();
+    });
+    it("registers engagement tools without error", () => {
+        expect(() => registerEngagementTools(server)).not.toThrow();
+    });
+    it("registers feature tools without error", () => {
+        expect(() => registerFeatureTools(server)).not.toThrow();
+    });
+    it("registers segment tools without error", () => {
+        expect(() => registerSegmentTools(server)).not.toThrow();
+    });
+    it("registers event tools without error", () => {
+        expect(() => registerEventTools(server)).not.toThrow();
+    });
+    it("registers survey tools without error", () => {
+        expect(() => registerSurveyTools(server)).not.toThrow();
+    });
+    it("registers knowledge center tools without error", () => {
+        expect(() => registerKnowledgeCenterTools(server)).not.toThrow();
+    });
+    it("registers admin tools without error", () => {
+        expect(() => registerAdminTools(server)).not.toThrow();
+    });
+    it("registers all 27 tools together without error", () => {
+        expect(() => {
+            registerUserTools(server);
+            registerAccountTools(server);
+            registerEngagementTools(server);
+            registerFeatureTools(server);
+            registerSegmentTools(server);
+            registerEventTools(server);
+            registerSurveyTools(server);
+            registerKnowledgeCenterTools(server);
+            registerAdminTools(server);
+        }).not.toThrow();
+    });
+});

package/dist/config.d.ts

@@ -0,0 +1,5 @@
+export declare const config: {
+    apiKey: string;
+    baseUrl: string;
+};
+export declare function validateConfig(): void;

package/dist/config.js

@@ -0,0 +1,9 @@
+export const config = {
+    apiKey: process.env.PX_API_KEY || "",
+    baseUrl: (process.env.PX_API_BASE_URL || "https://api-staging.aptrinsic.com").replace(/\/$/, ""),
+};
+export function validateConfig() {
+    if (!config.apiKey) {
+        throw new Error("PX_API_KEY environment variable is required");
+    }
+}

package/dist/http-client.d.ts

@@ -0,0 +1,14 @@
+interface ApiResponse {
+    status: number;
+    data: unknown;
+}
+export declare function buildUrl(baseUrl: string, path: string, queryParams?: Record<string, string | string[] | number | undefined>): string;
+export declare function formatError(status: number, data: unknown): string;
+export declare function pxApi(method: string, path: string, queryParams?: Record<string, string | string[] | number | undefined>, body?: unknown): Promise<ApiResponse>;
+export declare function jsonResult(data: unknown): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+};
+export {};

package/dist/http-client.js

@@ -0,0 +1,58 @@
+import { config } from "./config.js";
+export function buildUrl(baseUrl, path, queryParams) {
+    const url = new URL(baseUrl + path);
+    if (queryParams) {
+        for (const [key, value] of Object.entries(queryParams)) {
+            if (value === undefined)
+                continue;
+            if (Array.isArray(value)) {
+                for (const v of value) {
+                    url.searchParams.append(key, v);
+                }
+            }
+            else {
+                url.searchParams.set(key, String(value));
+            }
+        }
+    }
+    return url.toString();
+}
+export function formatError(status, data) {
+    const msg = status === 401
+        ? "Authentication failed — check PX_API_KEY"
+        : status === 429
+            ? "Rate limit exceeded — try again later"
+            : status === 404
+                ? "Resource not found"
+                : `API error ${status}`;
+    return `${msg}: ${typeof data === "string" ? data : JSON.stringify(data)}`;
+}
+export async function pxApi(method, path, queryParams, body) {
+    const url = buildUrl(config.baseUrl, path, queryParams);
+    const headers = {
+        "X-APTRINSIC-API-KEY": config.apiKey,
+        "Content-Type": "application/json",
+    };
+    const res = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    let data;
+    const text = await res.text();
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        data = text;
+    }
+    if (!res.ok) {
+        throw new Error(formatError(res.status, data));
+    }
+    return { status: res.status, data };
+}
+export function jsonResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { validateConfig } from "./config.js";
+import { registerUserTools } from "./tools/users.js";
+import { registerAccountTools } from "./tools/accounts.js";
+import { registerEngagementTools } from "./tools/engagements.js";
+import { registerFeatureTools } from "./tools/features.js";
+import { registerSegmentTools } from "./tools/segments.js";
+import { registerEventTools } from "./tools/events.js";
+import { registerSurveyTools } from "./tools/survey.js";
+import { registerKnowledgeCenterTools } from "./tools/knowledge-center.js";
+import { registerAdminTools } from "./tools/admin.js";
+validateConfig();
+const server = new McpServer({
+    name: "gainsight-px",
+    version: "1.0.0",
+});
+registerUserTools(server);
+registerAccountTools(server);
+registerEngagementTools(server);
+registerFeatureTools(server);
+registerSegmentTools(server);
+registerEventTools(server);
+registerSurveyTools(server);
+registerKnowledgeCenterTools(server);
+registerAdminTools(server);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/tools/accounts.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAccountTools(server: McpServer): void;

package/dist/tools/accounts.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { pxApi, jsonResult } from "../http-client.js";
+export function registerAccountTools(server) {
+    server.tool("px_list_accounts", "List PX accounts with optional filtering, sorting, and scroll-based pagination. Filter syntax: fieldName{op}value.", {
+        filter: z.array(z.string()).optional().describe("Filter expressions"),
+        sort: z.string().optional().describe("Sort field and direction, e.g. 'name:asc'"),
+        pageSize: z.number().optional().describe("Results per page (default 25, max 1000)"),
+        scrollId: z.string().optional().describe("Scroll ID from previous response for next page"),
+    }, async ({ filter, sort, pageSize, scrollId }) => {
+        const res = await pxApi("GET", "/v1/accounts", { filter, sort, pageSize, scrollId });
+        return jsonResult(res.data);
+    });
+    server.tool("px_get_account", "Get a single PX account by ID", {
+        accountId: z.string().describe("The account ID"),
+    }, async ({ accountId }) => {
+        const res = await pxApi("GET", `/v1/accounts/${encodeURIComponent(accountId)}`);
+        return jsonResult(res.data);
+    });
+    server.tool("px_create_account", "Create a new PX account", {
+        accountData: z.record(z.string(), z.unknown()).describe("Account object JSON with id, name, propertyKeys, etc."),
+    }, async ({ accountData }) => {
+        const res = await pxApi("POST", "/v1/accounts", undefined, accountData);
+        return jsonResult(res.data);
+    });
+    server.tool("px_update_account", "Update an existing PX account by ID", {
+        accountId: z.string().describe("The account ID"),
+        accountData: z.record(z.string(), z.unknown()).describe("Fields to update"),
+    }, async ({ accountId, accountData }) => {
+        const res = await pxApi("PUT", `/v1/accounts/${encodeURIComponent(accountId)}`, undefined, accountData);
+        return jsonResult(res.data);
+    });
+    server.tool("px_delete_account", "Delete a PX account by ID (cascading delete of associated users)", {
+        accountId: z.string().describe("The account ID"),
+    }, async ({ accountId }) => {
+        const res = await pxApi("DELETE", `/v1/accounts/${encodeURIComponent(accountId)}`);
+        return jsonResult(res.data);
+    });
+}

package/dist/tools/admin.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAdminTools(server: McpServer): void;

package/dist/tools/admin.js

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import { pxApi, jsonResult } from "../http-client.js";
+export function registerAdminTools(server) {
+    server.tool("px_get_subscription", "Get PX subscription details for the authenticated account", {}, async () => {
+        const res = await pxApi("GET", "/v1/admin/subscription");
+        return jsonResult(res.data);
+    });
+    server.tool("px_get_model_attributes", "Get PX user or account model attributes (custom and standard fields)", {
+        type: z.enum(["user", "account"]).describe("Model type to retrieve attributes for"),
+    }, async ({ type }) => {
+        const res = await pxApi("GET", `/v1/admin/model/${type}/attributes`);
+        return jsonResult(res.data);
+    });
+}

package/dist/tools/engagements.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerEngagementTools(server: McpServer): void;

package/dist/tools/engagements.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { pxApi, jsonResult } from "../http-client.js";
+export function registerEngagementTools(server) {
+    server.tool("px_list_engagements", "List PX engagements with optional content type filter and page-based pagination", {
+        contentTypes: z.array(z.string()).optional().describe("Filter by content types, e.g. ['DIALOG', 'SLIDER', 'GUIDE']"),
+        pageSize: z.number().optional().describe("Results per page (default 200, max 500)"),
+        pageNumber: z.number().optional().describe("Page number (0-indexed)"),
+    }, async ({ contentTypes, pageSize, pageNumber }) => {
+        const params = { pageSize, pageNumber };
+        if (contentTypes)
+            params.contentTypes = contentTypes.join(",");
+        const res = await pxApi("GET", "/v1/engagement", params);
+        return jsonResult(res.data);
+    });
+    server.tool("px_get_engagement", "Get a single PX engagement by ID", {
+        engagementId: z.string().describe("The engagement ID"),
+    }, async ({ engagementId }) => {
+        const res = await pxApi("GET", `/v1/engagement/${encodeURIComponent(engagementId)}`);
+        return jsonResult(res.data);
+    });
+    server.tool("px_set_engagement_state", "Start or pause a PX engagement", {
+        engagementId: z.string().describe("The engagement ID"),
+        state: z.enum(["START", "PAUSE"]).describe("Target state"),
+        envs: z.array(z.string()).optional().describe("Environments to apply to"),
+    }, async ({ engagementId, state, envs }) => {
+        const body = { engagementId, state };
+        if (envs)
+            body.envs = envs;
+        const res = await pxApi("PUT", "/v1/engagement/state", undefined, body);
+        return jsonResult(res.data);
+    });
+    server.tool("px_delete_engagement", "Delete a PX engagement by ID", {
+        engagementId: z.string().describe("The engagement ID"),
+    }, async ({ engagementId }) => {
+        const res = await pxApi("DELETE", `/v1/engagement/${encodeURIComponent(engagementId)}`);
+        return jsonResult(res.data);
+    });
+}

package/dist/tools/events.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerEventTools(server: McpServer): void;

package/dist/tools/events.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { pxApi, jsonResult } from "../http-client.js";
+const EVENT_TYPE_PATHS = {
+    pageView: "/v1/events/pageView",
+    identify: "/v1/events/identify",
+    click: "/v1/events/click",
+    email: "/v1/events/email",
+    formSubmit: "/v1/events/formSubmit",
+    lead: "/v1/events/lead",
+    sessionInitialized: "/v1/events/session",
+    segmentMatch: "/v1/events/segment_match",
+    engagementView: "/v1/events/engagementView",
+    feature_match: "/v1/events/feature_match",
+};
+export function registerEventTools(server) {
+    server.tool("px_get_events", "Query PX events by type with filtering, sorting, and scroll-based pagination. Date values are epoch milliseconds. Max historical range: 190 days.", {
+        eventType: z.enum([
+            "pageView", "identify", "click", "email", "formSubmit",
+            "lead", "sessionInitialized", "segmentMatch", "engagementView", "feature_match",
+        ]).describe("Type of event to query"),
+        filter: z.array(z.string()).optional().describe("Filter expressions"),
+        sort: z.string().optional().describe("Sort field and direction"),
+        pageSize: z.number().optional().describe("Results per page (default 25, max 1000)"),
+        scrollId: z.string().optional().describe("Scroll ID for next page"),
+        dateRangeStart: z.number().optional().describe("Start date as epoch ms"),
+        dateRangeEnd: z.number().optional().describe("End date as epoch ms"),
+    }, async ({ eventType, filter, sort, pageSize, scrollId, dateRangeStart, dateRangeEnd }) => {
+        const path = EVENT_TYPE_PATHS[eventType];
+        const res = await pxApi("GET", path, { filter, sort, pageSize, scrollId, dateRangeStart, dateRangeEnd });
+        return jsonResult(res.data);
+    });
+    server.tool("px_get_custom_events", "Query PX custom events with filtering, sorting, and scroll-based pagination", {
+        filter: z.array(z.string()).optional().describe("Filter expressions"),
+        sort: z.string().optional().describe("Sort field and direction"),
+        pageSize: z.number().optional().describe("Results per page (default 25, max 1000)"),
+        scrollId: z.string().optional().describe("Scroll ID for next page"),
+        dateRangeStart: z.number().optional().describe("Start date as epoch ms"),
+        dateRangeEnd: z.number().optional().describe("End date as epoch ms"),
+    }, async ({ filter, sort, pageSize, scrollId, dateRangeStart, dateRangeEnd }) => {
+        const res = await pxApi("GET", "/v1/events/custom", { filter, sort, pageSize, scrollId, dateRangeStart, dateRangeEnd });
+        return jsonResult(res.data);
+    });
+    server.tool("px_create_custom_event", "Create a custom event in PX", {
+        eventData: z.record(z.string(), z.unknown()).describe("Custom event JSON with identifyId, propertyKey, eventName, date, attributes, etc."),
+    }, async ({ eventData }) => {
+        const res = await pxApi("POST", "/v1/events/custom", undefined, eventData);
+        return jsonResult(res.data);
+    });
+}

package/dist/tools/features.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerFeatureTools(server: McpServer): void;

package/dist/tools/features.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { pxApi, jsonResult } from "../http-client.js";
+export function registerFeatureTools(server) {
+    server.tool("px_list_features", "List PX features with page-based pagination", {
+        pageSize: z.number().optional().describe("Results per page (default 25, max 200)"),
+        pageNumber: z.number().optional().describe("Page number (0-indexed)"),
+        propertyKey: z.string().optional().describe("Filter by product ID"),
+    }, async ({ pageSize, pageNumber, propertyKey }) => {
+        const res = await pxApi("GET", "/v1/feature", { pageSize, pageNumber, propertyKey });
+        return jsonResult(res.data);
+    });
+    server.tool("px_get_feature", "Get a single PX feature by ID", {
+        featureId: z.string().describe("The feature ID"),
+    }, async ({ featureId }) => {
+        const res = await pxApi("GET", `/v1/feature/${encodeURIComponent(featureId)}`);
+        return jsonResult(res.data);
+    });
+    server.tool("px_get_feature_adoption", "Get feature adoption statistics for a given date range", {
+        featureId: z.string().describe("The feature ID"),
+        dateRangeStart: z.number().describe("Start date as epoch milliseconds"),
+        dateRangeEnd: z.number().optional().describe("End date as epoch milliseconds (defaults to now)"),
+        propertyKey: z.string().describe("Product ID"),
+    }, async ({ featureId, dateRangeStart, dateRangeEnd, propertyKey }) => {
+        const res = await pxApi("GET", `/v1/feature/adoption/${encodeURIComponent(featureId)}`, {
+            dateRangeStart,
+            dateRangeEnd,
+            propertyKey,
+        });
+        return jsonResult(res.data);
+    });
+}

package/dist/tools/knowledge-center.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerKnowledgeCenterTools(server: McpServer): void;

package/dist/tools/knowledge-center.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { pxApi, jsonResult } from "../http-client.js";
+export function registerKnowledgeCenterTools(server) {
+    server.tool("px_list_kc_bots", "List PX Knowledge Center bots with page-based pagination", {
+        productId: z.string().optional().describe("Filter by product ID"),
+        pageSize: z.number().optional().describe("Results per page"),
+        pageNumber: z.number().optional().describe("Page number (0-indexed)"),
+    }, async ({ productId, pageSize, pageNumber }) => {
+        const res = await pxApi("GET", "/v1/kcbot", { productId, pageSize, pageNumber });
+        return jsonResult(res.data);
+    });
+    server.tool("px_get_kc_bot", "Get a single PX Knowledge Center bot by ID", {
+        kcId: z.string().describe("The Knowledge Center bot ID"),
+    }, async ({ kcId }) => {
+        const res = await pxApi("GET", `/v1/kcbot/${encodeURIComponent(kcId)}`);
+        return jsonResult(res.data);
+    });
+}

package/dist/tools/segments.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerSegmentTools(server: McpServer): void;

package/dist/tools/segments.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { pxApi, jsonResult } from "../http-client.js";
+export function registerSegmentTools(server) {
+    server.tool("px_list_segments", "List PX segments with page-based pagination", {
+        pageSize: z.number().optional().describe("Results per page (default 25, max 200)"),
+        pageNumber: z.number().optional().describe("Page number (0-indexed)"),
+    }, async ({ pageSize, pageNumber }) => {
+        const res = await pxApi("GET", "/v1/segment", { pageSize, pageNumber });
+        return jsonResult(res.data);
+    });
+    server.tool("px_get_segment", "Get a single PX segment by ID", {
+        segmentId: z.string().describe("The segment ID"),
+    }, async ({ segmentId }) => {
+        const res = await pxApi("GET", `/v1/segment/${encodeURIComponent(segmentId)}`);
+        return jsonResult(res.data);
+    });
+}

package/dist/tools/survey.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerSurveyTools(server: McpServer): void;

package/dist/tools/survey.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { pxApi, jsonResult } from "../http-client.js";
+export function registerSurveyTools(server) {
+    server.tool("px_get_survey_responses", "Query PX survey response events with filtering, sorting, and scroll-based pagination", {
+        filter: z.array(z.string()).optional().describe("Filter expressions"),
+        sort: z.string().optional().describe("Sort field and direction"),
+        pageSize: z.number().optional().describe("Results per page (default 25, max 1000)"),
+        scrollId: z.string().optional().describe("Scroll ID for next page"),
+        dateRangeStart: z.number().optional().describe("Start date as epoch ms"),
+        dateRangeEnd: z.number().optional().describe("End date as epoch ms"),
+    }, async ({ filter, sort, pageSize, scrollId, dateRangeStart, dateRangeEnd }) => {
+        const res = await pxApi("GET", "/v1/survey/responses", { filter, sort, pageSize, scrollId, dateRangeStart, dateRangeEnd });
+        return jsonResult(res.data);
+    });
+}

package/dist/tools/users.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerUserTools(server: McpServer): void;

package/dist/tools/users.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { pxApi, jsonResult } from "../http-client.js";
+export function registerUserTools(server) {
+    server.tool("px_list_users", "List PX users with optional filtering, sorting, and scroll-based pagination. Filter syntax: fieldName{op}value (ops: ==, !=, <, <=, >, >=, ~, !~). Multiple filters are ANDed; pass multiple filter strings for OR.", {
+        filter: z.array(z.string()).optional().describe("Filter expressions, e.g. ['email==john@example.com']"),
+        sort: z.string().optional().describe("Sort field and direction, e.g. 'lastSeenDate:desc'"),
+        pageSize: z.number().optional().describe("Results per page (default 25, max 1000)"),
+        scrollId: z.string().optional().describe("Scroll ID from previous response for next page"),
+    }, async ({ filter, sort, pageSize, scrollId }) => {
+        const res = await pxApi("GET", "/v1/users", { filter, sort, pageSize, scrollId });
+        return jsonResult(res.data);
+    });
+    server.tool("px_get_user", "Get a single PX user by their identifyId", {
+        identifyId: z.string().describe("The user's identifyId"),
+    }, async ({ identifyId }) => {
+        const res = await pxApi("GET", `/v1/users/${encodeURIComponent(identifyId)}`);
+        return jsonResult(res.data);
+    });
+    server.tool("px_create_user", "Create a new PX user. Required fields: identifyId, propertyKeys (with at least one product ID).", {
+        userData: z.record(z.string(), z.unknown()).describe("User object JSON with identifyId, propertyKeys, etc."),
+    }, async ({ userData }) => {
+        const res = await pxApi("POST", "/v1/users", undefined, userData);
+        return jsonResult(res.data);
+    });
+    server.tool("px_update_user", "Update an existing PX user by identifyId", {
+        identifyId: z.string().describe("The user's identifyId"),
+        userData: z.record(z.string(), z.unknown()).describe("Fields to update"),
+    }, async ({ identifyId, userData }) => {
+        const res = await pxApi("PUT", `/v1/users/${encodeURIComponent(identifyId)}`, undefined, userData);
+        return jsonResult(res.data);
+    });
+    server.tool("px_delete_user", "Delete a PX user by identifyId", {
+        identifyId: z.string().describe("The user's identifyId"),
+    }, async ({ identifyId }) => {
+        const res = await pxApi("DELETE", `/v1/users/${encodeURIComponent(identifyId)}`);
+        return jsonResult(res.data);
+    });
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "gainsight-px-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for the Gainsight PX REST API — query and manage users, accounts, engagements, features, segments, events, and more from any MCP-compatible AI tool.",
+  "type": "module",
+  "bin": {
+    "px-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "gainsight",
+    "gainsight-px",
+    "model-context-protocol",
+    "ai",
+    "claude",
+    "cursor"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}