Skip to main content

​
Overview

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 timeline alongside automatic events, so you get the full picture of what happened during a session.

​
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: "report_exported",
  parameters: {
    format: "csv",
    rowCount: 1500
  }
})

​
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"
})

​
Function 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.
All fields in eventData are optional. You can call publishCustomEvent with just the server and project ID to record a minimal custom event.

​
Examples

​
Tracking Feature Usage

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

await mcpcat.publishCustomEvent(mcpServer, "proj_abc123xyz", {
  resourceName: "onboarding_completed",
  message: "User finished all onboarding steps",
  parameters: {
    stepsCompleted: 5
  },
  duration: 200000
})

​
Viewing Custom Events

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.