Quickstart
Install the SDK, wrap your MCP server, and see your first event
This guide walks you through adding Yavio analytics to an existing MCP server. By the end, every tool invocation will be tracked automatically.
Prerequisites
- Node.js 20+
- An existing MCP server built with
@modelcontextprotocol/sdk
Get an API key
Create a project in the Yavio dashboard and copy the API key.
For local development, you can skip the dashboard and create a .yaviorc.json file in your project root:
{
"apiKey": "yav_your_key_here",
"endpoint": "http://localhost:3001/v1/events"
}Without an API key, the SDK operates in no-op mode — your server runs normally with zero overhead.
Install the SDK
npm install @yavio/sdkThe SDK has a peer dependency on @modelcontextprotocol/sdk (>= 1.0.0), which you likely already have installed.
Wrap your MCP server
Import withYavio and wrap your McpServer instance. Everything else stays the same.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { withYavio } from "@yavio/sdk";
const server = new McpServer({
name: "my-server",
version: "1.0.0",
});
const instrumented = withYavio(server, {
apiKey: process.env.YAVIO_API_KEY,
});
// Register tools on the instrumented server
instrumented.tool("greet", { name: { type: "string" } }, async ({ name }) => {
return { content: [{ type: "text", text: `Hello, ${name}!` }] };
});That's it. Every tool call is now automatically captured with latency, status, platform detection, and input metadata.
Track users and conversions
Inside any tool handler, use ctx.yavio to identify users and track custom events:
instrumented.tool(
"checkout",
{ userId: { type: "string" }, plan: { type: "string" } },
async ({ userId, plan }, ctx) => {
// Tie this session to a known user
ctx.yavio.identify(userId, { plan });
// Track a custom event
ctx.yavio.track("plan_selected", { plan });
// Record a conversion with monetary value
ctx.yavio.conversion("upgrade", {
value: 49,
currency: "USD",
});
return {
content: [{ type: "text", text: `Upgraded to ${plan}!` }],
};
},
);Verify events
Start your MCP server and invoke a tool. You should see events flowing in the Yavio dashboard within a few seconds.
If you're running locally with the self-hosted stack:
# Start Yavio infrastructure
docker compose up -d
# Start your MCP server
node server.ts
# Invoke a tool (e.g., via the MCP inspector)
# Events appear at http://localhost:3000If events aren't appearing, check the Troubleshooting guide for common issues.