How It Works

​

Architecture

​

Agent Intent Capture

{
  "tool": "search_files",
  "arguments": {
    "query": "authentication",
    "context": "Looking for authentication logic to understand how user sessions are validated before adding a new permission check"
  }
}

• What users are trying to accomplish
• How tools fit into larger workflows
• Common patterns and use cases
• Missing functionality users need

​

Request Tracing

import mcpcat
from mcp.server import FastMCP

# Your existing server

server = FastMCP(name="my-tools")

# One line to add analytics

mcpcat.track(server, "proj_YOUR_PROJECT_ID")

• Event type (tool call, resource access, prompt execution)
• Timing data (start time, duration)
• Request parameters and response data
• Error states and messages
• Client information (which AI tool made the request)

​

How it Works Under the Hood

​

1. Schema Enhancement

{
  "name": "search_files",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" }
    }
  }
}

{
  "name": "search_files",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "context": {
        "type": "string",
        "description": "Describe why you are calling this tool..."
      }
    },
    "required": ["query", "context"]
  }
}

​

2. Transparent Interception

1. Client calls tool with arguments + context
2. MCPcat extracts the context parameter
3. Your tool receives original arguments (without context)
4. Tool executes normally
5. MCPcat captures the response
6. Event is queued for analytics

​

3. Asynchronous Processing

• Thread-safe queue holds events (default: 10,000 capacity)
• Worker threads send events to MCPcat API
• Automatic retries with exponential backoff
• Graceful shutdown ensures no data loss

​

4. Privacy & Control

• Redaction functions let you scrub sensitive data before sending
• All data encrypted at rest
• You control what events are tracked
• No PII required - user identification is optional

​

Sessions

• Stateful servers: The SDK generates a session ID when a client connects. All events during that connection share the same session.
• Stateless servers: Each request is independent, so the SDK sends events without a session ID. MCPcat’s backend groups these events into sessions automatically based on the identified user, the client used, and a 30-minute inactivity window. See Stateless Servers for setup details.

1. Initialization: A new session starts when a client initializes a connection to your MCP server
2. Activity: All tool invocations and interactions are associated with the session
3. Inactivity: Sessions remain active as long as the client maintains the connection
4. Termination: Sessions end when the client disconnects or after a period of inactivity (usually 30 minutes)

​

Session Construction

​

Client-Side (SDK)

1. Generates a unique session ID (stateful) or signals stateless mode so the server can group events — and associates all subsequent events accordingly
2. Captures metadata about the connection, like client name and version, server name and version, and SDK language and version
3. Records each interaction as a structured event with tool calls, resource reads, prompt requests, along with timing data, parameters, and responses
4. Streams events asynchronously to MCPcat’s ingestion pipeline so there is zero impact on your server’s response times

​

Server-Side Processing

1. Session assembly: Events are matched to their session using atomic, concurrent-safe operations. If a session doesn’t exist yet, it’s created on the first event. Metadata fields are progressively backfilled: if the first event is missing client info, later events in the same session can fill in the gaps. For stateless servers, events arrive without a session ID, and MCPcat groups them by matching the identified user and AI client within a 30-minute window. This requires user identification — anonymous stateless events each get their own isolated session.
2. Session consolidation: Some MCP clients (like Claude Desktop) reset session identifiers mid-conversation. MCPcat detects these inconsistencies and automatically merges fragmented sessions back together, so you see one continuous interaction instead of several broken ones.
3. Counter denormalization: As events arrive, session-level metrics (total events, tool calls, errors, missing tool indicators) are updated atomically. This means your dashboard queries are fast even across thousands of sessions, without needing to re-aggregate raw events on every page load.
4. Error grouping: When an error occurs during a tool call, MCPcat parses the error, computes a fingerprint, and groups it with similar errors across sessions. This surfaces recurring issues automatically rather than burying them in individual session logs.
5. Goal categorization: After a session becomes inactive, MCPcat analyzes the sessions contents to classify an agent goal, giving you insight into what users were trying to accomplish, not just what tools they called. For more information, see Agent Goals

​

Projects

• By server type: Separate projects for different MCP servers (database tools, file system tools, API integrations)
• By environment: Keep development, staging, and production data isolated
• By customer or team: Track usage across different customer deployments or internal teams

​

What Gets Tracked

• Tool Operations: tools/list, tools/call
• Resource Operations: resources/list, resources/read
• Prompt Operations: prompts/list, prompts/get
• Completions: completion/complete
• Server Lifecycle: initialize, initialized
• Custom Events: Your own analytics events

​

Next Steps