Configuration

Configure Agnost analytics settings and options

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

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

Field	Type	Default	Description
endpoint	str	"https://api.agnost.ai"	API endpoint URL for analytics data
disable_input	bool	False	Whether to disable tracking of input parameters
disable_output	bool	False	Whether to disable tracking of output responses
identify	function	None	Function 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

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