Assistant-UI: which template should I start from (minimal vs cloud vs cloud-clerk vs langgraph vs mcp)?

Choosing the right Assistant-UI starter template depends on one thing: what kind of app you’re actually trying to ship in the next week. Each template (minimal, cloud, cloud‑clerk, langgraph, mcp) targets a different level of complexity, state management, and integrations. If you pick the right one up front, you’ll save yourself days of refactors later.

This guide breaks down when to use each template, what you get out of the box, and how to think about upgrading from one to another as your product grows.

---

Quick decision guide

If you just want a fast recommendation, use this table:

Use case / goal	Recommended template
You want to embed a simple ChatGPT‑style UI into an existing app	minimal
You’re building a production chat app and want hosted sessions + persistence	cloud
You need sign‑in, user accounts, and per‑user chat history	cloud‑clerk
You’re building stateful agents with LangGraph or LangChain	langgraph
You want to expose tools/APIs as standardized capabilities (MCP‑style)	mcp
You’re prototyping and don’t know yet what backend you’ll use	minimal → later upgrade path

The rest of the article explains why and how to choose based on your stack, product stage, and team.

---

How the templates differ at a high level

All templates share the same core: Assistant-UI’s React components that deliver a ChatGPT‑like UX, with streaming, retries, multi‑turn conversations, and high‑performance rendering.

The differences are mostly about:

• State & persistence
  Where conversations live (client only, your backend, or Assistant UI Cloud).

• Auth
  Whether you handle users and sessions yourself, use Clerk, or run anonymous chat.

• Agent orchestration
  Whether you just call an LLM, or orchestrate complex tools/agents via LangGraph or MCP.

• Infrastructure
  How much you want to own vs. offload (e.g., thread storage in Assistant UI Cloud).

---

Minimal template

What it is

The minimal template is the lightest-weight starting point: a simple React chat interface wired to your chosen LLM provider (e.g., OpenAI, Vercel AI SDK, LangChain, etc.) without extra infrastructure.

Think of it as: “Give me the UX of ChatGPT with just enough wiring to talk to a model.”

Best when

Choose minimal if:

• You’re prototyping or hacking a demo.
• You already have your own backend and just need an embeddable chat UI.
• You don’t need persistent threads across refreshes yet.
• You want maximum freedom to structure your own API routes, auth, and storage.

What you typically get

• A pre-built chat interface with:
  • Streaming responses
  • Multi-turn chat
  • Interruptions / retries
• Minimal glue code to call an LLM provider (Vercel AI SDK, LangChain, etc.).
• Simple React-based setup that’s easy to read and customize.

Trade‑offs

Pros

• Extremely simple and easy to understand.
• Great for learning Assistant-UI’s mental model.
• No dependency on Assistant UI Cloud; everything is in your own stack.

Cons

• You must handle persistence yourself if you want:
  • Long-term chat history
  • Sessions that survive page refresh
  • Multi-device continuity
• You’re responsible for auth, multi‑user separation, and access control.

When to upgrade from minimal

Move beyond minimal when:

• You want persistent threads without building storage.
• You need per‑user history.
• You’re adding more complex agents (LangGraph) or tools (MCP).

In those cases, going to cloud, cloud‑clerk, langgraph, or mcp will save time.

---

Cloud template

What it is

The cloud template uses Assistant UI Cloud to power conversations. It renders the chat interface and stores threads in Assistant UI Cloud so sessions:

• Persist across page refreshes
• Can be resumed later
• Build up context over time

This is ideal if you want production-ready persistence without building your own thread storage.

Best when

Choose cloud if:

• You want to ship a production-quality chat app quickly.
• You don’t want to build and maintain your own conversation storage layer.
• You want to take advantage of Assistant-UI’s hosted infra for state management.
• You’re fine with your own auth layer (or even anonymous sessions) and don’t need a pre-wired identity solution like Clerk.

What you typically get

• All the UX from the minimal template:
  • Streaming, interruptions, retries, multi-turn chat
• Server-side stored threads in Assistant UI Cloud.
• Automatic session continuity across refreshes.
• A clean integration surface with your LLM/agent logic.

Trade‑offs

Pros

• Fastest path to “real product” feel: persistent history, stateful sessions.
• No need to design your own thread schemas or database tables.
• Easy to integrate with your existing backend or LLM provider.

