Waniwani SDK — Build MCP funnels

The SDK is open source and runs without an API key. The Platform is an optional hosted layer at app.waniwani.ai that adds features the engine alone doesn’t ship: event tracking, funnel analytics, a knowledge base, a chat widget, and hosted flow state. The Platform works the same whether your MCP server is on your own infra or on Managed Hosting. A single environment variable, WANIWANI_API_KEY, switches it on.

Two independent choices

Where your server runs and whether you connect the Platform are independent decisions:

	No Platform	With Platform
Self-hosted server	Pure open source. Engine on your infra, no outbound calls.	Your infra for the server, our backend for KB, chat, tracking, and (optionally) state.
Managed Hosting	Not applicable.	Fully managed. We host the server and the Platform.

Pick the combination that fits. Most teams start at “self-hosted + Platform” or “Managed Hosting + Platform”, and a smaller set runs pure open source.

What the Platform adds

Feature	Entry point	What it gives you
Event tracking	`withWaniwani(server)`, `waniwani().track()`	`tool.called` events, custom events, dashboard ingest
Funnel analytics	Automatic from tracked node visits	Conversion, drop-off, completion rate per node
Knowledge base	`@waniwani/sdk/kb`	Markdown ingest, semantic search from any tool
Chat widget	`@waniwani/sdk/chat`	Drop-in chat against your project, in script or React
Hosted flow state	`WaniwaniKvStore` (auto-selected)	Encrypted-at-rest state with zero infra

All of these require WANIWANI_API_KEY. None of them require Managed Hosting.

Enable it

.env

WANIWANI_API_KEY=wwk_...

Create a free key at app.waniwani.ai. See API keys for staging vs production setup. With the key set, createFlow().compile() selects WaniwaniKvStore automatically when no store argument is passed, withWaniwani(server) starts emitting tracked events, and the KB / chat clients work end to end.

What works without it

The engine is fully usable with no key:

createFlow, StateGraph, START, END, redacted from @waniwani/sdk/mcp
KvStore interface and MemoryKvStore (plus any adapter you write for Redis, Upstash, Cloudflare KV, DynamoDB, SQLite)
withWaniwani(server) as a no-op wrapper that still bridges transport session IDs and forwards widget metadata
useWaniwani() browser hook in degrade-to-no-op mode

createFlow().compile() requires a store when no API key is configured. With neither, it throws at compile time:

Error: [waniwani] createFlow "...": no flow store configured.
Pass { store } to .compile(). Use MemoryKvStore from "@waniwani/sdk/mcp"
for local development, or plug in a Redis/Upstash/Cloudflare KV adapter
for production. Alternatively, set WANIWANI_API_KEY to use hosted flow
state on app.waniwani.ai.

This is intentional. No silent fallback to a backend that does not exist in production. See self-hosting the engine for the fully offline path.

Going from open source to Platform

One line. Drop the store argument and set the env var:

- .compile({ store: flowStore });
+ .compile(); // uses WaniwaniKvStore when WANIWANI_API_KEY is set

Existing sessions stay where they started: pre-switch sessions keep reading from your KV backend, new sessions persist on app.waniwani.ai. There is no automatic migration. To keep self-hosted state and only add Platform tracking on top, keep the explicit store and call withWaniwani(server). Tracking fires to app.waniwani.ai; flow state stays in your backend. The two pipelines are independent.

Pricing

The Platform has a free plan. Set the API key and you are in. Limits and paid plans are listed at app.waniwani.ai.

Get Started

CLI

Compare

Flow engine

Deployment

Waniwani Platform

Tracking & analytics

Knowledge base

Chat widget

Configuration

Reference

Skills & commands

Build a funnel

Changelog

Waniwani Platform

Two independent choices

What the Platform adds

Enable it

What works without it

Going from open source to Platform

Pricing

​Two independent choices

​What the Platform adds

​Enable it

​What works without it

​Going from open source to Platform

​Pricing

Two independent choices

What the Platform adds

Enable it

What works without it

Going from open source to Platform

Pricing