Installation

Detailed installation guide for all environments

System Requirements

Minimum

• Python 3.10+
• 2 CPU cores
• 4GB RAM
• 10GB disk space

Recommended

• Python 3.11+
• 4 CPU cores
• 8GB RAM
• 20GB disk space

Installation Methods

Choose the installation method that best fits your use case:

Local Development

Best for: Development, testing, learning

Step-by-Step Installation

1. Install Python

   Ensure Python 3.11 or higher is installed:

   python --version  # Should show 3.11+
   

   If not installed:

   • macOS: brew install python@3.11
   • Ubuntu: sudo apt install python3.11
   • Windows: Download from python.org
2. Install Docker

   Required for OpenFGA, Jaeger, and other infrastructure:

   • macOS: Docker Desktop
   • Ubuntu: Docker Engine
   • Windows: Docker Desktop

   Verify installation:

   docker --version
   docker compose version
   
3. Clone Repository

   git clone https://github.com/vishnu2kmohan/mcp-server-langgraph.git
   cd mcp_server_langgraph
   
4. Install uv Package Manager

   Install uv (recommended for fast dependency management):

   # macOS/Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Windows
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   
   # Verify installation
   uv --version
   

   uv is 10-100x faster than pip and handles virtual environments automatically!

5. Install Dependencies

   No manual venv creation needed! uv sync automatically:

   • Creates .venv if it doesn’t exist
   • Installs all dependencies from pyproject.toml
   • Uses uv.lock for reproducible builds

   # uv sync creates .venv automatically and installs ALL dependencies (recommended)
   uv sync
   
   # Install production dependencies only
   uv sync --frozen --no-dev
   
   # Install with optional extras
   uv sync --extra secrets      # With Infisical support
   uv sync --extra embeddings   # With self-hosted embeddings
   uv sync --all-extras         # All optional features
   

   Or use the Makefile:

   make install     # Production only (from lockfile)
   make install-dev # Development with all tools
   

   requirements.txt files are deprecated.* All dependencies are managed via pyproject.toml and locked in uv.lock for reproducible builds.

Docker

Best for: Isolated environments, CI/CD, quick testing

Using Docker

1. Build Image

   docker build -t mcp-server-langgraph:latest .
   
2. Create Environment File

   cp .env.example .env
   # Edit .env with your configuration
   
3. Run with Docker Compose

   # Start all services
   docker compose up -d
   
   # View logs
   docker compose logs -f mcp-server-langgraph
   
   # Stop services
   docker compose down
   

Docker Compose Services

services:
  mcp-server-langgraph:  # Main application
    ports:
      - "8000:8000"

  openfga:          # Authorization
    ports:
      - "8080:8080"

  postgres:         # OpenFGA database
    ports:
      - "5432:5432"

  jaeger:           # Tracing
    ports:
      - "16686:16686"

  prometheus:       # Metrics
    ports:
      - "9090:9090"

  grafana:          # Visualization
    ports:
      - "3000:3000"

Kubernetes

Best for: Production deployments, high availability

See the Kubernetes Deployment Guide for detailed instructions.

Quick Deploy

# Using kubectl
kubectl apply -k deployments/kubernetes/base/

# Using Helm
helm install mcp-server-langgraph ./deployments/helm/mcp-server-langgraph

uv Install

Best for: Using as a library

The package is not yet published to PyPI. Install from source for now.

# Install from GitHub (future)
uv pip install git+https://github.com/vishnu2kmohan/mcp-server-langgraph.git

# Or install locally
uv sync

Post-Installation Setup

1. Start Infrastructure Services

docker compose up -d

Verify services are running:

docker compose ps

All services should show “Up” status.

2. Setup OpenFGA

Initialize the authorization system:

python scripts/setup/setup_openfga.py

Save the output values:

• OPENFGA_STORE_ID
• OPENFGA_MODEL_ID

3. Configure Environment

Create .env from the example:

cp .env.example .env

Edit .env with your values:

Google Gemini

LLM_PROVIDER=google
MODEL_NAME=gemini-2.5-flash-002
GOOGLE_API_KEY=your-api-key-here

4. Add OpenFGA IDs

Add to .env:

OPENFGA_STORE_ID=01HXXXXXXXXXXXXXXXXXX
OPENFGA_MODEL_ID=01HYYYYYYYYYYYYYYYY
JWT_SECRET_KEY=your-secret-key-change-in-production

5. Test Installation

# Preferred: Use uv run
uv run python examples/client_stdio.py

# Alternative: Activate venv first
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows
python examples/client_stdio.py

You should see successful responses from the agent!

Verification

Run the full test suite to verify everything is working:

Unit Tests

uv run pytest -m unit -v

Optional: Development Tools

Install additional tools for development:

Pre-commit Hooks

## Install as a tool (recommended)
uv tool install pre-commit
pre-commit install
pre-commit run --all-files

## Or use the Makefile
make pre-commit-setup

Platform-Specific Notes

macOS

macOS Installation

Use Homebrew for easy installation:

# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install python@3.11
brew install docker
brew install git

# Start Docker Desktop
open /Applications/Docker.app

Ubuntu/Debian

Ubuntu Installation

# Update package list
sudo apt update

# Install Python
sudo apt install python3.11 python3.11-venv python3-pip

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
# Log out and back in

# Install Git
sudo apt install git

Windows

Windows Installation

1. Install Python:

   • Download from python.org
   • Check “Add Python to PATH” during installation

2. Install Docker Desktop:

   • Download from docker.com
   • Enable WSL 2 backend

3. Install Git:

   • Download from git-scm.com
   • Use Git Bash for commands

4. Use PowerShell or Git Bash for terminal commands

ARM64 (Apple Silicon, Graviton)

ARM64 Support

The project fully supports ARM64:

# Docker builds work natively
docker build -t mcp-server-langgraph:latest .

# Python packages have ARM64 wheels
uv sync

On Apple Silicon Macs, use native Python, not Rosetta!

Troubleshooting

Dependency installation fails

Problem: Dependencies fail to install

Solution:

# Using uv (recommended - handles this automatically):
uv sync

# If still failing, install build tools:
# Ubuntu: sudo apt install build-essential python3-dev
# macOS: xcode-select --install

# Then try again:
uv sync

uv handles most dependency resolution issues automatically and is much faster than pip!

Docker not found

Problem: docker: command not found

Solution:

• Ensure Docker Desktop is running (macOS/Windows)
• Add Docker to PATH (Linux: sudo usermod -aG docker $USER)
• Restart terminal

Permission denied

Problem: Permission errors when running Docker

Solution:

# Linux: Add user to docker group
sudo usermod -aG docker $USER
newgrp docker  # Or log out and back in

# macOS/Windows: Start Docker Desktop

Port already in use

Problem: Address already in use

Solution:

# Find what's using the port
lsof -i :8000  # macOS/Linux
netstat -ano | findstr :8000  # Windows

# Kill the process or change ports in docker-compose.yml

Next Steps

First Request

Send your first message to the agent

Configuration

Configure LLM providers and settings

Development Setup

Set up your development environment

Deploy

Deploy to production