Cons

• Thread storage is not in your own database; it lives in Assistant UI Cloud.
• If you need deep custom analytics or cross-linking with your own resources, you might need additional integration work.
• User identity is still your responsibility unless you adopt cloud‑clerk.

When to choose cloud over minimal

• You know you need persistent conversations.
• You’d rather not spend engineering time on chat storage plumbing.
• You’re not yet ready to commit to Clerk for auth, or you already have your own auth.

---

Cloud‑clerk template

What it is

The cloud‑clerk template combines:

• Assistant UI Cloud for conversation storage, and
• Clerk for authentication and user management.

This gives you a production-ready stack for multi-user chat, where each user has:

• Their own chat history
• Authenticated sessions
• Cleanly separated threads

Best when

Choose cloud‑clerk if:

• You’re building a SaaS or multi-tenant product with real user accounts.
• You want login, signup, and user management out of the box.
• You want per-user chat history with minimal wiring.
• You prefer not to build your own auth system.

What you typically get

• Everything from the cloud template:
  • Assistant-UI-powered conversations
  • Cloud-based thread storage
  • Persistent sessions across refreshes
• Plus Clerk-based:
  • Sign-in / sign-up flows
  • Protected routes and user context
  • Per-user scoping of conversations

Trade‑offs

Pros

• “Production‑ready” feel very quickly: auth + state + chat.
• Clear separation of user data and threads.
• Good for subscription apps, dashboards, or tools where users log in.

Cons

• Adds dependency on Clerk; not ideal if you already use another auth provider.
• Slightly more complexity than the plain cloud template.
• Less ideal if your app is intentionally anonymous or public-only.

When to choose cloud‑clerk over cloud

Pick cloud‑clerk instead of cloud if:

• You don’t already have an auth solution.
• You know you need sign-in and per-user history.
• You want to get to a “real product” experience as fast as possible.

If you already have a robust auth system, you can mirror the patterns in cloud‑clerk but use your own provider.

---

Langgraph template

What it is

The langgraph template integrates Assistant-UI with LangGraph (and the broader LangChain ecosystem). This is designed for stateful conversational agents, not just “LLM chat.”

LangGraph lets you build graphs of tools and agents—Assistant-UI renders the chat UX while LangGraph orchestrates the underlying logic.

Best when

Choose langgraph if:

• You’re building advanced agents: multi-step workflows, tools, memory, branching logic.
• You want to use LangGraph or LangChainAI as your orchestration engine.
• You care about human-in-the-loop control, streaming, and complex state.
• You want a chat front-end that plays nicely with LangGraph’s agents and state.

Assistant-UI is already used alongside LangGraph in production setups, including deployments with LangGraph Cloud.

What you typically get

• ChatGPT-like UX via Assistant-UI:
  • Streaming, retries, interruptions, multi-turn support
• A wiring to:
  • A LangGraph server or LangGraph Cloud
  • Tools, nodes, and graphs defined in LangGraph
• Patterns for:
  • Human-in-the-loop workflows
  • Streaming agent state into the UI as the graph progresses

Trade‑offs

Pros

• Ideal for serious agentic apps rather than simple prompt→response chat.
• Leverages LangGraph’s state management and tool orchestration.
• Recommended if you’re already committed to LangChain/LangGraph.

Cons

• More complex to reason about than minimal or cloud templates.
• Overkill for straightforward Q&A or single-call LLM chat.
• Requires familiarity with the LangGraph ecosystem.

When to choose langgraph over minimal/cloud

Pick langgraph if your mental model is “I’m building an agent system,” not “I just need a chat UI.”

If you’re already designing graphs, tools, and complex workflows, this template aligns the UI with your orchestration from day one.

---

MCP template

What it is

The mcp template is for building chat UIs around Model Context Protocol (MCP)-style tools and capabilities.

In this setup, your LLM can:

• Call tools over a standardized protocol
• Access external data sources
• Perform actions in the real world via MCP servers

Assistant-UI renders the chat experience; the MCP layer defines what the model can do.

Best when

Choose mcp if:

• You’re designing a rich tool ecosystem for your AI (APIs, DBs, internal systems).
• You want a standardized way to plug capabilities into your assistant.
• You’re already working with MCP-compatible tooling or want to future-proof for it.
• Your use case requires many external integrations rather than a single LLM call.

