AI agents and MCP

Let a coding agent add Trace, or query events over MCP.

Trace is built to be used by AI agents as well as people: an MCP server for assistants such as Claude, a machine-readable API description, docs in a form language models read well, and a prompt that lets a coding agent integrate it into your app.

MCP server

@trace-id/mcp is a Model Context Protocol server. It gives an assistant read-only access to your project through your secret key, so you can ask "why was this signup blocked?" or "which other accounts used this device?" in plain language.

ToolWhat it does
explain_eventThe verdict for an event's suspect score, which signals fired and why, when each can be wrong, other browsers on the same device
get_eventThe full verified event (same as GET /v1/events/:eventId)
get_visitorA visitor's history, paginated
get_deviceEvery browser and account on one device (multi-accounting investigations)
list_signalsThe signal catalog, offline
delete_visitorPermanent deletion for a data request. Only present with TRACE_ALLOW_DELETE=true, marked destructive, and requires confirm: true

Configuration is two environment variables: TRACE_ENDPOINT (your server, e.g. https://id.example.com) and TRACE_SECRET_KEY (sk_...). Use a separate secret key for the assistant so you can revoke it on its own.

Claude Code:

Terminal
claude mcp add trace -e TRACE_ENDPOINT=https://id.example.com -e TRACE_SECRET_KEY=sk_... -- npx -y @trace-id/mcp

Claude Desktop, Cursor and other clients that read an mcpServers file:

JSON
{
  "mcpServers": {
    "trace": {
      "command": "npx",
      "args": ["-y", "@trace-id/mcp"],
      "env": { "TRACE_ENDPOINT": "https://id.example.com", "TRACE_SECRET_KEY": "sk_..." }
    }
  }
}

From a checkout (before the package is published), use "command": "node", "args": ["/path/to/trace/packages/mcp-server/dist/cli.js"] after npm run build.

The server speaks MCP over stdio (protocol versions 2025-06-18, 2025-03-26 and 2024-11-05) and writes nothing but protocol messages to stdout. API failures come back as tool errors the model can read (invalid_api_key (HTTP 401): ...), not as crashes.

OpenAPI

Every server publishes its API description at GET /openapi.json (OpenAPI 3.1, no key needed). Point client generators, API tools or agents with an HTTP tool at it. It covers identify, events, visitors, devices, webhooks and health, including every signal id.

Docs for language models

The docs site serves /llms.txt, an index of every page, and /llms-full.txt, all pages in one plain-text file, following the llms.txt convention. Give either to an assistant before asking it about trace.

Integrating with a coding agent

Paste this into Claude Code, Cursor or a similar agent in your app's repository, after filling in the two values:

Text
Integrate Trace device identification into this app.
Server: https://id.example.com (public key pk_..., secret key in the TRACE_SECRET_KEY environment variable).
Docs: https://<docs-site>/llms-full.txt and the API at https://id.example.com/openapi.json.

1. Add the browser SDK for this app's framework (@trace-id/sdk-js, sdk-react, sdk-vue or sdk-svelte). Call it on
   signup, login and checkout with linkedId set to our internal user id (never an email), and send the returned
   eventId with the form request.
2. On the backend, verify that eventId with the server SDK for this language (sdk-node, Python, PHP, Java) or
   GET /v1/events/:eventId. Never trust the visitorId or score the browser sends.
3. Policy: suspectScore >= 60 -> block or challenge; 25-59 -> challenge; signals.multiAccount.detected -> flag for
   review. Log the eventId with the decision.
4. If the Trace call fails or times out (2 s), let the request continue (fail open) and log it.
5. Add tests with the SDK mocked, and show me the diff.

The agent finds the rest in the docs: consent (enabled: false), first-party mode, webhooks and sealed results.

Agents as visitors

Browser agents (computer-use assistants, headless automation) are bots by definition and the bot, automatedInput and antiDetect signals are designed to see them. If you want to admit some, decide on your backend: for example allow a known agent's requests by your own authentication, and use the signals only for anonymous traffic.

Suggest an edit

Spotted something wrong or unclear? Tell us on GitHub and we will fix it.