> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentcat.com/llms.txt > Use this file to discover all available pages before exploring further. # TypeScript reference > Options, transports, delivery, logging, and limits of the AgentCat TypeScript SDK. This page describes the `agentcat` npm package, version 2.x. For the first setup, see [TypeScript setup](https://docs.agentcat.com/languages/typescript.md). ## Options `agentcat.track(server, projectId, options)` takes these options. Every option is optional. | Option | Default | What it does | | - | - | - | | `identify` | none | `(request, extra) => Promise`. Runs on every tool call and names the user of that call. See [Identifying users](https://docs.agentcat.com/languages/typescript.md#identifying-users). | | `enableToolCallContext` | `true` | Adds the `context` parameter to each tool. The agent explains in it why it calls the tool. This is the source of intent data. | | `customContextDescription` | built-in text | Replaces the description of the `context` parameter, for example with domain-specific guidance. Works only when `enableToolCallContext` is `true`. | | `enableReportMissing` | `true` | Adds the `get_more_tools` tool, so agents can report the tools that they looked for and did not find. | | `enableTracing` | `true` | Records tool calls and injects the `session_id` parameter. | | `enableAgentTracking` | `false` | Adds an `agent_id` parameter, in the `required` list of each tool schema. Each agent makes its own ID and sends it on every call. AgentCat puts it on the event as the `agentcat_agent_id` tag. A strict client refuses to send a call without `agent_id`, so this option is off by default. | | `resolveSessionId` | none | `(request, extra) => string \| null`, sync or async. Gives your own task ID for each request. AgentCat then injects no `session_id` parameter. It combines your value with the project ID into one fixed `ses_` ID. A `null` result makes a new session that the agent never learns. | | `redactSensitiveInformation` | none | `(text) => Promise`. Changes every text value before the event leaves your server. | | `redactEvent` | none | `(event) => event \| null`, sync or async. Gets the full event before `redactSensitiveInformation`. The hook returns a changed event, or `null` to drop it. If the hook throws, AgentCat drops the event. | | `eventTags` | none | `(request, extra) => Record \| null`. Adds tags that you can filter on. Keys: 32 characters or fewer, from `[a-zA-Z0-9$_.:\- ]`. Values: strings of 200 characters or fewer, with no newlines. At most 50 tags. AgentCat drops invalid entries and logs a warning. | | `eventProperties` | none | `(request, extra) => Record \| null`. Adds JSON data to each event. | | `exporters` | none | Sends events to `otlp`, `datadog`, `sentry`, or `posthog` too. See [Integrations](https://docs.agentcat.com/integrations.md). | | `apiBaseUrl` | `https://api.agentcat.com` | The address that receives events. If not set, the SDK reads `AGENTCAT_API_URL`, then `MCPCAT_API_URL`. | | `disableDiagnostics` | `false` | Stops the anonymous error reports that the SDK sends to AgentCat. These reports never contain tool calls, responses, or user data. | > [!NOTE] > > We recommend that you keep the defaults of `enableToolCallContext`, `enableReportMissing`, `enableTracing`, and `disableDiagnostics`, because each one feeds a part of the dashboard or helps us fix a broken install. With `enableToolCallContext: false`, the dashboard has no intent data. With `enableReportMissing: false`, agents cannot report missing tools. With `enableTracing: false`, AgentCat records nothing. `UserIdentity` has three fields: `userId` (a string), `userName` (optional), and `userData` (an optional object). A `projectId` of `null` turns on telemetry-only mode: events go to your `exporters` and not to AgentCat. With no project ID and no exporters, the SDK sends nothing and writes a warning to the log. The SDK reads these environment variables: | Variable | What it does | | - | - | | `AGENTCAT_API_URL` | The address that receives events, when `apiBaseUrl` is not set. `MCPCAT_API_URL` is the old name. | | `DISABLE_DIAGNOSTICS` | Stops the anonymous error reports, the same as `disableDiagnostics`. | | `DIAGNOSTICS_TOKEN` | The token for a self-hosted diagnostics collector. | The SDK does not read `AGENTCAT_PROJECT_ID` or `AGENTCAT_DEBUG_MODE`. ## Framework and transport details ### MCP SDK 2.x * `createMcpHandler(factory)` builds a new `McpServer` for each HTTP request, so `track()` goes inside the factory, and the factory returns its result. A Node.js `http` server can serve the handler through `toNodeHandler` from `@modelcontextprotocol/node`. On Cloudflare Workers, the Worker calls `handler.fetch(request)`. * `serveStdio(factory)` from `@modelcontextprotocol/server/stdio` builds a new `McpServer` for each connection, so `track()` goes inside the factory. * A long-lived `McpServer` on `NodeStreamableHTTPServerTransport` needs one `track()` call at start. All instances share one event queue, one set of exporters, and one diagnostics client. AgentCat builds them on the first `track()` call. ### MCP SDK 1.x `track()` accepts the high-level `McpServer` and the low-level `Server`, on stdio and on `StreamableHTTPServerTransport`. A stateless 1.x server (no `sessionIdGenerator`) creates a new server for each request, so each one needs its own `track()` call. ### What `track()` changes in your server * Each tool schema gets `session_id` and `context` (and `agent_id` with `enableAgentTracking`). AgentCat removes these values before your handler runs. * AgentCat removes `additionalProperties: false` from tracked input schemas. * On the first call of a task, the result starts with a text block that gives the agent its new `session_id`. For a tool with an object `outputSchema`, AgentCat also puts the ID in `structuredContent`. * If your tool already declares `session_id`, `agent_id`, or `context`, AgentCat leaves that parameter alone and writes a line to the log. A tool with its own `session_id` sends its events with no session. * Tools that you register after `track()` are tracked too. * `track()` returns the server. A second `track()` on the same instance does nothing. ## Runtimes, delivery, and shutdown The `identify`, `resolveSessionId`, `eventTags`, and `eventProperties` hooks run at the same time as your tool handler. They never delay the tool call. AgentCat waits up to 30 seconds for each hook, then sends the event without that value. AgentCat puts each event in a queue in the process and sends it in the background. It sends up to 5 events at the same time, and tries again 3 times (after 1, 2, and 4 seconds). The queue holds up to 10,000 events. When the queue is full, AgentCat drops the oldest event. On Node.js, the SDK listens for `SIGINT`, `SIGTERM`, and `beforeExit`. It waits up to 5 seconds for the queue to empty. Then it sends the signal again, so that the process stops as usual. If your code has its own listener for the signal, the SDK does not send the signal again, and your listener controls the exit. On Cloudflare Workers, the package loads its `workerd` build. This build gives each event delivery to `waitUntil`, so the Worker stays alive until AgentCat sends the event. ## Logging and debug mode The SDK has no debug option. It always writes its log to `~/agentcat.log`, and never to stdout, because stdout carries JSON-RPC on a stdio server. On Cloudflare Workers, the log goes to the console. If the process has no home directory, the SDK writes no log. Useful log lines: * `AgentCat setup complete | project ... | tracing=true context=true reportMissing=true`: `track()` worked. * `Successfully sent event ... | `: an event reached AgentCat. The last value is the user ID from `identify`, or `anonymous`. * `Warning: Failed to track server`: the server shape is not supported. `track()` returns the server untracked. ## Testing In a test run (`VITEST`, `JEST_WORKER_ID`, or `NODE_ENV=test`), the SDK turns off diagnostics. It still sends events when it has a project ID. If you prefer that tests send no events, you can leave `AGENTCAT_PROJECT_ID` unset in the test environment. AgentCat changes your tool schemas. If your tests compare exact schemas, they see `session_id` and `context` after your own parameters. ## Differences and known limits * `identify` runs on every tool call. AgentCat keeps no identity cache. The hook runs at the same time as your handler, so it cannot prepare state for the handler. * Each event carries the request context (`extra`), with the HTTP headers. The `redactEvent` hook can remove a header before the event leaves your server. * AgentCat cuts each string to 32 KB, each event to 100 KB, and the intent text to 2,048 characters. Objects keep at most 10 levels and 100 keys or items for each level. * `publishCustomEvent(server, projectId, data)` sends an event with no session, unless `data.sessionId` gives one. See [Custom events](https://docs.agentcat.com/sdk/custom-events.md). * The old package name is `mcpcat`. It still works, but new features go to `agentcat`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.