Skip to main content
MCPcat’s SDKs automatically capture rich telemetry on every tool call and major event in your MCP server. But sometimes, you need additional information to query or debug events. Event tags and properties let you attach that context:
  • Tags: string key-value pairs designed for filtering and grouping in the dashboard and exported data
  • Properties: flexible JSON for arbitrary context like feature flags, device info, or build metadata
Both are callback options on mcpcat.track() that attach metadata to every auto-captured event - tool calls, tool lists, and session initialization. You set them up once and every event gets enriched automatically, without modifying individual tool handlers. Both callbacks receive the same (request, extra) arguments as identify, and if they throw or return null, the event is still sent without metadata.

​
Event Tags

Use eventTags to attach structured, filterable metadata to every event. Tags are ideal for values you’ll want to filter or group by in the dashboard, such as environments, regions, trace IDs, or deployment versions. 
mcpcat.track(mcpServer, "proj_abc123xyz", {
  eventTags: async (request, extra) => ({
    env: process.env.NODE_ENV ?? "development",
    region: "us-east-1",
    trace_id: extra?.requestContext?.traceId ?? "none",
  }),
});

​
Event Properties

Use eventProperties to attach flexible JSON metadata. Properties have no client-side validation constraints beyond being valid JSON. 
mcpcat.track(mcpServer, "proj_abc123xyz", {
  eventProperties: async (request, extra) => ({
    device: "desktop",
    app_version: "2.1.0",
    feature_flags: ["dark_mode", "beta_ui"],
    build: {
      commit: "abc123",
      branch: "main",
    },
  }),
});

​
Using Both Together

Use tags for the values you’d filter by in a dashboard and properties for the detail you’d want when clicking into a specific event. 
mcpcat.track(mcpServer, "proj_abc123xyz", {
  identify: async (request, extra) => {
    const userId = request.params?.arguments?.userId;
    if (!userId) return null;
    return { userId };
  },
  eventTags: async (request, extra) => ({
    env: process.env.NODE_ENV ?? "development",
    region: process.env.AWS_REGION ?? "unknown",
  }),
  eventProperties: async (request, extra) => ({
    tool_name: request.params?.name,
    server_version: process.env.npm_package_version,
  }),
});

​
Examples

​
Tagging by Environment

Tag events with your deployment environment and region to compare error rates and tool usage patterns across production, staging, and development. 
mcpcat.track(mcpServer, "proj_abc123xyz", {
  eventTags: async (request, extra) => ({
    env: process.env.NODE_ENV ?? "development",
    region: process.env.AWS_REGION ?? "unknown",
    version: process.env.npm_package_version ?? "0.0.0",
  }),
});

​
Attaching Feature Flags

Attach feature flags and build metadata as properties so you can see exactly what configuration was active when a tool call happened — useful for debugging why a tool behaves differently for certain users. 
mcpcat.track(mcpServer, "proj_abc123xyz", {
  eventProperties: async (request, extra) => ({
    feature_flags: getActiveFlags(),
    build: {
      commit: process.env.GIT_SHA,
      branch: process.env.GIT_BRANCH,
      ci: process.env.CI === "true",
    },
  }),
});

​
Correlating with External Observability

Tag events with trace and span IDs from your existing observability stack to link MCPcat events directly to traces in Datadog, Sentry, or any OpenTelemetry-compatible platform. 
mcpcat.track(mcpServer, "proj_abc123xyz", {
  eventTags: async (request, extra) => ({
    trace_id: extra?.requestContext?.traceId ?? "none",
    span_id: extra?.requestContext?.spanId ?? "none",
    service: "my-mcp-server",
  }),
});

​
Tag Validation Rules

Tags are validated client-side before being attached to events. Invalid entries are silently dropped with a warning written to ~/mcpcat.log.
  • Keys: Must be 32 characters or fewer and match [a-zA-Z0-9_.:\- ] (letters, digits, dots, underscores, colons, hyphens, spaces)
  • Values: Must be strings, 200 characters or fewer, and cannot contain newline characters
  • Max entries: 50 tags per event — entries beyond the limit are dropped
Event properties have no client-side validation constraints — any valid JSON is accepted. Only tags are validated.
Tag validation applies to both eventTags callback results and inline tags on custom events. Invalid entries are dropped, but the event is still sent.