​
Overview

Events are the core unit of analytics in MCPcat. Each interaction between an AI client and your MCP server generates an event that captures what happened, when it happened, and the surrounding context. When analyzed together, these events reveal how users interact with your tools and where improvements can be made.

​
Event Types

MCPcat automatically tracks several types of events throughout the lifecycle of client-server interactions.

​
Tool Events

Tool List (tools/list): Captured when a client discovers available tools from your server. These events show which capabilities clients are accessing and how often they refresh their tool inventory.

Tool Call (tools/call): The most important event type, fired whenever a client invokes one of your tools. These events capture:

  • Which tool was called
  • Arguments passed to the tool
  • How long execution took
  • Whether the operation succeeded or failed
  • The response or error returned

​
Session Events

Initialize (initialize): Marks the beginning of a client session, capturing client information like application name and version. This helps you understand your user ecosystem and make compatibility decisions.

​
Event Anatomy

Each event contains several layers of information that enable meaningful analytics.

​
Core Properties

Every event includes:

  • Event ID: A unique identifier for the event
  • Timestamp: Precise time when the event occurred
  • Session ID: Links the event to a user session
  • Event Type: The category of interaction (tool call, initialization, etc.)

​
Contextual Data

Events also capture rich context including:

  • Client Information: Name and version of the connecting application
  • Server Details: Your MCP server name and version
  • User Identity: If configured, the identified user information
  • Duration: For tool calls, how long execution took

​
Tool-Specific Data

For tool invocation events, MCPcat captures:

  • Tool Name: Which tool was invoked
  • Arguments: Parameters passed to the tool (with optional redaction)
  • Response: The tool’s return value or error details
  • User Intent: When context collection is enabled, why the user called the tool

​
How events are processed

MCPcat’s event system is designed for both performance and privacy.

​
Asynchronous Collection

Events are captured without blocking your tool execution. This ensures analytics never impact your server’s response times. Events are collected in a background queue and processed separately from your main application flow.

​
Batching and Delivery

Instead of sending each event immediately, MCPcat batches events for efficient transmission. This reduces network overhead and improves reliability. The batching system adapts to activity levels, sending more frequently during high usage and conserving resources during quiet periods.

​
Privacy Protection

Before transmission, events pass through a privacy pipeline where:

  • Custom redaction functions can remove sensitive data
  • Personal information can be stripped or hashed
  • File paths and API keys can be sanitized

This ensures compliance with privacy requirements while maintaining analytical value.