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.
Badge for your README
Markdown
[](/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
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)
- # 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_
- [](https://www.typescriptlang.org/)
- [](https://nextjs.org/)
- [](https://langchain-ai.github.io/langgraphjs/)
- [](https://www.postgresql.org/)
- [](https://www.prisma.io/)
- ---
- ## Built with this template: Cameron
- [**Cameron**](https://github.com/agentailor/cameron) is a personal finance agent that started from this
- template and was built in public, one tagged release per article. If you want to see where this scaffold
- goes once it becomes a real agent — human-in-the-loop approval on every money-moving action, self-hosted
- data, a full LangGraph workflow — read its source as a worked example.
- ---
- ## 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](https://www.linkedin.com/in/ali-ibrahim-junior/)
- 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
- <div align="center">
- <img src="docs/images/tool-approval.png" alt="Tool Approval Dialog" width="600" />
- <p><em>Tool approval dialog with detailed parameter inspection</em></p>
- </div>
- ### **Persistent Conversation Memory**
- - LangGraph checkpointer with PostgreSQL backend
- - Full conversation history preservation
- - Thread-based organization
- - Seamless resume across sessions
- ### **Multimodal File Uploads**
- <div align="center">
- <img src="docs/images/file-upload.gif" alt="File upload" width="600" />
- <p><em>Tool approval dialog with detailed parameter inspection</em></p>
- </div>
- - 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
- ### **Persistent Model Settings**
- - Provider and model selection saved to `localStorage` automatically
- - Settings survive page reloads and thread navigation
- - No backend required — zero latency reads on startup
- ### **LLM Observability with Langfuse**
- - End-to-end tracing of agent runs, LLM calls, tool invocations, and token usage
- - Works with [Langfuse Cloud](https://cloud.langfuse.com) or a self-hosted instance
- - Toggle via `LANGFUSE_ENABLED` env var — zero overhead when disabled
- - See [docs/OBSERVABILITY.md](docs/OBSERVABILITY.md) for setup instructions
- ### **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/Anthropic models
- - **UI**: shadcn/ui components, Lucide icons
- ## Quick Start
- ### 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
- ```bash
- git clone https://github.com/IBJunior/fullstack-langgraph-nextjs-agent.git
- cd fullstack-langgraph-nextjs-agent
- pnpm install
- ```
- ### 2. Environment Setup
- ```bash
- cp .env.example .env.local
- ```
- Edit `.env.local` with your configuration:
- ```env
- # 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
- ```bash
- docker compose up -d # Starts PostgreSQL and MinIO
- ```
- ### 4. Database Setup
- ```bash
- pnpm prisma:generate
- pnpm prisma:migrate
- ```
- ### 5. Run Development Server
- ```bash
- pnpm dev
- # Or use custom port
- pnpm dev --port=3005
- ```
- Visit [http://localhost:3000](http://localhost:3000) to start chatting with your AI agent!
- ## Screenshots
- <table>
- <tr>
- <td align="center">
- <img src="docs/images/chat-interface.png" alt="Chat Interface" width="400" />
- <br /><strong>Main Chat Interface</strong>
- <br />Clean, responsive design with streaming responses
- </td>
- <td align="center">
- <img src="docs/images/mcp-configuration.png" alt="MCP Configuration" width="400" />
- <br /><strong>MCP Server Management</strong>
- <br />Easy setup and configuration of tool servers
- </td>
- </tr>
- <tr>
- <td align="center">
- <img src="docs/images/thread-sidebar.png" alt="Thread Management" width="400" />
- <br /><strong>Thread Management</strong>
- <br />Organize conversations with persistent history
- </td>
- <td align="center">
- <img src="docs/images/agent-configuration.png" alt="Streaming Response" width="400" />
- <br /><strong>Agent Configurations</strong>
- <br /> Multiple model Providers Support
- </td>
- </tr>
- </table>
- ## 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](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.
- ### Example MCP Server Configurations
- #### Filesystem Server (stdio)
- ```json
- {
- "name": "filesystem",
- "type": "stdio",
- "command": "npx",
- "args": ["@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
- }
- ```
- #### HTTP API Server
- ```json
- {
- "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](docs/OAUTH.md) 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](docs/ARCHITECTURE.md).
- ## API Documentation
- The app serves an interactive OpenAPI 3.1 explorer at **`/api-docs`** and the raw spec at
- **`/api/openapi`** — generated from per-route Zod schemas. See [docs/API.md](docs/API.md) for how
- it works and how to document new routes.
- ## Development
- ### Available Scripts
- ```bash
- 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)
- ```
- ### Agent Skills
- This repo ships [Agent Skills](https://github.com/agentailor/skills) in [.agents/skills/](.agents/skills/),
- pinned by `skills-lock.json`. They give any skill-aware coding agent (Claude Code and friends) the
- conventions for working on an agent codebase like this one:
- | Skill | Use it when |
- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
- | [`agent-prompt-engineering`](.agents/skills/agent-prompt-engineering/SKILL.md) | Writing or auditing the agent’s system prompt |
- | [`tool-design`](.agents/skills/tool-design/SKILL.md) | Adding or reviewing a tool / MCP server the agent calls |
- | [`agent-eval-cases`](.agents/skills/agent-eval-cases/SKILL.md) | Deciding what agent behavior deserves an eval case, and writing it |
- Agent guidance for this repo lives in [AGENTS.md](AGENTS.md) (with [CLAUDE.md](CLAUDE.md) pointing to it).
- ### 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](https://langchain-ai.github.io/langgraphjs/)
- - [StateGraph API Reference](https://langchain-ai.github.io/langgraphjs/reference/modules/langgraph.html)
- - [Checkpointer Guide](https://langchain-ai.github.io/langgraphjs/how-tos/persistence-postgres)
- ### Model Context Protocol (MCP)
- - [MCP Specification](https://spec.modelcontextprotocol.io/)
- - [MCP Servers Repository](https://github.com/modelcontextprotocol/servers)
- - [Building MCP Servers](https://modelcontextprotocol.io/docs/building-servers)
- - [Docker MCP Catalog](https://blog.agentailor.com/posts/docker-mcp-catalog-and-toolkit?utm_source=github_fullstack_repo)
- ### Next.js & React
- - [Next.js 15 Documentation](https://nextjs.org/docs)
- - [React 19 Release Notes](https://react.dev/blog/2024/12/05/react-19)
- - [React Query (TanStack Query)](https://tanstack.com/query/latest)
- ## License
- This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
- ## Acknowledgments
- - [LangChain](https://github.com/langchain-ai) for the incredible AI framework
- - [Model Context Protocol](https://modelcontextprotocol.io/) for the tool integration standard
- - [Next.js](https://nextjs.org/) team for the amazing React framework
- ---
- **Ready to build your next AI agent?**
- [Get Started](#quick-start)
- ---
- 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 inFree to use. If it’s helped, pass it on.