How It Works

Mistflow is built on a simple principle: your AI editor is smart enough to build apps, it just needs the right tools.

Those tools ship as a single MCP server (@mistflow-ai/mcp) — 14 discrete tools for auth, planning, scaffolding, building, deploying, and QA. Your editor talks to the server over stdio/JSON-RPC.

Architecture

┌──────────────────┐     MCP (stdio)     ┌──────────────────┐
│   AI Editor      │ ◄──────────────────► │  @mistflow-ai/   │
│  (Claude Code,   │   JSON-RPC 2.0      │  mcp (local)     │
│   Cursor, etc.)  │                      └────────┬─────────┘
│                  │                               │ HTTPS
└──────────────────┘                               ▼
                                          ┌──────────────────┐
                                          │  Mistflow Cloud  │
                                          ├──────────────────┤
                                          │  Plan + Deploy   │
                                          │  Edge Runtime    │
                                          └──────────────────┘

Fire-and-poll for long-running work

Every MCP client enforces a per-tool-call ceiling (~60s). Mistflow’s long-running operations — mist_plan, mist_install, mist_build, mist_qa, mist_deploy — routinely exceed that. Each of those tools uses the same shape:

1. First call spawns the work detached and returns immediately with { status: "running", jobId }.
2. Subsequent calls with the same jobId return current state (running / complete / failed) in under a second.
3. The AI polls until it sees a terminal status.

Install/build/qa jobs are detached Node subprocesses on your machine — state lives at ~/.mistflow/jobs/<jobId>/. Plan/deploy jobs use a backend-side conversation id and poll backend endpoints. Same fire-and-poll shape for both.

Mistflow never calls an LLM. Your editor does all the reasoning. The server is a pure tool orchestrator.

The 14 tools

Shape	Tool	What it does
sync	mist_setup	Authenticate via device code flow.
sync	mist_project	Read/write project state; browse design + integration catalogs.
sync	mist_browser	Navigate, click, type, screenshot the running app.
sync	mist_help	Full tool reference + end-to-end chain examples.
sync, iterative	mist_plan	Generate or modify a plan. Returns clarifying questions; polls the backend while Sonnet runs.
sync, iterative	mist_mockup	Generate a grayscale wireframe for user approval.
sync	mist_init	Scaffold a new project from a plan (transactional).
sync	mist_implement	Execute one plan step at a time.
sync	mist_debug	Parse a failed build into structured errors.
sync	mist_config	Manage env vars and custom domains.
fire-and-poll	mist_install	Run npm install detached.
fire-and-poll	mist_build	Run npm run build detached.
fire-and-poll	mist_qa	Run Playwright against the deployed app.
fire-and-poll	mist_deploy	Tar, upload, orchestrate deploy, poll for live URL.

See the tool reference for the complete list with call signatures.

Cloud

The Mistflow cloud handles:

• Project and org management
• Plan generation (the LLM call lives here, fronted by the MCP server’s fire-and-poll wrapper)
• Deployment to Mistflow Cloud’s edge runtime
• Domain management and DNS
• Provenance tracking (which prompt built which feature)

The flow

When you describe an app to your AI editor, here’s what happens:

1. Planning. Your editor calls mist_plan with your description. The backend generates clarifying questions (runs as a background task so the tool call returns in under a second). Your editor polls mist_plan a few times while questions generate, then renders them via its native AskUserQuestion UI. After your answers, a second pair of calls generates the full plan and creative design directions.

2. Mockup (optional). mist_mockup returns a prompt that your editor uses to write a grayscale HTML wireframe for preview. Iterate with feedback, lock with approval before any code is written.

3. Scaffolding. mist_init creates the project, writes an integration contract layer to contracts/, initializes the feature manifest at .mistflow/manifest.json, and sets up the initial file structure. Transactional — if cloud registration fails, no partial scaffold lands locally.

4. Install. mist_install runs npm install as a detached subprocess. Your editor polls every ~15s until it completes.

5. Building. mist_implement executes plan steps one at a time. Each call returns rich context (existing CRUD, stack docs, integration blueprints, acceptance criteria) so your editor writes correct code the first time. Auto-marks the previous step complete on each call.

6. Production build + deploy. mist_build runs the production build detached; on failure it surfaces missing modules so your editor can chain mist_install + mist_build again without asking. mist_deploy tars, uploads, and polls the backend until the deployment is live.

7. QA. mist_qa runs Playwright against the deployed URL. Your editor does NOT reveal the URL to you until QA passes.

8. Iterating. When you ask for changes, the loop picks up from the right place: mist_project action='get' for context → edit, mist_plan with existingPlanId for structural changes, or mist_debug for a bug fix.

Key design decisions

Why fire-and-poll instead of streaming?

MCP’s transport is request/response — streaming progress inside a single tool call is hard to do portably across hosts. Fire-and-poll trades one long call for many short ones: each poll returns in under a second, so the 60s ceiling never bites, and the AI naturally chains through status updates the same way it would narrate a streaming response. Every step is an auditable tool call instead of a silent wait.

Why no built-in AI?

Every AI editor already has an LLM. Adding another one would mean:

• Extra latency (double the AI calls)
• Extra cost (you’d pay for Mistflow’s tokens)
• Conflicts (two AIs disagreeing)

Mistflow stays tool-only, so it’s fast, free, and always aligned with your editor’s reasoning.

Why track provenance?

When an AI builds your app, you lose the “why” behind decisions. Provenance tracking means every file, every feature, and every deploy links back to the prompt that created it. Essential for teams and for debugging.

Note

Provenance data is visible in the dashboard. Your AI can also query it to understand what was already built before making changes.

Why a feature manifest?

Plans can drift from implementation. The manifest turns every feature into a set of verifiable criteria tracked from planned → implemented → verified. See the manifest guide.

Why contracts?

A Zod-backed contract layer derived from your database schema keeps the AI’s form validation, server actions, and API routes in sync when the schema changes. See the contracts guide.

Security model

• Auth: Device code flow, you log in through your browser, credentials stored locally.
• Isolation: Each org’s projects are fully isolated. No cross-org access.
• Code ownership: Your code is yours. Push it to your own GitHub repo at any time.
• Encrypted in transit: All communication over HTTPS. Build artifacts encrypted at rest.