Identifying Users

AgentCat 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:

agentcat.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
    };
  }
});

import agentcat
from agentcat import UserIdentity

def identify_user(request, context):
    user_id = request.params.arguments.get('userId')
    if not user_id:
        return None

    return UserIdentity(
        user_id=user_id,
        user_name=request.params.arguments.get('userName')
    )

agentcat.track(server, "proj_abc123xyz",
             agentcat.AgentCatOptions(identify=identify_user))

import (
    "github.com/modelcontextprotocol/go-sdk/mcp"
    agentcat "go.agentcat.com/sdk/officialsdk"
    // For mark3labs/mcp-go: agentcat "go.agentcat.com/sdk/mcpgo"
)

agentcat.Track(s, "proj_abc123xyz", &agentcat.Options{
    Identify: func(ctx context.Context, req *mcp.CallToolRequest) *agentcat.UserIdentity {
        args := req.GetArguments()
        userID, _ := args["userId"].(string)
        if userID == "" {
            return nil
        }
        userName, _ := args["userName"].(string)
        return &agentcat.UserIdentity{
            UserID:   userID,
            UserName: 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
}

from agentcat import UserIdentity

UserIdentity(
    user_id="user123",                # Required: Unique identifier
    user_name="John Doe",             # Optional: Display name
    user_data={                       # Optional: Additional metadata
        "plan": "premium",
        "company": "Acme Corp"
    }
)

agentcat.UserIdentity{
    UserID:   "user123",              // Required: Unique identifier
    UserName: "John Doe",             // Optional: Display name
    UserData: map[string]any{         // Optional: Additional metadata
        "plan":    "premium",
        "company": "Acme Corp",
    },
}

Common Patterns

Token-Based Authentication

Extract user information from authentication tokens:

agentcat.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
      }
    };
  }
});

from mcp.server.auth.middleware.auth_context import get_access_token

def identify_from_token(request, context):
    # Try to get token from MCP auth context first
    access_token = get_access_token()
    if access_token:
        token = access_token.token
    else:
        # Fall back to request arguments
        token = request.params.arguments.get('token')

    # Validate token and fetch user
    user = validate_token_and_get_user(token)

    return UserIdentity(
        user_id=user.id,
        user_name=user.email,
        user_data={
            'role': user.role,
            'organization': user.org_id
        }
    )

agentcat.track(server, "proj_abc123xyz",
             agentcat.AgentCatOptions(identify=identify_from_token))

agentcat.Track(s, "proj_abc123xyz", &agentcat.Options{
    Identify: func(ctx context.Context, req *mcp.CallToolRequest) *agentcat.UserIdentity {
        // Get token from request arguments or context
        args := req.GetArguments()
        token, _ := args["token"].(string)

        // Validate token and fetch user
        user, err := validateTokenAndGetUser(token)
        if err != nil {
            return nil
        }

        return &agentcat.UserIdentity{
            UserID:   user.ID,
            UserName: user.Email,
            UserData: map[string]any{
                "role":         user.Role,
                "organization": user.OrgID,
            },
        }
    },
})

API Key Identification

Identify users based on API keys:

agentcat.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
      }
    };
  }
});

def identify_from_api_key(request, context):
    api_key = request.params.arguments.get('apiKey')

    account = get_account_by_api_key(api_key)

    return UserIdentity(
        user_id=account.id,
        user_name=account.organization_name,
        user_data={
            'tier': account.tier,
            'monthly_usage': account.current_usage,
            'region': account.region
        }
    )

agentcat.track(server, "proj_abc123xyz",
             agentcat.AgentCatOptions(identify=identify_from_api_key))

agentcat.Track(s, "proj_abc123xyz", &agentcat.Options{
    Identify: func(ctx context.Context, req *mcp.CallToolRequest) *agentcat.UserIdentity {
        args := req.GetArguments()
        apiKey, _ := args["apiKey"].(string)

        account := getAccountByApiKey(apiKey)

        return &agentcat.UserIdentity{
            UserID:   account.ID,
            UserName: account.OrganizationName,
            UserData: map[string]any{
                "tier":         account.Tier,
                "monthlyUsage": account.CurrentUsage,
                "region":       account.Region,
            },
        }
    },
})

MCP Authentication

For servers using MCP’s built-in authentication:

agentcat.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
      }
    };
  }
});

from mcp.server.auth.middleware.auth_context import get_access_token

def identify_from_mcp_auth(request, context):
    # Get the MCP access token
    access_token = get_access_token()

    if not access_token:
        return None  # Anonymous session

    # Use the MCP auth token to identify user
    user = get_user_from_mcp_token(access_token.token)

    return UserIdentity(
        user_id=user.id,
        user_name=user.email,
        user_data={
            'auth_provider': 'mcp',
            'scopes': access_token.scopes
        }
    )

