LangGraph.js AI Agent Template

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

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

Tool approval dialog with detailed parameter inspection

Persistent Conversation Memory

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

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
• AI: LangGraph.js, OpenAI/Google models
• UI: shadcn/ui components, Lucide icons

Quick Start

Prerequisites

• Node.js 18+ and pnpm
• Docker (for PostgreSQL)
• 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 Database

docker compose up -d

4. Database Setup

pnpm prisma:generate
pnpm prisma:migrate

5. Run Development Server

pnpm dev

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

Screenshots

Main Chat Interface Clean, responsive design with streaming responses	MCP Server Management Easy setup and configuration of tool servers
Thread Management Organize conversations with persistent history	Agent Configurations Multiple model Providers Support

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

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"
  }
}

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     │
                       │  (Persistence)   │
                       └──────────────────┘

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

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
│   └── thread/         # Thread-specific pages
├── components/         # React components
├── hooks/              # Custom React hooks
├── lib/                # Core utilities
│   └── agent/          # Agent-related logic
├── 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
• Database Models: prisma/schema.prisma
• Main Chat Interface: src/components/Thread.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