Track API Calls With the Node.js SDK

Step 1: Install the NPM Package

Download and include the package via NPM:

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 API Calls

Call trackVisit with the incoming request and outgoing response. If you can, do this in middleware.

knownAgents.trackVisit(request, response)

MCP

For MCP endpoints, call trackVisit from each tool handler.

import { createMcpHandler, McpServer } from "@modelcontextprotocol/server"

const mcpHandler = createMcpHandler(({ requestInfo }) => {
    const server = new McpServer({
        name: SERVER_NAME,
        version: SERVER_VERSION,
    })

    server.registerTool("ping", { description: "Check whether the server is available" }, async (context) => {
        const result = {
            content: [{ type: "text", text: "pong" }]
        }

        knownAgents.trackVisit(requestInfo, undefined, {
            mcp: {
                context: context,
                result: result
            }
        })

        return result
    })

    return server
})

Agentic Commerce

For ACP and UCP endpoints, include the response body in trackVisit.

ACP

knownAgents.trackVisit(request, response, {
    acp: {
        responseBody: acpResponseBody
    }
})

UCP

knownAgents.trackVisit(request, response, {
    ucp: {
        responseBody: ucpResponseBody
    }
})

Step 4: Test Your Integration

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

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