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.

Where your MCP server runs is independent of whether you connect the WaniWani Platform. This page covers the two server-hosting options. The Platform layer (tracking, KB, chat, hosted state) works the same in both.

Managed Hosting

WaniWani hosts your app. Provisioned, pre-configured, push to main and it deploys. Fastest path.

Self-hosted

You host the app yourself. Docker, Alpic, or Vercel. Connect by giving us the MCP URL.
Both paths use the same MCP Distribution Template. Pick based on where you want the server to live.

​
Managed Hosting

When you create a managed project in the WaniWani dashboard, we provision a copy of the distribution template fully wired up: API keys set, hosted URL assigned, everything ready. You don’t configure anything. Typical workflow:
1

Create the project

From app.waniwani.ai, create a managed project. We spin up a repo from the template and deploy it on our managed hosting. Your tools, flows, widgets, and chat surface are live immediately.
2

Take ownership of the code

Move the provisioned repo into your own GitHub organization when you want full control over the codebase. You keep the managed hosting; you just own the source now.
3

Push to main

Every push to main auto-deploys to our managed hosting environment. API keys, URLs, and tracking continue to flow without any setup on your side.
Best for: getting started fast, teams that don’t want to run infrastructure, and projects that want one less moving part to maintain.

​
Self-hosted server

You run the server. By default we recommend connecting the Platform: set WANIWANI_API_KEY and you get hosted state + dashboards on top of your self-hosted server, with no extra infra. If you want to push that further and self-host the state layer too, see Advanced: bring your own session cache below. If you want zero Platform dependency at all (no API key, no outbound calls), see the open-source self-hosting walkthrough. The MCP Distribution Template ships three deployment targets. Pick whichever fits your stack.

Docker

Run anywhere a container runs.

Alpic

MCP-native runtime.

Vercel

One command from the template root.

​
Docker

The template ships a Dockerfile. Build and run anywhere a container runs (Fly.io, Render, Railway, ECS, GCP Cloud Run, your own VPS, Kubernetes). 
docker build -t my-mcp-app .
docker run --env-file .env -p 3000:3000 my-mcp-app
Set WANIWANI_API_KEY and any backend secrets in the runtime’s environment.

​
Alpic

Deploy to Alpic, an MCP-native hosting runtime. Follow Alpic’s deployment instructions for the template repo. The SDK is tested against the Skybridge runtime, so flows, tracking, and widgets work out of the box.

​
Vercel

vercel deploy
From the template root. Set WANIWANI_API_KEY and any backend secrets in your Vercel project’s environment variables.

​
Connect to WaniWani

Once your app is deployed, copy its public MCP URL (the endpoint where MCP clients send initialize / tools/call requests). In the WaniWani dashboard, create a self-hosted project and paste that URL. WaniWani uses it as the entry point for chat requests, widget rendering, and analytics ingestion.

​
Advanced: bring your own session cache

By default a self-hosted server uses WaniwaniKvStore for flow state when WANIWANI_API_KEY is set (encrypted at rest, hosted by WaniWani, no infra). That’s the recommended setup. If you want zero dependency on app.waniwani.ai for state too, plug in your own KvStore adapter at .compile() time: 
import { createFlow } from "@waniwani/sdk/mcp";
import { flowStore } from "./kv-store"; // your Redis / Upstash / DynamoDB / SQLite adapter

const flow = createFlow({ /* ... */ }).compile({ store: flowStore });
See KV store adapters for recipes (Redis, Upstash, Cloudflare KV, DynamoDB, SQLite) and the full open-source self-hosting walkthrough. Your server, your state. You can still send tracking events to the Platform by calling withWaniwani(server), or skip that entirely for a fully open-source setup.

​
Platform features are orthogonal

Tracking, KB, chat, funnel analytics, and hosted state are Platform features. They are independent of where your server lives and where your state lives. Both Managed Hosting and self-hosted servers emit events through withWaniwani(server) and client.track(), and both surface in the same WaniWani dashboard. See the Platform overview for what’s included and Tracking for the event pipeline.