TypeScript

The TypeScript SDK wraps servers built with the official MCP TypeScript SDK or Mastra. It captures sessions and tool calls without changing how your server behaves.

Install

npm install @armature-tech/mcp-analytics

The SDK declares @modelcontextprotocol/sdk as a peer dependency. 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 key from the environment:

ANALYTICS_INGEST_API_KEY=<your API key>

Create a key in the dashboard, then add it to your deployment secrets. 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.

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: 500,
    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`	Armature ingest endpoint	Override with `ANALYTICS_INGEST_URL` or this option.
`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`	`500`	Delivery timeout in milliseconds.
`actorId`	Derived from request auth	A string or resolver used to attribute calls to a user. See Identifying users.
`emit`	Network emitter	Replace delivery with your own function — useful in tests.
`onError`	`console.warn`	Called when delivery fails. Failures never reach your tools.

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) and add an onError handler to surface delivery failures.

Getting started

Dashboard

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