MCPcat is an analytics platform that helps MCP server developers understand how their tools are being used. It captures user intent, traces every request, and provides actionable insights—all while preserving your server’s original functionality.

​
Core Concepts

​
Session Tracking

Every interaction with your MCP server happens within a session. MCPcat automatically:

  • Creates unique session IDs when a client connects
  • Tracks session duration and activity patterns
  • Groups related tool calls together
  • Detects when sessions go inactive

Sessions help you understand complete user workflows rather than isolated tool calls.

​
User Intent Capture

The magic of MCPcat lies in understanding why users call your tools, not just what they call.

MCPcat automatically injects a context parameter into your tool schemas. When AI assistants (like Claude or Cline) call your tools, they explain their reasoning:

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

This context is extracted and stored as user_intent, giving you insights into:

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

​
Request Tracing

MCPcat intercepts all MCP protocol messages by wrapping your server’s handlers:

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

Every request is captured with:

  • 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

When MCPcat wraps your server, it modifies tool schemas to include the context parameter:

Before MCPcat:

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

After MCPcat:

{
  "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

MCPcat intercepts requests without affecting your tool’s functionality:

  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

Your tools never see the context parameter—they work exactly as before.

​
3. Asynchronous Processing

Events are processed asynchronously to ensure zero performance impact:

  • 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

MCPcat is designed with privacy in mind:

  • 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

​
Session Lifecycle

Understanding the session lifecycle helps you interpret analytics:

  1. Session Start: Client connects to your MCP server
  2. Initialization: MCPcat captures client/server metadata
  3. Active Use: Tool calls, resource access, prompts executed
  4. Inactivity: No requests for configured timeout period
  5. Session End: Marked inactive after timeout

Each session provides a complete picture of user interaction, from initial connection to final tool call.

​
What Gets Tracked

MCPcat tracks all MCP protocol events:

  • 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

Ready to add analytics to your MCP server? Check out our Quickstart Guide to get started in minutes.