Skip to main content
When AgentCat knows who made each tool call, the dashboard can show who uses your server, how often each user comes back, and which sessions belong to one person. Without identity, each session stays anonymous.
We strongly recommend that you identify your users. If you prefer not to send user details, a stable anonymized ID still keeps the events of one user together.

Two levels of identity

We recommend the first of these two levels that your server can give:
  1. Full identity (recommended). Your server reads the user from the request, for example from a bearer token or an API key, and gives AgentCat a user ID and a name. The dashboard then shows real users.
  2. Anonymized identity (the minimum). Your server gives AgentCat a stable ID that reveals nothing about the user, for example a hash of the token or API key. The same user always gets the same ID, so you can still count users and follow each one across sessions.

How the identify hook works

Each SDK has an identify hook (Identify in Go and C#, setIdentify in Java). You pass it in the options of track(), and AgentCat calls it for each tool call:
  • The hook gets the call, with the tool arguments and, on HTTP transports, the request headers. A stdio server has no HTTP headers, so the hook can read the key that your server already uses, for example from an environment variable.
  • The hook returns a user ID, an optional name, and optional extra data. If it returns nothing, the call stays anonymous.
  • If the hook fails or takes too long, the event still goes out, without identity. Each language page describes how its SDK handles a slow or failing hook.
  • On a stateless server, the hook runs in the same way, because AgentCat tracks each server instance that your factory creates.
We recommend a hook that returns the same ID for the same user on every call, because a random value or a timestamp splits one user into many. Keep raw tokens, API keys, and passwords out of the user ID, the name, and the extra data, because AgentCat stores and shows them.

Example

This is the full-identity example from the TypeScript and Python setup pages. getUserByToken and get_user_by_token stand for your own lookup:

Identity in your language

Each setup page has an “Identifying users” section with both levels for each MCP library that it supports, and each reference page describes the hook arguments and the identity fields:

When identity is not possible

Some servers have no login at all, for example a public demo. AgentCat still records every tool call, and each session stays anonymous. If your server gets a login later, adding the hook then is all that it takes.