agnost weekly downloads statistics

Agnost Analytics SDK (TypeScript)

Analytics SDK for tracking and analyzing Model Context Protocol (MCP) server interactions.

Installation

Setup Example

Configuration Example

Disabling All Logs

To completely disable all SDK logs (including error logs), you can use the disableLogs option:

Alternatively, you can use environment variables:

User Identification

The SDK supports user identification to track analytics per user. This is especially useful for understanding usage patterns across different users and roles.

Basic User Identification

Advanced User Identification

User Identity Interface

The identify function should return a UserIdentity object or null:

Identify Function Parameters

• request: The incoming MCP request object 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 from process.env, useful for: • Reading user info from environment variables • Accessing configuration secrets • Getting deployment-specific user context

Common Usage Patterns

1. Header-based Identification

2. Environment Variable Identification

3. Token-based Identification

Important Notes

• The userId field is required in the returned UserIdentity object • If identification fails, return null or { userId: 'anonymous' } • User identification runs per request — safe for concurrent, multi-user servers • Any errors in the identify function are logged and fallback to anonymous tracking • Additional fields beyond userId are included in analytics for segmentation • The raw Authorization header value is never sent to Agnost; only the fields your identify function (or the built-in fallback) returns

Built-in bearer identification (zero config)

If you do NOT provide an identify function, the SDK derives the user id from the request's Authorization: Bearer header automatically. If the MCP auth middleware exposes a validated token as extra.authInfo.token but extra.requestInfo.headers is empty, the SDK uses that token as a fallback.

1. Decode: if the token is a JWT (3 parts) with a decodable payload, the first present identifier claim becomes the userId — in order: sub, user_id, userId, email, preferred_username, username. (No signature verification — your own auth middleware has already validated the token.) 2. Hash: any other token — opaque API keys, 2-part shapes, JWEs, undecodable or claimless JWTs — becomes tok_, a stable pseudonymous per-token id. The raw token is never used as an id and never leaves the process. Note: tokens that rotate (JWE/refresh-style) mint a new pseudo-user per rotation. 3. x-api-key fallback: when there is no Authorization header, an x-api-key header (de facto standard for API-key auth) is hashed the same way. 4. OAuth authInfo fallback: when headers are unavailable, the SDK also reads identity from authInfo.sub, authInfo.claims, authInfo.tokenPayload, authInfo.extra, authInfo.token, authInfo.accessToken, or authInfo.access_token. If your OAuth verifier sets authInfo.extra.userId and authInfo.extra.tokenId, Agnost uses userId for user attribution and tokenId to create a durable OAuth conversation id (oauth:{orgId}:{tokenId}) for stateless HTTP servers.

For OAuth MCP servers, keep the official transport path so headers reach MCP handlers:

If you use a custom transport or manual message dispatch, pass the MCP extra object yourself:

Do not log raw bearer tokens. If your OAuth middleware validates the token, attach stable non-secret identity on authInfo.extra:

Conversations on stateless servers

Session (conversation) grouping precedence, per request:

1. MCP session id (Mcp-Session-Id / extra.sessionId) — stateful servers keep today's grouping. 2. OAuth token id (authInfo.extra.tokenId) — stateless OAuth servers group calls by the durable authorization record: oauth:{orgId}:{tokenId}. 3. User id — stateless servers (new server per request, no session id) group all of a user's tool calls into one conversation: user:{orgId}:{userId}. 4. Anonymous stateless HTTP requests merge into one shared conversation per SDK process (anon:{orgId}) — unattributable traffic is aggregated rather than flooding your dashboard with single-call conversations.

Known limitation

One org per process: the first trackMCP call pins the orgId and endpoint for the process lifetime. A later call with a different orgId logs an error and records under the pinned org.

Configuration Options

| Option | Type | Default | Description |

| endpoint | string | "https://api.agnost.ai" | API endpoint URL | | disableInput | boolean | false | Disable tracking of input arguments | | disableOutput | boolean | false | Disable tracking of output results | | disableError | boolean | false | When disableOutput is true, errors take precedence and the error message is still captured. Set this to true to drop errors as well. | | disableLogs | boolean | false | Completely disable all SDK logs | | identify | IdentifyFunction | undefined | Function to identify users from request context |

Performance Monitoring with Checkpoints

The TypeScript SDK provides a powerful checkpoint() function for detailed latency breakup of tool calls. Checkpoints allow you to track specific points in your tool's execution, providing granular observability into where time is being spent.

Overview

When analyzing tool performance, knowing the total execution time is often not enough. The checkpoint() function lets you mark specific points in your execution flow to understand:

• Which operations are slow • Where bottlenecks occur • How time is distributed across different phases • Performance impact of external API calls, database queries, or processing steps

All checkpoint data is automatically captured and visualized in the Agnost AI dashboard with interactive timeline charts.

Function Signature…

Description from the npm listing.