⚡ Next.js AI Agentic Full-Stack Template (V2)

The Enterprise-Grade, AI-Native Foundation for Autonomous Web Applications & Agentic SaaS

Quick Start • Product Showcase • MCP Architecture • Feature Catalog • Documentation

---

---

💎 Product Showcase & Sales Pitch

Building modern AI applications requires more than just connecting an LLM to a chat prompt. You need stateful multi-turn agent loops, safe tool execution guardrails, encrypted secret management, enterprise RBAC, live telemetry, and seamless Model Context Protocol (MCP) interoperability with modern IDEs like Cursor, Claude Desktop, and Windsurf.

This template is designed from the ground up as a commercial-grade, turnkey platform:

• 🚀 Zero to Production in Minutes: Full authentication, Prisma PostgreSQL database, dynamic dark/light theme, landing page with Three.js 3D animations, and an administrative control plane pre-wired out of the box.
• 🤖 In-Process Agentic Execution Engine: Execute complex, multi-step agent goals with real-time SSE step streaming, dry-run safety modes, and Human-in-the-Loop (HITL) approval queues.
• 🔌 Turnkey MCP Server (/api/mcp): Connect Cursor, Windsurf, or Claude Desktop directly to your backend database and business logic with token authentication, fine-grained capability permission matrices, and rate limiting.
• 🧠 Vector Knowledge Base & Multi-Format Ingestion: Drag-and-drop file ingestion for Markdown, TXT, JSON, CSV, and code with semantic chunking and recommendations for local Ollama (nomic-embed-text, mxbai-embed-large) and Cloud OpenAI embeddings.
• 🛡️ Vault-Grade Security: AES-256-GCM encrypted secrets at rest with zero-exposure secret redaction across logs, payloads, and APIs.

---

🏛️ System Architecture & Data Flow

flowchart TB
    subgraph Clients["Clients & External AI Agents"]
        Web[Modern Web & Mobile App]
        AdminUI[Admin Dashboard & Copilot Panel]
        CursorIDE[Cursor IDE / Windsurf]
        Claude[Claude Desktop App]
        Webhooks[External Webhook Triggers]
    end

    subgraph Gateway["Ingress & Protocol Layer"]
        NextAuth[NextAuth.js v5 Session Engine]
        MCPRoute["/api/mcp (JSON-RPC 2.0 Server)"]
        StreamRoute["/api/agent/stream (SSE Runner)"]
        ChatRoute["/api/chat & /api/chat/public"]
    end

    subgraph AgentCore["In-Process Agentic Engine"]
        Registry["Central Capability Registry"]
        CoreCaps["Built-in Capabilities (ai, system, chat, diagnostics)"]
        DropInCaps["Drop-In Modules (src/capabilities/*)"]
        HITL["Human-in-the-Loop Approval Queue"]
    end

    subgraph Backends["AI & Database Gateways"]
        Postgres[("PostgreSQL Database (Prisma 7)")]
        OllamaGate["Local Ollama Gateway"]
        OpenAIGate["OpenAI / OpenRouter / vLLM"]
        Embedder["Vector Embeddings (Ollama / OpenAI)"]
        Vault["AES-256-GCM Encryption Vault"]
    end

    Web --> NextAuth & ChatRoute
    AdminUI --> NextAuth & StreamRoute & Registry
    CursorIDE & Claude --> MCPRoute
    Webhooks --> StreamRoute

    MCPRoute --> Registry
    StreamRoute --> Registry
    ChatRoute --> Registry

    Registry --> CoreCaps & DropInCaps & HITL
    CoreCaps --> Postgres & Vault & OllamaGate & OpenAIGate & Embedder

Loading

---

🔌 Model Context Protocol (MCP) Interface

Expose all system capabilities safely to modern AI agents and IDEs with fine-grained access control:

Cursor IDE Configuration (.cursor/mcp.json)

{
  "mcp": {
    "servers": {
      "app-backend": {
        "url": "http://localhost:3000/api/mcp",
        "headers": {
          "Authorization": "Bearer mcp_live_your_token_here"
        }
      }
    }
  }
}

Claude Desktop Configuration (claude_desktop_config.json)

{
  "mcpServers": {
    "app-backend": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3000/api/mcp",
        "--header",
        "Authorization: Bearer mcp_live_your_token_here"
      ]
    }
  }
}

---

🌟 Feature Catalog

