Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.waniwani.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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.
1

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
2

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.
3

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

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

​
Install

bun 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.
AddWhat it gives youAPI key
createFlowMulti-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() clientDirect 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.