Waniwani SDK — Build MCP funnels

Platform feature. Requires WANIWANI_API_KEY. Works whether your MCP server is self-hosted or on Managed Hosting. About the Platform.

A session represents one conversation between a user and an MCP client. Events are grouped into a session by a sessionId that the SDK extracts from the MCP request metadata (_meta). You do not create sessions. You pass meta: extra._meta on every track() call, and the SDK does the correlation.

How session correlation works

The SDK reads the first non-empty string value it finds under these keys of _meta, in order:

waniwani/sessionId
openai/sessionId
openai/session
sessionId
conversationId

The matched value becomes the correlation.sessionId field on the outgoing V2 envelope. The SDK also extracts requestId, traceId, correlationId, and externalUserId from _meta using the same approach. Source is derived from the session key (openai/sessionId -> chatgpt, waniwani/sessionId -> chatbar).

The rule

Always pass meta: extra._meta when tracking events from inside a tool handler.

server.registerTool(
  "get_quote",
  { /* config */ },
  async ({ amount, currency }, extra) => {
    // ... run your business logic

    await wani.track({
      event: "quote.succeeded",
      properties: { amount, currency },
      meta: extra._meta,
    });

    return { content: [{ type: "text", text: "Quoted" }] };
  },
);

If you omit meta and do not set sessionId explicitly, the envelope ships without a session id and the dashboard cannot group it with the rest of the conversation.

Where `_meta` lives

MCP library	Location
`@modelcontextprotocol/sdk`	`request.params._meta` (on the raw request), surfaced as `extra._meta` in tool handlers
`@vercel/mcp-handler`	`extra._meta`

Wherever you see extra._meta in these docs, substitute the equivalent for your runtime.

The scoped client inside tools and flows

When a server is wrapped with withWaniwani(server), each tool invocation receives a request-scoped Waniwani client on extra["waniwani/client"]. The scoped client is also surfaced as context.waniwani inside createTool handlers and as waniwani inside flow nodes. Its track() and identify() methods merge the current request’s _meta automatically, so you do not pass it yourself.

import { createTool } from "@waniwani/sdk/mcp";
import { z } from "zod";

createTool(
  {
    id: "get_quote",
    title: "Get quote",
    description: "Return a price quote",
    inputSchema: { amount: z.number() },
  },
  async ({ amount }, context) => {
    // context.waniwani is the scoped client, meta is already attached
    await context.waniwani?.track({
      event: "quote.succeeded",
      properties: { amount, currency: "USD" },
    });
    return { text: `Quoted ${amount}` };
  },
);

Inside a flow node:

.addNode({
  id: "record",
  run: async ({ state, waniwani }) => {
    await waniwani?.track({
      event: "quote.succeeded",
      properties: { amount: state.amount },
    });
    return {};
  },
})

See Flows for the full node context.

Manual session ids

For background jobs, backfills, or tests where _meta is not available, you can set sessionId explicitly:

await wani.track({
  event: "purchase.completed",
  properties: { amount: 4999, currency: "USD" },
  sessionId: "session_01HX...",
});

Use manual sessionId only when there is no _meta to pass. Inside tool handlers, always prefer meta: extra._meta.

Session lifecycle

The Waniwani backend emits session.started automatically the first time it sees a new sessionId. You do not send it yourself, and session.started in the SDK’s EventType union exists only to type the ingestion envelope. Sessions do not have a hard close. The backend treats them as closed after an idle window. If the user comes back, they either resume the same session (within the window) or start a fresh one, depending on what the host client sends in _meta.

Get Started

CLI

Compare

Flow engine

Deployment

Waniwani Platform

Tracking & analytics

Knowledge base

Chat widget

Configuration

Reference

Skills & commands

Build a funnel

Changelog

Sessions

How session correlation works

The rule

Where `_meta` lives

The scoped client inside tools and flows

Manual session ids

Session lifecycle

​How session correlation works

​The rule

​Where _meta lives

​The scoped client inside tools and flows

​Manual session ids

​Session lifecycle

How session correlation works

The rule

Where `_meta` lives

The scoped client inside tools and flows

Manual session ids

Session lifecycle