Instrument an MCP server

On this page

An MCP server is a surface of its own. An install never reaches your server: the person adds the connector in the MCP client, and the calls your server handles are tool calls. Each call is the arrival, and one event per call turns an install that is otherwise invisible into a journey with steps in it.

Send the call as an event named tool_call, source sdk, with properties { "tool": "search_docs", "mcp_client": "claude", "status_code": 200, "duration_ms": 42 }. mcp_client is the connector's name, status_code 400 and above marks a failed call, and duration_ms is optional. Send the two numbers as numbers; a numeric string such as "500" is read as the number it spells, which is what a hand-built JSON body or a YAML config often produces. Any event carrying a properties.mcp_client gives its journey the surface mcp when nothing declares one, so a connector's journey is not labelled with the chat client it runs in. A session made only of tool_call events classifies as a declared agent on the strength of properties.mcp_client, so its calls count as agent journeys. Pass the MCP session id as sessionOf anyway (the wrapper sends it as session_hint, so one connector session becomes one journey), and send an account_id when you have one so its payments are credited to it.

examples/mcp-track.js is a dependency-free wrapper for this: one file, no dependencies, built to be copied into your MCP server. curl -sS https://alg.katrinalaszlo.com/mcp-track.js -o mcp-track.js fetches it, and the repository keeps it at examples/mcp-track.js. Copy it beside the code that defines your tools and import it:

js
import { trackToolCalls } from "./mcp-track.js"; // copied from examples/mcp-track.js

const track = trackToolCalls({
  key: process.env.AGENT_TRAFFIC_KEY,
  projectId: process.env.AGENT_TRAFFIC_PROJECT_ID,
  client: "claude", // sent as properties.mcp_client
  sessionOf: (context) => context?.sessionId, // one MCP session: the calls become one journey
});

// The wrapped handler keeps its signature; register it with your MCP framework as before.
const search_docs = track.wrap(async ({ query }) => searchDocs(query), "search_docs");

It throws at startup when the key or the project id is missing, rather than failing one call at a time. A send never blocks the tool and never throws into it: a failed send goes to onError, and await track.flush() before the process exits waits for the sends still in flight. A handler that throws is recorded with status_code 500 and rethrown unchanged.

Pass accountOf(context) to return the caller's hashed account_id. With one, the call joins that account's journey like any other step and appears in the MCP tools card on the Journeys page, which lists each tool with its calls, failed calls, journeys and median duration. Without one, the call is counted in totals but belongs to no journey.