Skip to main content
MCPcat automatically tracks MCP protocol events like tool calls and session initialization. Custom events let you go further and track actions specific to your application: feature usage, billing milestones, or anything else that matters to your product. Custom events appear in the session replay timeline with a bolt icon, alongside automatic MCP events. The resourceName is used as the label. Click on any custom event to see its full details, including parameters, response, and message. If isError is set to true, the event is styled as an error in the timeline.

​
Publishing Events

After calling mcpcat.track(), use publishCustomEvent to send events tied to the current session. Pass the tracked server instance as the first argument. 
import * as mcpcat from "mcpcat"

await mcpcat.publishCustomEvent(mcpServer, "proj_abc123xyz", {
  resourceName: "subscription_upgraded",
  parameters: {
    plan: "pro",
    source: "settings_page"
  }
})

​
Using a Session ID

If you have a session ID instead of the server instance, you can pass it directly as a string. MCPcat will derive a stable session from it. 
await mcpcat.publishCustomEvent("user-session-12345", "proj_abc123xyz", {
  resourceName: "report_exported"
})

​
publishCustomEvent Reference

ParameterTypeRequiredDescription
serverOrSessionIdServer | stringYesA tracked MCP server instance, or a session ID string
projectIdstringYesYour MCPcat project ID (e.g. proj_abc123xyz)
eventDataobjectNoThe event payload (see below)

​
Event Data

FieldTypeDescription
resourceNamestringA name for the event. Shows as the label in the dashboard timeline. If omitted, the event shows as “Custom”.
parametersobjectArbitrary data to attach to the event. Visible in the event detail panel.
responseobjectResponse data to attach to the event.
messagestringA human-readable description of what happened.
durationnumberDuration of the event in milliseconds.
isErrorbooleanSet to true to mark this event as an error.
errorobjectError details. Typically includes message and optionally type or code.
tagsRecord<string, string>Indexed string key-value pairs for filtering and grouping. Subject to tag validation rules.
propertiesRecord<string, any>Arbitrary JSON metadata. No client-side validation constraints.
All fields in eventData are optional. You can call publishCustomEvent with just the server and project ID to record a minimal custom event. You can also enrich every auto-captured event with metadata — see Event Tags & Properties.

​
Examples

​
Tracking Feature Usage

Record when users interact with specific features to understand adoption and usage patterns. 
await mcpcat.publishCustomEvent(mcpServer, "proj_abc123xyz", {
  resourceName: "feature_used",
  parameters: {
    feature: "data_export",
    format: "json",
    recordCount: 250
  }
})

​
Tracking Errors

Capture application-level errors that aren’t tied to a specific tool call. 
await mcpcat.publishCustomEvent(mcpServer, "proj_abc123xyz", {
  resourceName: "rate_limit_hit",
  isError: true,
  error: { message: "Rate limit exceeded", code: "RATE_LIMIT" },
  parameters: {
    endpoint: "/api/search",
    limit: 100
  }
})

​
Tracking User Milestones

Track when users reach key points in their journey, with duration to measure how long it took. 
await mcpcat.publishCustomEvent(mcpServer, "proj_abc123xyz", {
  resourceName: "onboarding_completed",
  message: "User finished all onboarding steps",
  parameters: {
    stepsCompleted: 5
  },
  duration: 200000
})