TypeScript

The TypeScript SDK wraps servers built with the official MCP TypeScript SDK (1.x and 2.x), Mastra, punkpeye/fastmcp, or Vercel’s mcp-handler. It captures sessions and tool calls without changing how your server behaves.

Install

npm install @armature-tech/mcp-analytics

Both MCP SDK peers are optional — install the one your server uses (or both): @modelcontextprotocol/sdk (>=1.20 <2) for the package root, the /mastra subpath, and the doctor CLI; @modelcontextprotocol/server 2.x for the /v2 subpath. If your tools use Zod 4 raw-shape schemas, use MCP SDK 1.29 or later — 1.20 silently drops fields added to Zod 4 raw shapes.

Set your API key

The SDK reads your configuration from the environment:

ANALYTICS_INGEST_API_KEY=<your ingest key>
ANALYTICS_INGEST_URL=<your region's ingest URL>

Copy both values from the dashboard when you mint the key. US workspaces can omit ANALYTICS_INGEST_URL (the SDK defaults to the US endpoint); EU workspaces must set it to https://eu.armature.tech/api/mcp-analytics/ingest. If the key is missing, the SDK quietly no-ops — your server keeps working, and no data is sent.

Wrap your server

If you build your server in a factory function, wrap the factory with createMcpAnalyticsServer. Every tool registered inside is instrumented automatically:

server.ts

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { createMcpAnalyticsServer } from "@armature-tech/mcp-analytics";
import { z } from "zod";

const server = createMcpAnalyticsServer(() => {
  const mcp = new McpServer({ name: "customer-mcp", version: "1.0.0" });

  mcp.registerTool(
    "lookup_customer",
    {
      description: "Look up a customer by ID",
      inputSchema: { customer_id: z.string() },
    },
    async ({ customer_id }) => ({
      content: [{ type: "text", text: `customer ${customer_id} is active` }],
    }),
  );

  return mcp;
});

await server.connect(new StdioServerTransport());

That’s the whole integration. Deploy, and sessions appear in the dashboard within minutes.

Other server shapes

Existing server + tool registry

If you already have an McpServer instance and a list of tool definitions, instrument them in place:

import { instrumentMcpServerTools } from "@armature-tech/mcp-analytics";

const { server: instrumented, recorder } = instrumentMcpServerTools({
  server,
  tools, // array or record of { ...toolRegistration, handler }
});

Custom dispatcher

If you handle tools/list and tools/call yourself, use the recorder directly:

import { createAnalyticsRecorder } from "@armature-tech/mcp-analytics";

const analytics = createAnalyticsRecorder();

analytics.tool(toolDefinition, toolHandler);

// tools/list
const tools = analytics.toolDefinitions();

// tools/call
const result = await analytics.dispatch(name, args, context);

Mastra

Wrap a Mastra tool map with the dedicated adapter:

import { wrapMastraTools } from "@armature-tech/mcp-analytics/mastra";

const instrumentedTools = wrapMastraTools(tools);

The adapter reads MCP request context from context.mcp.extra or context.requestContext.get("mcp.extra") automatically.

fastmcp (punkpeye/fastmcp)

Wrap each tool with the adapter from the dedicated subpath:

import {
  withFastmcpAnalytics,
  flushFastmcpAnalytics,
} from "@armature-tech/mcp-analytics/fastmcp";

// Hoist the options: wrap calls sharing this object share one pipeline,
// and flush must receive the same object.
const analyticsOptions = { transport: "httpStream" as const };

server.addTool(withFastmcpAnalytics(tool, analyticsOptions));

// before shutdown:
await flushFastmcpAnalytics(analyticsOptions);

On an httpStream server, keep transport: "httpStream" in the options — without it, anonymous HTTP sessions collapse onto one process-scoped session id. instrumentFastMCP(server, options) wraps every tool at once and detects httpStream on its own. fastmcp validates schemas before execute, so telemetry schema decoration is off by default — opt in with declareTelemetry: true, a top-level key next to armature. The shutdown flush is unnecessary with delivery: "await" or a schedule hook. Details in the SDK README.

Vercel mcp-handler

mcp-handler runs your initialize callback per request with a real official-SDK McpServer, so wrap the server inside the callback and the handler outside it:

import { createMcpHandler } from "mcp-handler";
import { withMcpAnalytics } from "@armature-tech/mcp-analytics";
import { withMcpHandlerAnalytics } from "@armature-tech/mcp-analytics/mcp-handler";

// Hoist the config; use "await" delivery — the callback runs per
// request and a background queue may be frozen.
const analyticsConfig = { armature: { delivery: "await" as const } };

