# 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.

- **Type:** MCP server
- **Install:** `agentstack add mcp-agentailor-fullstack-langgraph-nextjs-agent`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [agentailor](https://agentstack.voostack.com/s/agentailor)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [agentailor](https://github.com/agentailor)
- **Source:** https://github.com/agentailor/fullstack-langgraph-nextjs-agent

## Install

```sh
agentstack add mcp-agentailor-fullstack-langgraph-nextjs-agent
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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/)

---

## 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

  
  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

### **Multimodal File Uploads**

  
  Tool approval dialog with detailed parameter inspection

- 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

  
    
      
      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_

> **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)
```

### 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/).

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [agentailor](https://github.com/agentailor)
- **Source:** [agentailor/fullstack-langgraph-nextjs-agent](https://github.com/agentailor/fullstack-langgraph-nextjs-agent)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-agentailor-fullstack-langgraph-nextjs-agent
- Seller: https://agentstack.voostack.com/s/agentailor
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.