Waniwani SDK — Build MCP funnels

Choose your approach

Start from template

Clone a ready-to-go MCP app (server + widgets + UI) with the SDK pre-configured. Best for new projects.

Add to existing project

Install the SDK package into your existing MCP server or app. Best for existing projects.

The SDK is open source and works without an API key. Set WANIWANI_API_KEY to connect the Waniwani Platform and unlock hosted state, tracking, knowledge base, and the chat widget on top.

Option A: Start from template

The MCP Distribution Template gives you a production-ready MCP app (server + widgets + UI) with the SDK, event tracking, flows, and widgets already wired up.

The template is an MCP app. If you only need a bare MCP server (no widgets or embedded UI), skip to Option B or follow the Quickstart. The SDK works for both.

Create your repo

Click “Use this template” on GitHub to create a new repository from the template, or clone it directly:

git clone https://github.com/WaniWani-AI/mcp-distribution-template.git my-mcp-server
cd my-mcp-server

Install and run

bun install
cp .env.example .env
bun dev

The template runs without an API key. Set WANIWANI_API_KEY in .env to connect the Platform and enable hosted state, tracking, and the dashboard.

Customize

The template includes a reference flow (Alpine ski lessons) you can replace with your own. If you have the agent skill installed, run /waniwani-sdk initialize to interactively scaffold a flow tailored to your business.

Option B: Add to existing project

Requirements

Node.js 18.17 or newer (Node 20+ recommended)
An MCP server runtime. The SDK is tested against:
- @modelcontextprotocol/sdk
- Skybridge (Alpic)
- @vercel/mcp-handler
A Waniwani account at app.waniwani.ai — optional, only needed for Platform features.

@modelcontextprotocol/sdk and zod are peer dependencies. Install them in your project if you do not already have them.

Install

bun add @waniwani/sdk

pnpm add @waniwani/sdk

npm install @waniwani/sdk

yarn add @waniwani/sdk

The SDK has zero runtime dependencies and targets a sub-5KB core bundle. It runs in long-lived Node processes, serverless functions, and edge runtimes.

Pick what you need

Three things you can add independently to an existing MCP server. Any subset works.

Add	What it gives you	API key
`createFlow`	Multi-step typed flows registered as a single MCP tool. The primary entry point.	Not required. Required only if you want hosted state instead of bringing a `KvStore`.
`withWaniwani(server)`	Wraps existing `registerTool` handlers to emit tracking events and bridge session IDs. No handler changes.	Required for events. Bridging works without.
`waniwani()` client	Direct calls to Platform APIs (custom events, `identify()`, KB search).	Required.

Add a flow to an existing server

Assume you already have an McpServer instance with some tools registered on it. Define a flow and .register() it alongside them:

import { createFlow, END, MemoryKvStore, START } from "@waniwani/sdk/mcp";
import { z } from "zod";
import { server } from "./mcp-server"; // your existing McpServer

const onboardingFlow = createFlow({
  id: "onboarding",
  title: "User Onboarding",
  description: "Use when a new user wants to get started.",
  state: { name: z.string().describe("Their name") },
})
  .addNode({
    id: "ask_name",
    run: ({ interrupt }) =>
      interrupt({ name: { question: "What is your name?" } }),
  })
  .addEdge(START, "ask_name")
  .addEdge("ask_name", END)
  .compile({ store: new MemoryKvStore() });

await onboardingFlow.register(server);

MemoryKvStore is fine for development and tests. For production, plug in a real backend (Redis, Upstash, Cloudflare KV, DynamoDB) or set WANIWANI_API_KEY to use hosted state. See KV store adapters.

Wrap an existing server for Platform tracking

If your server already has plain registerTool handlers and you just want them tracked, wrap it once. No changes to the handlers themselves:

import { withWaniwani } from "@waniwani/sdk/mcp";
import { server } from "./mcp-server"; // your existing McpServer

withWaniwani(server);

.env

WANIWANI_API_KEY=wwk_...

Every wrapped tool call now emits a tool.called event to your Waniwani dashboard. Without an API key, the wrapper still bridges session IDs and forwards widget metadata but emits no events. Safe to wrap unconditionally. See Wrap your server for all options.

Create a Platform client

The waniwani() client is needed only when you call Platform APIs directly (custom event tracking via track(), identify(), KB search). It is not required for createFlow or withWaniwani.

import { waniwani } from "@waniwani/sdk";

const wani = waniwani();

With no arguments, the client reads WANIWANI_API_KEY from the environment and uses https://app.waniwani.ai as the base URL. See API keys for how to obtain and configure the key, and Client & KV store reference for the full client config.

Also supported

Project config file. Drop a waniwani.json at the project root with $schema set to https://docs.waniwani.ai/waniwani.json. The SDK auto-loads it on the first waniwani() call; the CLI uses the same file for connect/dev/evals. No explicit import required.

Next: get your API key (if you want Platform features), then wrap your MCP server.

Get Started

CLI

Compare

Flow engine

Deployment

Waniwani Platform

Tracking & analytics

Knowledge base

Chat widget

Configuration

Reference

Skills & commands

Build a funnel

Changelog

Installation

Choose your approach

Start from template

Add to existing project

Option A: Start from template

Option B: Add to existing project

Requirements

Install

Pick what you need

Add a flow to an existing server

Wrap an existing server for Platform tracking

Create a Platform client

Also supported

​Choose your approach

Start from template

Add to existing project

​Option A: Start from template

​Option B: Add to existing project

​Requirements

​Install

​Pick what you need

​Add a flow to an existing server

​Wrap an existing server for Platform tracking

​Create a Platform client

​Also supported

Choose your approach

Option A: Start from template

Option B: Add to existing project

Requirements

Install

Pick what you need

Add a flow to an existing server

Wrap an existing server for Platform tracking

Create a Platform client

Also supported