Custom Events - AgentCat

AgentCat 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 agentcat.track(), use publishCustomEvent to send events tied to the current session. Pass the tracked server instance as the first argument.

import * as agentcat from "agentcat"

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

import agentcat

agentcat.publish_custom_event(server, "proj_abc123xyz", {
    "resource_name": "subscription_upgraded",
    "parameters": {
        "plan": "pro",
        "source": "settings_page"
    }
})

import agentcat "go.agentcat.com/sdk/officialsdk"
// For mark3labs/mcp-go: import agentcat "go.agentcat.com/sdk/mcpgo"

agentcat.PublishCustomEvent(s, "proj_abc123xyz", agentcat.EventData{
    ResourceName: "subscription_upgraded",
    Parameters: map[string]any{
        "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. AgentCat will derive a stable session from it.

await agentcat.publishCustomEvent("user-session-12345", "proj_abc123xyz", {
  resourceName: "report_exported"
})

agentcat.publish_custom_event("user-session-12345", "proj_abc123xyz", {
    "resource_name": "report_exported"
})

agentcat.PublishCustomEvent("user-session-12345", "proj_abc123xyz", agentcat.EventData{
    ResourceName: "report_exported",
})

publishCustomEvent Reference

Parameter	Type	Required	Description
`serverOrSessionId`	Server \| string	Yes	A tracked MCP server instance, or a session ID string
`projectId`	string	Yes	Your AgentCat project ID (e.g. `proj_abc123xyz`)
`eventData`	object	No	The event payload (see below)

Event Data

Field	Type	Description
`resourceName`	string	A name for the event. Shows as the label in the dashboard timeline. If omitted, the event shows as “Custom”.
`parameters`	object	Arbitrary data to attach to the event. Visible in the event detail panel.
`response`	object	Response data to attach to the event.
`message`	string	A human-readable description of what happened.
`duration`	number	Duration of the event in milliseconds.
`isError`	boolean	Set to `true` to mark this event as an error.
`error`	object	Error details. Typically includes `message` and optionally `type` or `code`.
`tags`	Record<string, string>	Indexed string key-value pairs for filtering and grouping. Subject to tag validation rules.
`properties`	Record<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 agentcat.publishCustomEvent(mcpServer, "proj_abc123xyz", {
  resourceName: "feature_used",
  parameters: {
    feature: "data_export",
    format: "json",
    recordCount: 250
  }
})

agentcat.publish_custom_event(server, "proj_abc123xyz", {
    "resource_name": "feature_used",
    "parameters": {
        "feature": "data_export",
        "format": "json",
        "record_count": 250
    }
})

agentcat.PublishCustomEvent(s, "proj_abc123xyz", agentcat.EventData{
    ResourceName: "feature_used",
    Parameters: map[string]any{
        "feature":     "data_export",
        "format":      "json",
        "recordCount": 250,
    },
})

Tracking Errors

Capture application-level errors that aren’t tied to a specific tool call.

await agentcat.publishCustomEvent(mcpServer, "proj_abc123xyz", {
  resourceName: "rate_limit_hit",
  isError: true,
  error: { message: "Rate limit exceeded", code: "RATE_LIMIT" },
  parameters: {
    endpoint: "/api/search",
    limit: 100
  }
})

agentcat.publish_custom_event(server, "proj_abc123xyz", {
    "resource_name": "rate_limit_hit",
    "is_error": True,
    "error": {"message": "Rate limit exceeded", "code": "RATE_LIMIT"},
    "parameters": {
        "endpoint": "/api/search",
        "limit": 100
    }
})

agentcat.PublishCustomEvent(s, "proj_abc123xyz", agentcat.EventData{
    ResourceName: "rate_limit_hit",
    IsError:      true,
    Error:        map[string]any{"message": "Rate limit exceeded", "code": "RATE_LIMIT"},
    Parameters: map[string]any{
        "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 agentcat.publishCustomEvent(mcpServer, "proj_abc123xyz", {
  resourceName: "onboarding_completed",
  message: "User finished all onboarding steps",
  parameters: {
    stepsCompleted: 5
  },
  duration: 200000
})

agentcat.publish_custom_event(server, "proj_abc123xyz", {
    "resource_name": "onboarding_completed",
    "message": "User finished all onboarding steps",
    "parameters": {
        "steps_completed": 5
    },
    "duration": 200000
})

agentcat.PublishCustomEvent(s, "proj_abc123xyz", agentcat.EventData{
    ResourceName: "onboarding_completed",
    Message:      "User finished all onboarding steps",
    Parameters: map[string]any{
        "stepsCompleted": 5,
    },
    Duration: 200000,
})

​Publishing Events

​Using a Session ID

​publishCustomEvent Reference

​Event Data

​Examples

​Tracking Feature Usage

​Tracking Errors

​Tracking User Milestones