Skip to content
Back to search

fullstack-langgraph-nextjs-agent

Production-ready Next.js template for building AI agents with LangGraph.js. Features MCP integration for dynamic tool loading, human-in-the-loop tool approval, persistent conversation memory with PostgreSQL, and real-time streaming responses. Built with TypeScript, React, Prisma, and Tailwind CSS.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/agentailor--fullstack-langgraph-nextjs-agent/badge.svg)](/listings/agentailor--fullstack-langgraph-nextjs-agent)

HTML

<a href="/listings/agentailor--fullstack-langgraph-nextjs-agent"><img src="/api/listings/agentailor--fullstack-langgraph-nextjs-agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Node.js 18+ and pnpm - Docker (for PostgreSQL and MinIO) - OpenAI API key, Google AI API key, or Anthropic 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 more)
OPENAI_API_KEY="sk-..."
GOOGLE_API_KEY="..."
ANTHROPIC_API_KEY="sk-ant-..."

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

3. Start Services

docker compose up -d  # Starts PostgreSQL and MinIO

4. Database Setup

pnpm prisma:generate
pnpm prisma:migrate

5. Run Development Server

pnpm dev
# Or use custom port
pnpm dev --port=3005

Visit [http://localhost:3000](http://localhost:3000) to start chatting with your AI agent!

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 434 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # LangGraph.js AI Agent Template
  2. > **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.**
  3. ![Demo](docs/images/hero-demo.gif)
  4. _Complete agent workflow: user input → tool approval → execution → streaming response_
  5. [![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue?logo=typescript)](https://www.typescriptlang.org/)
  6. [![Next.js](https://img.shields.io/badge/Next.js-16.2-black?logo=next.js)](https://nextjs.org/)
  7. [![LangGraph](https://img.shields.io/badge/LangGraph.js-1.2-green?logo=langchain)](https://langchain-ai.github.io/langgraphjs/)
  8. [![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16+-blue?logo=postgresql)](https://www.postgresql.org/)
  9. [![Prisma](https://img.shields.io/badge/Prisma-6.16-2D3748?logo=prisma)](https://www.prisma.io/)
  10. ---
  11. ## Built with this template: Cameron
  12. [**Cameron**](https://github.com/agentailor/cameron) is a personal finance agent that started from this
  13. template and was built in public, one tagged release per article. If you want to see where this scaffold
  14. goes once it becomes a real agent — human-in-the-loop approval on every money-moving action, self-hosted
  15. data, a full LangGraph workflow — read its source as a worked example.
  16. ---
  17. ## Need help taking this to production?
  18. I help teams design and optimize LangGraph-based AI agents (RAG, memory, latency, architecture).
  19. If you're building something serious on top of this template and want hands-on help:
  20. → [DM me on LinkedIn](https://www.linkedin.com/in/ali-ibrahim-junior/)
  21. Happy to jump on a short call.
  22. ---
  23. ## Features
  24. ### **Dynamic Tool Loading with MCP**
  25. - **Model Context Protocol** integration for dynamic tool management
  26. - Add tools via web UI - no code changes required
  27. - Support for both stdio and HTTP MCP servers
  28. - Tool name prefixing to prevent conflicts
  29. ### **Human-in-the-Loop Tool Approval**
  30. - Interactive tool call approval before execution
  31. - Granular control with approve/deny/modify options
  32. - Optional auto-approval mode for trusted environments
  33. - Real-time streaming with tool execution pauses
  34. <div align="center">
  35. <img src="docs/images/tool-approval.png" alt="Tool Approval Dialog" width="600" />
  36. <p><em>Tool approval dialog with detailed parameter inspection</em></p>
  37. </div>
  38. ### **Persistent Conversation Memory**
  39. - LangGraph checkpointer with PostgreSQL backend
  40. - Full conversation history preservation
  41. - Thread-based organization
  42. - Seamless resume across sessions
  43. ### **Multimodal File Uploads**
  44. <div align="center">
  45. <img src="docs/images/file-upload.gif" alt="File upload" width="600" />
  46. <p><em>Tool approval dialog with detailed parameter inspection</em></p>
  47. </div>
  48. - Upload images, PDFs, and text files with messages
  49. - S3-compatible storage (MinIO for development)
  50. - Automatic file processing for AI consumption
  51. - Production-ready with AWS S3, Cloudflare R2 support
  52. ### **Real-time Streaming Interface**
  53. - Server-Sent Events (SSE) for live responses
  54. - Optimistic UI updates with React Query
  55. - Type-safe message handling
  56. - Error recovery and graceful degradation
  57. ### **Persistent Model Settings**
  58. - Provider and model selection saved to `localStorage` automatically
  59. - Settings survive page reloads and thread navigation
  60. - No backend required — zero latency reads on startup
  61. ### **LLM Observability with Langfuse**
  62. - End-to-end tracing of agent runs, LLM calls, tool invocations, and token usage
  63. - Works with [Langfuse Cloud](https://cloud.langfuse.com) or a self-hosted instance
  64. - Toggle via `LANGFUSE_ENABLED` env var — zero overhead when disabled
  65. - See [docs/OBSERVABILITY.md](docs/OBSERVABILITY.md) for setup instructions
  66. ### **Modern Tech Stack**
  67. - **Frontend**: Next.js 15, React 19, TypeScript, Tailwind CSS
  68. - **Backend**: Node.js, Prisma ORM, PostgreSQL, MinIO/S3
  69. - **AI**: LangGraph.js, OpenAI/Google/Anthropic models
  70. - **UI**: shadcn/ui components, Lucide icons
  71. ## Quick Start
  72. ### Prerequisites
  73. - Node.js 18+ and pnpm
  74. - Docker (for PostgreSQL and MinIO)
  75. - OpenAI API key, Google AI API key, or Anthropic API key
  76. ### 1. Clone and Install
  77. ```bash
  78. git clone https://github.com/IBJunior/fullstack-langgraph-nextjs-agent.git
  79. cd fullstack-langgraph-nextjs-agent
  80. pnpm install
  81. ```
  82. ### 2. Environment Setup
  83. ```bash
  84. cp .env.example .env.local
  85. ```
  86. Edit `.env.local` with your configuration:
  87. ```env
  88. # Database
  89. DATABASE_URL="postgresql://user:password@localhost:5434/agent_db"
  90. # AI Models (choose one or more)
  91. OPENAI_API_KEY="sk-..."
  92. GOOGLE_API_KEY="..."
  93. ANTHROPIC_API_KEY="sk-ant-..."
  94. # Optional: Default model
  95. DEFAULT_MODEL="gpt-4o-mini" # or "gemini-1.5-flash" or "claude-sonnet-4-5"
  96. ```
  97. ### 3. Start Services
  98. ```bash
  99. docker compose up -d # Starts PostgreSQL and MinIO
  100. ```
  101. ### 4. Database Setup
  102. ```bash
  103. pnpm prisma:generate
  104. pnpm prisma:migrate
  105. ```
  106. ### 5. Run Development Server
  107. ```bash
  108. pnpm dev
  109. # Or use custom port
  110. pnpm dev --port=3005
  111. ```
  112. Visit [http://localhost:3000](http://localhost:3000) to start chatting with your AI agent!
  113. ## Screenshots
  114. <table>
  115. <tr>
  116. <td align="center">
  117. <img src="docs/images/chat-interface.png" alt="Chat Interface" width="400" />
  118. <br /><strong>Main Chat Interface</strong>
  119. <br />Clean, responsive design with streaming responses
  120. </td>
  121. <td align="center">
  122. <img src="docs/images/mcp-configuration.png" alt="MCP Configuration" width="400" />
  123. <br /><strong>MCP Server Management</strong>
  124. <br />Easy setup and configuration of tool servers
  125. </td>
  126. </tr>
  127. <tr>
  128. <td align="center">
  129. <img src="docs/images/thread-sidebar.png" alt="Thread Management" width="400" />
  130. <br /><strong>Thread Management</strong>
  131. <br />Organize conversations with persistent history
  132. </td>
  133. <td align="center">
  134. <img src="docs/images/agent-configuration.png" alt="Streaming Response" width="400" />
  135. <br /><strong>Agent Configurations</strong>
  136. <br /> Multiple model Providers Support
  137. </td>
  138. </tr>
  139. </table>
  140. ## Usage Guide
  141. ### Adding MCP Servers
  142. 1. **Navigate to Settings** - Click the gear icon in the sidebar
  143. 2. **Add MCP Server** - Click "Add MCP Server" button
  144. 3. **Configure Server**:
  145. - **Name**: Unique identifier (e.g., "filesystem")
  146. - **Type**: Choose `stdio` or `http`
  147. - **Command**: For stdio servers (e.g., `npx @modelcontextprotocol/server-filesystem`)
  148. - **Args**: Command arguments (e.g., `["/path/to/allow"]`)
  149. - **URL**: For HTTP servers
  150. ![Add MCP Server](docs/images/add-mcp-server.png)
  151. _MCP server configuration form with example filesystem server setup_
  152. > **Want to build your own MCP server?** Check out [create-mcp-server](https://github.com/agentailor/create-mcp-server) - scaffold production-ready MCP servers in seconds with TypeScript, multiple frameworks (MCP SDK or FastMCP), and built-in debugging tools.
  153. ### Example MCP Server Configurations
  154. #### Filesystem Server (stdio)
  155. ```json
  156. {
  157. "name": "filesystem",
  158. "type": "stdio",
  159. "command": "npx",
  160. "args": ["@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
  161. }
  162. ```
  163. #### HTTP API Server
  164. ```json
  165. {
  166. "name": "web-api",
  167. "type": "http",
  168. "url": "http://localhost:8080/mcp",
  169. "headers": {
  170. "Authorization": "Bearer your-token"
  171. }
  172. }
  173. ```
  174. > **Note**: Some HTTP MCP servers require OAuth 2.0 authentication. See [OAuth Documentation](docs/OAUTH.md) for details.
  175. ### Tool Approval Workflow
  176. 1. **Agent Requests Tool** - AI suggests using a tool
  177. 2. **Approval Prompt** - Interface shows tool details and asks for approval
  178. 3. **User Decision**:
  179. - ✅ **Allow**: Execute tool as requested
  180. - ❌ **Deny**: Skip tool execution
  181. - ✏️ **Modify**: Edit tool parameters before execution
  182. 4. **Continue Conversation** - Agent responds with tool results
  183. ## Architecture
  184. ### High-Level Overview
  185. ```
  186. ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
  187. │ Next.js UI │◄──►│ Agent Service │◄──►│ LangGraph.js │
  188. │ (React 19) │ │ (SSE Streaming) │ │ Agent │
  189. └─────────────────┘ └──────────────────┘ └─────────────────┘
  190. │ │ │
  191. ▼ ▼ ▼
  192. ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
  193. │ React Query │ │ Prisma │ │ MCP Clients │
  194. │ (State Mgmt) │ │ (Database) │ │ (Tools) │
  195. └─────────────────┘ └──────────────────┘ └─────────────────┘
  196. │
  197. ▼
  198. ┌──────────────────────────────┐
  199. │ PostgreSQL │ MinIO/S3 │
  200. │ (Persistence)│ (File Store) │
  201. └──────────────────────────────┘
  202. ```
  203. ### Core Components
  204. #### Agent Builder (`src/lib/agent/builder.ts`)
  205. - Creates StateGraph with agent→tool_approval→tools flow
  206. - Handles tool approval interrupts
  207. - Manages model binding and system prompts
  208. #### MCP Integration (`src/lib/agent/mcp.ts`)
  209. - Dynamic tool loading from database-stored MCP servers
  210. - Support for stdio and HTTP transports
  211. - Tool name prefixing for conflict prevention
  212. #### Streaming Service (`src/services/agentService.ts`)
  213. - Server-Sent Events for real-time responses
  214. - Message processing and chunk aggregation
  215. - Tool approval workflow handling
  216. #### Chat Hook (`src/hooks/useChatThread.ts`)
  217. - React Query integration for optimistic UI
  218. - Stream management and error handling
  219. - Tool approval user interface
  220. #### File Storage (`src/lib/storage/`)
  221. - S3-compatible storage with MinIO (development) or AWS S3 (production)
  222. - File validation, upload, and content processing for AI
  223. - Multimodal message building with base64 conversion
  224. For detailed architecture documentation, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
  225. ## API Documentation
  226. The app serves an interactive OpenAPI 3.1 explorer at **`/api-docs`** and the raw spec at
  227. **`/api/openapi`** — generated from per-route Zod schemas. See [docs/API.md](docs/API.md) for how
  228. it works and how to document new routes.
  229. ## Development
  230. ### Available Scripts
  231. ```bash
  232. pnpm dev # Start development server with Turbopack
  233. pnpm build # Production build
  234. pnpm start # Start production server
  235. pnpm lint # Run ESLint
  236. pnpm format # Format with Prettier
  237. pnpm format:check # Check formatting
  238. # Database
  239. pnpm prisma:generate # Generate Prisma client (after schema changes)
  240. pnpm prisma:migrate # Create and apply migrations
  241. pnpm prisma:studio # Open Prisma Studio (database UI)
  242. ```
  243. ### Agent Skills
  244. This repo ships [Agent Skills](https://github.com/agentailor/skills) in [.agents/skills/](.agents/skills/),
  245. pinned by `skills-lock.json`. They give any skill-aware coding agent (Claude Code and friends) the
  246. conventions for working on an agent codebase like this one:
  247. | Skill | Use it when |
  248. | ------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
  249. | [`agent-prompt-engineering`](.agents/skills/agent-prompt-engineering/SKILL.md) | Writing or auditing the agent’s system prompt |
  250. | [`tool-design`](.agents/skills/tool-design/SKILL.md) | Adding or reviewing a tool / MCP server the agent calls |
  251. | [`agent-eval-cases`](.agents/skills/agent-eval-cases/SKILL.md) | Deciding what agent behavior deserves an eval case, and writing it |
  252. Agent guidance for this repo lives in [AGENTS.md](AGENTS.md) (with [CLAUDE.md](CLAUDE.md) pointing to it).
  253. ### Project Structure
  254. ```
  255. src/
  256. ├── app/ # Next.js App Router
  257. │ ├── api/ # API routes (stream, upload, mcp-servers)
  258. │ └── thread/ # Thread-specific pages
  259. ├── components/ # React components
  260. ├── hooks/ # Custom React hooks
  261. ├── lib/ # Core utilities
  262. │ ├── agent/ # Agent-related logic
  263. │ └── storage/ # File upload & S3 utilities
  264. ├── services/ # Business logic
  265. └── types/ # TypeScript definitions
  266. prisma/
  267. ├── schema.prisma # Database schema
  268. └── migrations/ # Database migrations
  269. ```
  270. ### Key Files
  271. - **Agent Configuration**: `src/lib/agent/builder.ts`, `src/lib/agent/mcp.ts`
  272. - **API Endpoints**: `src/app/api/agent/stream/route.ts`, `src/app/api/agent/upload/route.ts`
  273. - **File Storage**: `src/lib/storage/` (validation, upload, content processing)
  274. - **Database Models**: `prisma/schema.prisma`
  275. - **Main Chat Interface**: `src/components/Thread.tsx`, `src/components/MessageInput.tsx`
  276. - **Streaming Logic**: `src/hooks/useChatThread.ts`
  277. ## Contributing
  278. We welcome contributions! This project is designed to be a community resource for LangGraph.js development.
  279. ### Getting Started
  280. 1. Fork the repository
  281. 2. Create a feature branch: `git checkout -b feature/amazing-feature`
  282. 3. Make your changes and add tests
  283. 4. Commit: `git commit -m 'Add amazing feature'`
  284. 5. Push: `git push origin feature/amazing-feature`
  285. 6. Open a Pull Request
  286. ### Development Guidelines
  287. - Follow TypeScript strict mode
  288. - Use Prettier for formatting
  289. - Add JSDoc comments for public APIs
  290. - Test MCP server integrations thoroughly
  291. - Update documentation for new features
  292. ## Learning Resources
  293. ### LangGraph.js
  294. - [LangGraph.js Documentation](https://langchain-ai.github.io/langgraphjs/)
  295. - [StateGraph API Reference](https://langchain-ai.github.io/langgraphjs/reference/modules/langgraph.html)
  296. - [Checkpointer Guide](https://langchain-ai.github.io/langgraphjs/how-tos/persistence-postgres)
  297. ### Model Context Protocol (MCP)
  298. - [MCP Specification](https://spec.modelcontextprotocol.io/)
  299. - [MCP Servers Repository](https://github.com/modelcontextprotocol/servers)
  300. - [Building MCP Servers](https://modelcontextprotocol.io/docs/building-servers)
  301. - [Docker MCP Catalog](https://blog.agentailor.com/posts/docker-mcp-catalog-and-toolkit?utm_source=github_fullstack_repo)
  302. ### Next.js & React
  303. - [Next.js 15 Documentation](https://nextjs.org/docs)
  304. - [React 19 Release Notes](https://react.dev/blog/2024/12/05/react-19)
  305. - [React Query (TanStack Query)](https://tanstack.com/query/latest)
  306. ## License
  307. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  308. ## Acknowledgments
  309. - [LangChain](https://github.com/langchain-ai) for the incredible AI framework
  310. - [Model Context Protocol](https://modelcontextprotocol.io/) for the tool integration standard
  311. - [Next.js](https://nextjs.org/) team for the amazing React framework
  312. ---
  313. **Ready to build your next AI agent?**
  314. [Get Started](#quick-start)
  315. ---
  316. If this repo helped you and you’d like guidance implementing it in production, feel free to reach out on [LinkedIn](https://www.linkedin.com/in/ali-ibrahim-junior/).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.