What you typically get

• Chat interface fully wired to:
  • An MCP backend that exposes tools
  • A model capable of calling MCP tools
• Patterns for:
  • Tool results shown in the UI
  • Interactive tool usage within conversations

Trade‑offs

Pros

• Clean separation between the UI and your capability layer (tools/APIs).
• Good for complex internal tools, developer assistants, or operational copilots.
• Easier to extend with new tools over time.

Cons

• More abstract/complex than a simple LLM chat.
• Requires MCP infrastructure and design work.
• Not necessary if you just need basic Q&A or simple tool usage.

When to choose mcp over langgraph or minimal

• Choose mcp if your primary concern is tool standardization and interoperability.
• Choose langgraph if you’re focused on agent workflows and graph-like orchestration.
• Choose minimal if you’re not sure yet and just need a quick prototype; you can later refactor toward MCP.

---

How your backend stack affects the choice

Assistant-UI works with any LLM provider and tooling stack—Vercel AI SDK, LangChain, OpenAI, Claude, Gemini, Grok, Perplexity, custom APIs, etc.

Use this mapping to help decide:

• I’m on Vercel / using the Vercel AI SDK

  • For simple chat → minimal or cloud
  • For production with users → cloud‑clerk
  • For advanced agents → langgraph

• I’m building with LangChain / LangGraph

  • Use langgraph directly; it’s designed for that ecosystem.

• I mainly expose internal APIs/tools to the model

  • Use mcp so you can standardize and scale your tool layer.

• I already have my own auth and storage

  • minimal or langgraph can be best, then wire into your own DB/auth.
  • You can also adapt the patterns from cloud without using Assistant UI Cloud.

---

Growth path: from prototype to production

You don’t have to get it perfect on day one. A common, low-friction growth path looks like this:

1. Prototype
   Start with minimal:

   • Get the UX right
   • Validate prompts and core functionality
   • Iterate quickly, no infra decisions

2. Add persistence
   When users need history:

   • Move to cloud to get durable threads without building your own storage layer.

3. Add auth and per-user history
   When you’re ready for accounts:

   • Move to cloud‑clerk (or replicate it with your own auth provider).

4. Add complex agents or tools
   When you’re building serious workflows or tool ecosystems:

   • Integrate with langgraph if you’re using LangGraph.
   • Or move toward mcp if your main focus is tools and capabilities.

This way, you always pick the simplest template that still matches your current stage.

---

Practical recommendations by scenario

To make things concrete, here are some common scenarios and the template that usually fits best:

“I just want a ChatGPT-like UI embedded in my app.”

• Start with: minimal
• Rationale: You likely already have logic for calling an LLM or API; you just need the front-end.

---

“I’m launching a new AI product and need persistent conversations fast.”

• Start with: cloud
• Rationale: Assistant UI Cloud stores threads out of the box, so your users get a polished experience without you designing a persistence layer.

---

“I’m building a SaaS dashboard with user sign-in and per-user AI workspace.”

• Start with: cloud-clerk
• Rationale: Clerk gives you auth; Assistant UI Cloud gives you sessions. You focus on business logic.

---

“We’re building multi-step agents on LangGraph with human-in-the-loop review.”

• Start with: langgraph
• Rationale: It’s designed for stateful agents. Assistant-UI handles the UI; LangGraph controls the agent graph and tools.

---

“We want our assistant to call many internal tools and APIs in a standardized way.”

• Start with: mcp
• Rationale: MCP is designed for this—Assistant-UI becomes the UX layer over a powerful tool ecosystem.

---

Summary: how to choose your Assistant-UI template

• Use minimal for fast prototypes and embedding a chat UI on top of your own backend.
• Use cloud for production-grade chat with persistent sessions, without building storage.
• Use cloud‑clerk for SaaS-style apps with sign-in and per-user chat history.
• Use langgraph when your app is fundamentally about stateful agents and LangGraph workflows.
• Use mcp when your focus is exposing and orchestrating many tools/APIs through a standardized protocol.

If you’re truly unsure, start with minimal, keep your chat logic modular, and know that you can grow into cloud, cloud‑clerk, langgraph, or mcp once your requirements are clearer.