A production-ready Next.js template for building AI agents with LangGraph.js, featuring Model Context Protocol (MCP) integration, human-in-the-loop tool approval, and persistent memory.

Complete agent workflow: user input → tool approval → execution → streaming response

Need help taking this to production?

I help teams design and optimize LangGraph-based AI agents (RAG, memory, latency, architecture).

If you're building something serious on top of this template and want hands-on help:

→ DM me on LinkedIn

Happy to jump on a short call.

Features

Dynamic Tool Loading with MCP

• Model Context Protocol integration for dynamic tool management
• Add tools via web UI - no code changes required
• Support for both stdio and HTTP MCP servers
• Tool name prefixing to prevent conflicts

Human-in-the-Loop Tool Approval

• Interactive tool call approval before execution
• Granular control with approve/deny/modify options
• Optional auto-approval mode for trusted environments
• Real-time streaming with tool execution pauses

Persistent Conversation Memory

• LangGraph checkpointer with PostgreSQL backend
• Full conversation history preservation
• Thread-based organization
• Seamless resume across sessions

Multimodal File Uploads

• Upload images, PDFs, and text files with messages
• S3-compatible storage (MinIO for development)
• Automatic file processing for AI consumption
• Production-ready with AWS S3, Cloudflare R2 support

Real-time Streaming Interface

• Server-Sent Events (SSE) for live responses
• Optimistic UI updates with React Query
• Type-safe message handling
• Error recovery and graceful degradation

Modern Tech Stack

• Frontend: Next.js 15, React 19, TypeScript, Tailwind CSS
• Backend: Node.js, Prisma ORM, PostgreSQL, MinIO/S3
• AI: LangGraph.js, OpenAI/Google models
• UI: shadcn/ui components, Lucide icons

Quick Start

Prerequisites

• Node.js 18+ and pnpm
• Docker (for PostgreSQL and MinIO)
• OpenAI API key or Google AI API key

1. Clone and Install

git clone https://github.com/IBJunior/fullstack-langgraph-nextjs-agent.git
cd fullstack-langgraph-nextjs-agent
pnpm install

2. Environment Setup

cp .env.example .env.local

Edit .env.local with your configuration:

# Database
DATABASE_URL="postgresql://user:password@localhost:5434/agent_db"

# AI Models (choose one or both)
OPENAI_API_KEY="sk-..."
GOOGLE_API_KEY="..."

# Optional: Default model
DEFAULT_MODEL="gpt-4o-mini"  # or "gemini-1.5-flash"

3. Start Services

docker compose up -d  # Starts PostgreSQL and MinIO

4. Database Setup

pnpm prisma:generate
pnpm prisma:migrate

5. Run Development Server

Visit http://localhost:3000 to start chatting with your AI agent!

Screenshots

Usage Guide

Adding MCP Servers

1. Navigate to Settings - Click the gear icon in the sidebar
2. Add MCP Server - Click "Add MCP Server" button
3. Configure Server:
   • Name: Unique identifier (e.g., "filesystem")
   • Type: Choose stdio or http
   • Command: For stdio servers (e.g., npx @modelcontextprotocol/server-filesystem)
   • Args: Command arguments (e.g., ["/path/to/allow"])
   • URL: For HTTP servers

MCP server configuration form with example filesystem server setup

Want to build your own MCP server? Check out create-mcp-server - scaffold production-ready MCP servers in seconds with TypeScript, multiple frameworks (MCP SDK or FastMCP), and built-in debugging tools.

Example MCP Server Configurations

Filesystem Server (stdio)

