Skip to main content
This page describes the agentcat npm package, version 2.x. For the first setup, see TypeScript setup.

​
Options

agentcat.track(server, projectId, options) takes these options. Every option is optional.
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: 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 ... | <user>: 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.
  • The old package name is mcpcat. It still works, but new features go to agentcat.