agentcat.track(server, "proj_abc123xyz",
             agentcat.AgentCatOptions(identify=identify_from_mcp_auth))

agentcat.Track(s, "proj_abc123xyz", &agentcat.Options{
    Identify: func(ctx context.Context, req *mcp.CallToolRequest) *agentcat.UserIdentity {
        // Extract auth token from context
        authToken := getAuthTokenFromContext(ctx)
        if authToken == "" {
            return nil // Anonymous session
        }

        // Use the auth token to identify user
        user := getUserFromToken(authToken)

        return &agentcat.UserIdentity{
            UserID:   user.ID,
            UserName: user.Email,
            UserData: map[string]any{
                "authProvider": "mcp",
            },
        }
    },
})

Error Handling

Handle identification failures gracefully:

agentcat.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;
    }
  }
});

def identify_with_error_handling(request, context):
    try:
        user = fetch_user_info(request)
        return UserIdentity(
            user_id=user.id,
            user_name=user.name
        )
    except Exception as e:
        print(f'User identification failed: {e}')
        # Return None to continue with anonymous tracking
        return None

agentcat.track(server, "proj_abc123xyz",
             agentcat.AgentCatOptions(identify=identify_with_error_handling))

agentcat.Track(s, "proj_abc123xyz", &agentcat.Options{
    Identify: func(ctx context.Context, req *mcp.CallToolRequest) *agentcat.UserIdentity {
        user, err := fetchUserInfo(ctx, req)
        if err != nil {
            log.Printf("User identification failed: %v", err)
            // Return nil to continue with anonymous tracking
            return nil
        }
        return &agentcat.UserIdentity{
            UserID:   user.ID,
            UserName: user.Name,
        }
    },
})

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: Uses the MCP TypeScript SDK
Python: Uses the MCP Python SDK
Go: Uses the official Go MCP SDK or mark3labs/mcp-go

// TypeScript SDK parameters
identify: async (request, extra) => {
  // request: MCP request object
  // extra: RequestHandlerExtra object
}

# Python SDK parameters
def identify(request, context):
    # request: MCP request object
    # context: RequestContext object
    pass

// Go SDK parameters
Identify: func(ctx context.Context, req *mcp.CallToolRequest) *agentcat.UserIdentity {
    // ctx: context.Context — request context with cancellation and deadlines
    // req: *mcp.CallToolRequest — the tool call request with arguments
    return nil
}

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;
    };
  };
}

# Python request object structure
request.method           # The tool/method being called (e.g., "tools/call")
request.params           # Optional parameters object
request.params.name      # Tool name being invoked
request.params.arguments # Tool-specific arguments dict
# Access arguments like:
request.params.arguments.get('userId')
request.params.arguments.get('apiKey')

// Go request object structure (*mcp.CallToolRequest)
req.Method()                          // The tool/method being called
req.Params.Name                       // Tool name being invoked
req.GetArguments()                    // Tool-specific arguments map
// Access arguments like:
args := req.GetArguments()
userID, _ := args["userId"].(string)
apiKey, _ := args["apiKey"].(string)

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...
}

from mcp.server.auth.middleware.auth_context import get_access_token

def identify(request, context):
    # Access tool arguments
    user_id = request.params.arguments.get('userId')
    api_key = request.params.arguments.get('apiKey')

    # Access auth token (if using MCP auth)
    access_token = get_access_token()
    if access_token:
        auth_token = access_token.token

    # Tool name being called
    tool_name = request.params.name

    # Access client information from context
    client_name = None
    try:
        client_info = context.session.client_params.clientInfo
        client_name = client_info.name if client_info else None
    except:
        pass

    # Your identification logic here...

Identify: func(ctx context.Context, req *mcp.CallToolRequest) *agentcat.UserIdentity {
    // Access tool arguments
    args := req.GetArguments()
    userID, _ := args["userId"].(string)
    apiKey, _ := args["apiKey"].(string)

    // Tool name being called
    toolName := req.Params.Name

    // Check if request was cancelled
    if ctx.Err() != nil {
        return nil
    }

    // 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

​Basic Implementation

​User Identity Object

​Common Patterns

​Token-Based Authentication

​API Key Identification

​MCP Authentication

​Error Handling

​Function Parameters

​request

​TypeScript: extra

​Python: context

​Go: ctx and req

​Common Usage Patterns

​Important Considerations

​Anonymous Sessions

Basic Implementation

User Identity Object

Common Patterns

Token-Based Authentication

API Key Identification

MCP Authentication

Error Handling

Function Parameters

request

TypeScript: extra

Python: context

Go: ctx and req

Common Usage Patterns

Important Considerations

Anonymous Sessions