Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mcpcat.io/llms.txt

Use this file to discover all available pages before exploring further.

MCPcat allows you to identify users and associate their sessions with specific user information. This lets you to track usage patterns, understand user behavior, and provide personalized experiences. User identification happens automatically when a tool is invoked. In stateful mode (the default), this happens once on the first tool call and persists for the session. In stateless mode, it runs on every request since there is no persistent session.

​
Basic Implementation

To identify users, provide an identify callback function when tracking your MCP server. The simplest approach is to pull the user ID directly from the tool call arguments: 
mcpcat.track(mcpServer, "proj_abc123xyz", {
  identify: async (request, extra) => {
    const userId = request.params?.arguments?.userId;
    if (!userId) return null;

    return {
      userId,
      userName: request.params?.arguments?.userName
    };
  }
});

​
User Identity Object

The identify function should return a UserIdentity object with the following structure: 
interface UserIdentity {
  userId: string;                    // Required: Unique identifier
  userName?: string;                 // Optional: Display name
  userData?: Record<string, any>;    // Optional: Additional metadata
}

​
Common Patterns

​
Token-Based Authentication

Extract user information from authentication tokens: 
mcpcat.track(mcpServer, "proj_abc123xyz", {
  identify: async (request, extra) => {
    // Get token from request arguments or auth info
    const token = request.params?.arguments?.token ||
                  extra.authInfo?.token;

    // Validate token and fetch user
    const user = await validateTokenAndGetUser(token);

    return {
      userId: user.id,
      userName: user.email,
      userData: {
        role: user.role,
        organization: user.orgId
      }
    };
  }
});

​
API Key Identification

Identify users based on API keys: 
mcpcat.track(mcpServer, "proj_abc123xyz", {
  identify: async (request, extra) => {
    const apiKey = request.params?.arguments?.apiKey;

    const account = await getAccountByApiKey(apiKey);

    return {
      userId: account.id,
      userName: account.organizationName,
      userData: {
        tier: account.tier,
        monthlyUsage: account.currentUsage,
        region: account.region
      }
    };
  }
});

​
MCP Authentication

For servers using MCP’s built-in authentication: 
mcpcat.track(mcpServer, "proj_abc123xyz", {
  identify: async (request, extra) => {
    // Access auth token from extra parameter
    const authToken = extra.authInfo?.token;

    if (!authToken) {
      return null; // Anonymous session
    }

    // Use the MCP auth token to identify user
    const user = await getUserFromMCPToken(authToken);

    return {
      userId: user.id,
      userName: user.email,
      userData: {
        authProvider: 'mcp',
        scopes: extra.authInfo?.scopes
      }
    };
  }
});

​
Error Handling

Handle identification failures gracefully: 
mcpcat.track(mcpServer, "proj_abc123xyz", {
  identify: async (request, extra) => {
    try {
      const user = await fetchUserInfo(request);
      return {
        userId: user.id,
        userName: user.name
      };
    } catch (error) {
      console.error('User identification failed:', error);
      // Return null to continue with anonymous tracking
      return null;
    }
  }
});

​
Function Parameters

The identify function receives parameters that vary between the TypeScript, Python, and Go SDKs:
The request structure follows the MCP (Model Context Protocol) specification. The specific types and fields available depend on your SDK:
// TypeScript SDK parameters
identify: async (request, extra) => {
  // request: MCP request object
  // extra: RequestHandlerExtra object
}

​
request

The MCP request object following the JSON-RPC format: 
{
  method: string;              // The tool/method being called (e.g., "tools/call")
  params?: {                   // Optional parameters
    _meta?: {                  // Optional metadata
      progressToken?: string | number;  // Token for progress notifications
    };
    name?: string;             // Tool name being invoked
    arguments?: {              // Tool-specific arguments passed by the client
      // Your custom arguments like userId, apiKey, token, etc. passed into tool calls
      [key: string]: any;
    };
  };
}

​
TypeScript: extra

The MCP RequestHandlerExtra object providing additional context: 
{
  signal: AbortSignal;         // Abort signal for request cancellation
  authInfo?: AuthInfo;         // Validated access token information
  sessionId?: string;          // Session ID from the transport
  _meta?: RequestMeta;         // Metadata from the original request
  requestId: RequestId;        // JSON-RPC ID of the request (string | number)

  // Functions for sending related messages (not typically used in identify)
  sendNotification: (notification: Notification) => Promise<void>;
  sendRequest: <U>(request: Request, resultSchema: U, options?: RequestOptions) => Promise<z.infer<U>>;
}

​
Python: context

The MCP RequestContext object providing session and client information: 
# Python context object
context.session                                   # ServerSession object
context.session.client_params.clientInfo.name     # Client name
context.session.client_params.clientInfo.version  # Client version
context.lifespan_context                          # Application-specific context storage
In stateless mode, context.session still exists but represents the per-request context rather than a long-lived session. The clientInfo fields are extracted from HTTP headers on each request.
Python Authentication Access: In Python MCP servers, authentication tokens are accessed via the get_access_token() function from mcp.server.auth.middleware.auth_context, not through the context parameter. This is different from the TypeScript SDK where auth info is available in the extra parameter.

​
Go: ctx and req

The Go SDK identify function receives context.Context and *mcp.CallToolRequest: 
// ctx: standard Go context with cancellation and deadline support
ctx.Done()      // Channel closed when request is cancelled
ctx.Err()       // Returns context.Canceled or context.DeadlineExceeded

// req: the MCP CallToolRequest
req.Params.Name                       // Tool name being invoked
args := req.GetArguments()            // Tool arguments as map[string]any
Go Authentication Access: In Go MCP servers, authentication information is typically extracted from the context.Context parameter. The exact method depends on your authentication middleware and MCP library.

​
Common Usage Patterns

identify: async (request, extra) => {
  // Access tool arguments
  const userId = request.params?.arguments?.userId;
  const apiKey = request.params?.arguments?.apiKey;

  // Access auth information (if using MCP auth)
  const authToken = extra.authInfo?.token;

  // Tool name being called
  const toolName = request.params?.name;

  // Check if request was cancelled
  if (extra.signal.aborted) {
    return null;
  }

  // Your identification logic here...
}

​
Important Considerations

Stateful servers (default): The identify function is called once per session on the first tool invocation. This minimizes overhead while ensuring consistent user tracking throughout the session.Stateless servers: The identify function is called on every request since there is no persistent session. Keep your identify function lightweight — avoid expensive API calls or database lookups if possible. Without identification, stateless events cannot be grouped into sessions.

​
Anonymous Sessions

If you don’t provide an identify function or if it returns null, sessions will be tracked anonymously. This is useful for:
  • Public APIs where user identification isn’t required
  • Development and testing environments
  • Respecting user privacy preferences