Skip to main content
Configure Agnost analytics by passing a configuration object to control endpoints, tracking behavior, and data collection. The configuration object is optional. If not provided, Agnost uses default settings.
  • Python
  • TypeScript
  • Go
from agnost import track, config

# With custom configuration
track(your_server, "your_org_id", config(
    endpoint="https://api.agnost.ai",
    disable_input=False,
    disable_output=False
))

​
Configuration Options

  • Python
  • TypeScript
  • Go
FieldTypeDefaultDescription
endpointstr"https://api.agnost.ai"API endpoint URL for analytics data
disable_inputboolFalseWhether to disable tracking of input parameters
disable_outputboolFalseWhether to disable tracking of output responses
identifyfunctionNoneFunction to identify users from request context

​
User Identification

All SDKs support user identification to track analytics per user. This helps you understand usage patterns across different users and roles.
  • Python
  • TypeScript
  • Go

​
Basic User Identification

from agnost import track, config

# Track with user identification
track(server, 'your-org-id', config(
    identify=lambda req, env: {
        'userId': req.get('headers', {}).get('x-user-id') or env.get('USER_ID') or 'anonymous',
        'email': req.get('headers', {}).get('x-user-email') or env.get('USER_EMAIL'),
        'role': req.get('headers', {}).get('x-user-role') or env.get('USER_ROLE', 'user')
    }
))

​
Advanced User Identification

from agnost import track, config
import jwt

async def identify_user(req, env):
    try:
        # Extract token from headers
        auth_header = req.get('headers', {}).get('authorization', '')
        if not auth_header.startswith('Bearer '):
            return {'userId': 'anonymous'}

        token = auth_header.replace('Bearer ', '')
        # Decode JWT token
        decoded = jwt.decode(token, verify=False)

        return {
            'userId': decoded.get('sub'),
            'email': decoded.get('email'),
            'role': decoded.get('role', 'user'),
            'organization': decoded.get('org'),
            'subscription': decoded.get('plan')
        }
    except Exception as e:
        print(f"User identification failed: {e}")
        return {'userId': 'anonymous'}

track(server, 'your-org-id', config(
    identify=identify_user
))

​
User Identity Dictionary

The identify function should return a dictionary with at least a userId field:
{
    'userId': str,      # Required: Unique user identifier
    # Optional: Any additional user properties
    'email': str,
    'role': str,
    'organization': str,
    # ... any other custom fields
}

​
Identify Function Parameters

  • req: The incoming MCP request dictionary containing:
    • headers: HTTP-style headers (e.g., x-user-id, authorization)
    • params: Request parameters including tool name and arguments
    • Other request metadata from the MCP protocol
  • env: Environment variables dictionary (from os.environ), useful for:
    • Reading user info from environment variables
    • Accessing configuration secrets
    • Getting deployment-specific user context

​
Common Usage Patterns

​
1. Header-based Identification

identify=lambda req, env: {
    'userId': req.get('headers', {}).get('x-user-id', 'anonymous'),
    'role': req.get('headers', {}).get('x-user-role', 'user')
}

​
2. Environment Variable Identification

identify=lambda req, env: {
    'userId': env.get('USER_ID') or env.get('LOGGED_IN_USER') or 'anonymous',
    'workspace': env.get('WORKSPACE_ID')
}

​
3. Token-based Identification

import jwt

def identify_from_token(req, env):
    auth = req.get('headers', {}).get('authorization', '')
    if auth.startswith('Bearer '):
        token = auth.replace('Bearer ', '')
        decoded = jwt.decode(token, verify=False)
        return {
            'userId': decoded.get('sub'),
            'email': decoded.get('email'),
            'role': decoded.get('role')
        }
    return {'userId': 'anonymous'}

track(server, 'your-org-id', config(identify=identify_from_token))

​
Important Notes

  • The userId field is required in the returned user identity object
  • If identification fails, return null, None, or { userId: 'anonymous' }
  • User identification happens once per session and is cached
  • Any errors in the identify function are logged and fallback to anonymous tracking
  • Additional fields beyond userId are included in analytics for segmentation
⌘I