Send Visit Events From Your Node.js Backend

Step 1: Install the NPM Package

Download the package from NPM using the command line.

npm install @knownagents/sdk

Step 2: Initialize the Client

In your code, create an instance of KnownAgents with your project's access token.

import { KnownAgents } from "@knownagents/sdk"

const knownAgents = new KnownAgents("YOUR_ACCESS_TOKEN")

• Navigate to the Known Agents Projects page and open your project
• Copy your access token from the Settings page
• Back in your code, swap in your access token where it says YOUR_ACCESS_TOKEN

Step 3: Track Visits

Track pageviews, MCP calls, and agentic commerce interactions.

Track Pageviews

Call trackPageviewOrRESTCall with the incoming request and outgoing response for each pageview. If you can, do this in middleware.

knownAgents.trackPageviewOrRESTCall(request, response)

High traffic websites should not use this method. Instead, batch visits and send them periodically with trackVisits. See the NPM page for an example.

Track MCP Calls (Optional)

For MCP servers that use StreamableHTTPServerTransport, call trackMCPCall after connecting the transport and before the transport handles the request.

High traffic websites, or those that use the same transport instance to handle multiple concurrent requests, should not use this method. Instead, batch visits and send them periodically with trackVisits. See the NPM page for an example.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"

// ...

const mcpServer = new McpServer({
    name: SERVER_NAME,
    version: SERVER_VERSION,
})

const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined
})

// ...

await mcpServer.connect(transport)

knownAgents.trackMCPCall(request, response, transport)

await transport.handleRequest(request, response, parsedBody)

Track Agentic Commerce Interactions (Optional)

Track agentic commerce interactions using ACP or UCP over REST or MCP.

Over REST

Call trackPageviewOrRESTCall with the incoming request, outgoing response, and response body.

// For ACP agentic commerce interactions ...

knownAgents.trackPageviewOrRESTCall(request, response, {
    acpResponseBody: acpResponseBody
})

// For UCP agentic commerce interactions ...

knownAgents.trackPageviewOrRESTCall(request, response, {
    ucpResponseBody: ucpResponseBody
})

Over MCP

trackMCPCall automatically tracks agentic commerce interactions using ACP or UCP over MCP. No additional setup beyond the MCP tracking above is required.

Step 4: Test Your Integration

• Navigate to the Projects page
• Select your project
• Click Settings
• Click Send a Test Visit
• Click Realtime

If your website is correctly connected, you should see visits from a test agent in the realtime timeline within a few seconds.