🤖 Autonomous Agentic Engine & Control Plane

• Capability Registry (src/lib/agentic/registry.ts): Structured tool definitions with Zod schema validation, RBAC role gating (PUBLIC, USER, ADMIN), and automatic secret scrubbing.
• Drop-In Capability System (src/capabilities/): Add a new tool by dropping a file into src/capabilities/. Automatically exposed to MCP, internal agents, and server actions.
• Agent Runner (/admin/ai/agent): Multi-turn goal-oriented execution environment with live step inspection, token count meters, and dry-run guardrails.
• Human-in-the-Loop Approvals (AgentActionRequest): Intercepts destructive actions for admin review in the header notification popover.
• Autonomous Scheduled Jobs (/admin/ai/schedules): Cron-based agent workflows for diagnostics, maintenance, and self-healing.
• External Webhooks (/api/agent/webhook): HMAC/Bearer-authenticated webhook triggers for Stripe, GitHub, or automated pipeline events.

🧠 Multi-Provider AI & Vector Knowledge Base

• Multi-Provider Support: Seamlessly route traffic to local Ollama or OpenAI-compatible cloud models (OpenRouter, Groq, LM Studio, Hermes).
• Pipeline Channel Routing: Isolated channels for FRONTEND_CHAT, ADMIN_CHAT, ADMIN_AGENT, FORM_ASSISTANT, and EMBEDDING.
• Knowledge Base File Attachment (/admin/ai/knowledge): Drag-and-drop file ingestion for Markdown, TXT, JSON, CSV, and code with token estimation and semantic chunking.
• Embedder Configuration: Built-in recommendations for Ollama (nomic-embed-text, mxbai-embed-large) and OpenAI embeddings.

🛡️ Enterprise Security & Vault

• AES-256-GCM Encryption: Stored credentials (provider keys, SMTP passwords) are encrypted with random 12-byte IVs.
• Zero-Secret Exposure: Secrets are masked in UI views and scrubbed from all API responses, MCP payloads, and log records.
• Session Isolation: Unique cookie prefixing prevents cross-project cookie collisions on localhost.
• First-User Admin Bootstrap: The first user to register at /register is automatically granted ADMIN privileges.

🎨 Design System & UI Architecture

• Tailwind CSS v4 & Radix UI: High-end glassmorphism, responsive drawer navigation, and light/dark theme toggling.
• Landing Page with Three.js: Interactive 3D particle canvas optimized for performance and SEO metadata.
• Slide-Over AI Copilot (Ctrl+J): Global assistant accessible anywhere in the admin dashboard with conversation history recall.

---

🛠 Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router + Turbopack)
Runtime & Styling	React 19, Tailwind CSS 4, Radix UI, Three.js
Database & ORM	PostgreSQL + Prisma 7 (with @prisma/adapter-pg)
Authentication	NextAuth.js v5 (5.0.0-beta.32)
AI Integration	Vercel AI SDK 7 (ai, @ai-sdk/openai, ai-sdk-ollama)
Protocol	Model Context Protocol (MCP) JSON-RPC 2.0 (/api/mcp)
Testing	Vitest 4 (454 unit & integration tests)
Observability	Pino Logger + Database Audit Trails

---

🚀 Quick Start

1. Clone & Install Dependencies

git clone <your-repo-url>
cd templates-base_project
npm install

2. Initialize Environment & Security Keys

Run the initialization script with your project name. This automatically generates a fresh AUTH_SECRET, AUTH_COOKIE_PREFIX, and a 32-byte base64 ENCRYPTION_KEY:

node scripts/init-project.js "enterprise-agent"

3. Database Sync & Seeding

Ensure PostgreSQL is running, then sync the Prisma schema and seed default prompt templates:

npx prisma db push
npm run db:seed

4. Run Test Suite

Verify system integrity and capability contracts:

npm run test:run

5. Launch Development Server

npm run dev

Open http://localhost:3000 in your browser. Register your initial account at /register to become the system administrator.

---

📚 Documentation

For in-depth architectural guides and developer manuals, explore the doc/ directory:

• System Architecture
• Agentic Framework & Capabilities
• Model Context Protocol (MCP)
• Multi-Provider AI & Endpoints
• Knowledge Base & RAG
• Security & Cryptography
• Production Deployment
• Adding New Features

---

📄 License

MIT © 2026. Free for commercial and personal use.