const handler = withMcpHandlerAnalytics(
  createMcpHandler((server) => {
    withMcpAnalytics(analyticsConfig, () => {
      server.registerTool(/* … */);
      return server;
    });
  }),
  analyticsConfig,
);
export { handler as GET, handler as POST };

MCP SDK v2 (@modelcontextprotocol/server 2.x)

Servers on the v2 package family use the dedicated /v2 subpath — the package root still targets the 1.x SDK:

import { createMcpHandler, McpServer } from "@modelcontextprotocol/server";
import {
  instrumentedFactory,
  wrapMcpHandler,
} from "@armature-tech/mcp-analytics/v2";

// Hoist the config: every per-request server shares one pipeline.
const analyticsConfig = {
  armature: { apiKey: process.env.ANALYTICS_INGEST_API_KEY },
};

const handler = wrapMcpHandler(
  createMcpHandler(
    instrumentedFactory(() => {
      const server = new McpServer(/* … */);
      // ...register your tools exactly as before
      return server;
    }, analyticsConfig),
  ),
  analyticsConfig,
);

wrapMcpHandler is strongly recommended: without it, clients on the pre-2026-07-28 protocol silently lose session identity through v2’s stateless legacy leg. The v2 adapter doesn’t decorate tool schemas with the telemetry field by default — restore that with declareTelemetry: true in the adapter options, the third argument: instrumentedFactory(buildServer, analyticsConfig, { declareTelemetry: true }). It is not a key of analyticsConfig. Details in the SDK README.

Running on serverless or stateless HTTP? See Stateless & serverless servers for session handling, and set delivery: "await" so events are sent before the function freezes.

Configuration

Pass options under the armature key:

const server = createMcpAnalyticsServer(buildServer, {
  armature: {
    delivery: "background",
    timeoutMs: 5000,
    onError: (error) => console.warn("analytics delivery failed", error),
  },
});

Option	Default	Description
`apiKey`	`ANALYTICS_INGEST_API_KEY` env var	API key used to authenticate ingestion.
`endpointUrl`	US ingest endpoint	Override with `ANALYTICS_INGEST_URL` or this option; EU workspaces must use the EU endpoint.
`enabled`	`true`	Set `false` to disable capture entirely.
`delivery`	`"background"`	`"background"` posts events off the request path; `"await"` sends before returning (use in serverless).
`timeoutMs`	`5000`	Delivery timeout in milliseconds.
`actorId`	Derived from request auth	A string or resolver used to attribute calls to a user. See Identifying users.
`actorIdentifier`	None	Attach a caller-provided identifier verbatim. See Identifying users.
`emit`	Network emitter	Replace delivery with your own function — useful in tests.
`onError`	None — failures are logged with `console.warn`	Called when delivery fails, including in-body ingest rejections. Failures never reach your tools — set this in production to route them to your logger.
`captureTelemetry`	`true`	Set `false` to disable conversation-derived telemetry while keeping call analytics.
`requestCapability`	On	Injects the `request_capability` tool (see What the SDK captures); set `false` to disable.

Flush on shutdown

With background delivery, drain pending events before the process exits:

import { withMcpAnalytics } from "@armature-tech/mcp-analytics";

const { result: server, recorder } = withMcpAnalytics({}, buildServer);

process.on("SIGTERM", async () => {
  await recorder.flush();
  process.exit(0);
});

Troubleshooting

`Mixed Zod versions detected in object shape`

Fixed in current releases — update the SDK. Older versions crashed when a tool declared a Zod 4 raw-shape schema while the SDK injected its telemetry field with Zod 3.

Sessions show up but telemetry fields are empty

Make sure @modelcontextprotocol/sdk is 1.29+. Version 1.20 silently drops fields the SDK adds to Zod 4 raw-shape schemas, so agents never see them.

No data arrives

Check that ANALYTICS_INGEST_API_KEY is set in the server’s environment (missing keys no-op silently by design), that ANALYTICS_INGEST_URL matches your workspace region — EU keys are rejected by the US endpoint — and search the server log for [mcp-analytics] telemetry emit failed:, the SDK’s default delivery-failure warning. Add an onError handler to route those failures to your own logger.

Getting started

Analytics

Evaluation

SDKs

Armature MCP

Privacy & security

Install

Set your API key

Wrap your server

Other server shapes

Configuration

Flush on shutdown

Troubleshooting

​Install

​Set your API key

​Wrap your server

​Other server shapes

​Configuration

​Flush on shutdown

​Troubleshooting

Install

Set your API key

Wrap your server

Other server shapes

Configuration

Flush on shutdown

Troubleshooting