{
  "name": "filesystem",
  "type": "stdio",
  "command": "npx",
  "args": ["@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
}

HTTP API Server

{
  "name": "web-api",
  "type": "http",
  "url": "http://localhost:8080/mcp",
  "headers": {
    "Authorization": "Bearer your-token"
  }
}

Note: Some HTTP MCP servers require OAuth 2.0 authentication. See OAuth Documentation for details.

Tool Approval Workflow

1. Agent Requests Tool - AI suggests using a tool
2. Approval Prompt - Interface shows tool details and asks for approval
3. User Decision:
   • ✅ Allow: Execute tool as requested
   • ❌ Deny: Skip tool execution
   • ✏️ Modify: Edit tool parameters before execution
4. Continue Conversation - Agent responds with tool results

Architecture

High-Level Overview

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Next.js UI   │◄──►│  Agent Service   │◄──►│  LangGraph.js   │
│   (React 19)   │    │  (SSE Streaming) │    │    Agent        │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   React Query   │    │     Prisma       │    │  MCP Clients    │
│   (State Mgmt)  │    │   (Database)     │    │   (Tools)       │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                  ┌──────────────────────────────┐
                  │   PostgreSQL  │  MinIO/S3    │
                  │  (Persistence)│ (File Store) │
                  └──────────────────────────────┘

Core Components

Agent Builder (src/lib/agent/builder.ts)

• Creates StateGraph with agent→tool_approval→tools flow
• Handles tool approval interrupts
• Manages model binding and system prompts

MCP Integration (src/lib/agent/mcp.ts)

• Dynamic tool loading from database-stored MCP servers
• Support for stdio and HTTP transports
• Tool name prefixing for conflict prevention

Streaming Service (src/services/agentService.ts)

• Server-Sent Events for real-time responses
• Message processing and chunk aggregation
• Tool approval workflow handling

Chat Hook (src/hooks/useChatThread.ts)

• React Query integration for optimistic UI
• Stream management and error handling
• Tool approval user interface

File Storage (src/lib/storage/)

• S3-compatible storage with MinIO (development) or AWS S3 (production)
• File validation, upload, and content processing for AI
• Multimodal message building with base64 conversion

For detailed architecture documentation, see docs/ARCHITECTURE.md.

Development

Available Scripts

pnpm dev                 # Start development server with Turbopack
pnpm build              # Production build
pnpm start              # Start production server
pnpm lint               # Run ESLint
pnpm format             # Format with Prettier
pnpm format:check       # Check formatting

# Database
pnpm prisma:generate    # Generate Prisma client (after schema changes)
pnpm prisma:migrate     # Create and apply migrations
pnpm prisma:studio      # Open Prisma Studio (database UI)

Project Structure

src/
├── app/                 # Next.js App Router
│   ├── api/            # API routes (stream, upload, mcp-servers)
│   └── thread/         # Thread-specific pages
├── components/         # React components
├── hooks/              # Custom React hooks
├── lib/                # Core utilities
│   ├── agent/          # Agent-related logic
│   └── storage/        # File upload & S3 utilities
├── services/           # Business logic
└── types/              # TypeScript definitions

prisma/
├── schema.prisma       # Database schema
└── migrations/         # Database migrations

Key Files

• Agent Configuration: src/lib/agent/builder.ts, src/lib/agent/mcp.ts
• API Endpoints: src/app/api/agent/stream/route.ts, src/app/api/agent/upload/route.ts
• File Storage: src/lib/storage/ (validation, upload, content processing)
• Database Models: prisma/schema.prisma
• Main Chat Interface: src/components/Thread.tsx, src/components/MessageInput.tsx
• Streaming Logic: src/hooks/useChatThread.ts

Contributing

We welcome contributions! This project is designed to be a community resource for LangGraph.js development.

Getting Started

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Commit: git commit -m 'Add amazing feature'
5. Push: git push origin feature/amazing-feature
6. Open a Pull Request

Development Guidelines

• Follow TypeScript strict mode
• Use Prettier for formatting
• Add JSDoc comments for public APIs
• Test MCP server integrations thoroughly
• Update documentation for new features

Learning Resources

LangGraph.js

• LangGraph.js Documentation
• StateGraph API Reference
• Checkpointer Guide

Model Context Protocol (MCP)

• MCP Specification
• MCP Servers Repository
• Building MCP Servers
• Docker MCP Catalog

Next.js & React

• Next.js 15 Documentation
• React 19 Release Notes
• React Query (TanStack Query)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• LangChain for the incredible AI framework
• Model Context Protocol for the tool integration standard
• Next.js team for the amazing React framework

Ready to build your next AI agent?

Get Started

If this repo helped you and you’d like guidance implementing it in production, feel free to reach out on LinkedIn.