Skip to content

day-1-developer.mdx

Latest commit

 

History

History
307 lines (228 loc) · 8.29 KB

day-1-developer.mdx

File metadata and controls

307 lines (228 loc) · 8.29 KB
Raw
title Day-1 Developer Guide
sidebarTitle Day-1 Guide
description Get from zero to running your first LangGraph MCP agent in under 5 minutes with progressive onboarding paths
icon rocket
contentType tutorial
seoTitle Day-1 Developer Guide - MCP Server LangGraph
seoDescription Get from zero to running your first LangGraph MCP agent in under 5 minutes with progressive onboarding paths Learn more about MCP Server LangGraph.
keywords
day-1
developer
guide
get
from
zero
running
your
first
langgraph

Day-1 Developer Guide

Welcome! This guide gets you from zero to running your first LangGraph MCP agent in under 5 minutes.

🎯 Choose Your Path

Path 1: Quickstart (0 infrastructure, < 2 minutes)

Perfect for: Learning, prototyping, exploring LangGraph + MCP

  • ✅ No Docker, no databases, no auth services
  • ✅ In-memory everything (conversations, checkpoints, sessions)
  • ✅ Free LLM tier (Google Gemini)
  • ✅ 3 endpoints, minimal complexity

→ Jump to Quickstart

Path 2: Local Development (Minimal infrastructure, ~5 minutes)

Perfect for: Feature development, integration testing

  • Uses: Redis (checkpoints), PostgreSQL (conversations)
  • No auth required (development mode)
  • Full observability optional
  • ~8 docker services

→ Jump to Local Dev

Path 3: Full Production Setup (~20 minutes)

Perfect for: Production deployment, enterprise features

  • Full stack: Auth (Keycloak/OpenFGA), observability (Prometheus/Grafana), compliance
  • Multi-tenant ready
  • All 10+ services

→ Jump to Production Setup

Quickstart (Zero Infrastructure)

Prerequisites

Steps

# 1. Clone and enter directory
git clone <your-repo>
cd mcp-server-langgraph

# 2. Install dependencies (35-45 seconds)
uv sync

# 3. Set ONE environment variable (Google Gemini API key - free tier)
export GOOGLE_API_KEY="your-key-here"  # Get free key: https://aistudio.google.com/apikey

# 4. Run the quickstart server
uv run python quickstart_app.py

# ✅ Server running at http://localhost:8000

Test It

# Send a chat message
curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello! What can you help me with?"}'

# Get conversation history
curl http://localhost:8000/conversations

# Interactive docs
open http://localhost:8000/docs

What You Get

  • In-memory agent: Conversations persist until server restart
  • 3 API endpoints: /chat, /conversations, /health
  • MemorySaver checkpointer: State management without Redis
  • No authentication: Open for local experimentation
  • Code location: quickstart_app.py + src/mcp_server_langgraph/presets/quickstart.py

Limitations

  • Data lost on restart (no persistent storage)
  • Single-threaded (no concurrency)
  • No auth/authorization
  • No observability/metrics

Next step: When you're ready for persistence and multi-user support, move to Path 2 (Local Development).

Local Development (Minimal Infrastructure)

Prerequisites

  • Docker & Docker Compose
  • uv package manager

Steps

# 1. Start minimal infrastructure (Redis + PostgreSQL only)
docker compose -f docker-compose.minimal.yml up -d

# 2. Copy environment template
cp .env.example .env

# 3. Configure for development mode
cat >> .env << EOF
# Minimal dev configuration
ENVIRONMENT=development
AUTH_PROVIDER=inmemory
CHECKPOINT_BACKEND=redis
REDIS_URL=redis://localhost:6379

# Database for conversations
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/langgraph

# LLM (use free tier)
GOOGLE_API_KEY=your-key-here

# Disable heavy features
OPENFGA_STORE_ID=
OPENFGA_MODEL_ID=
ENABLE_TRACING=false
ENABLE_METRICS=false
EOF

# 4. Run migrations
uv run alembic upgrade head

# 5. Start the server
uv run uvicorn src.mcp_server_langgraph.mcp.server_streamable:app --reload

# ✅ Server running at http://localhost:8000 with persistence

Test It

# Use same curl commands as quickstart, but conversations now persist!
curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Remember this: my favorite color is blue"}'

# Restart server, then:
curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "What is my favorite color?"}'
# Response: "Your favorite color is blue" ✅

What You Get

  • Persistent conversations: PostgreSQL storage
  • Distributed checkpointing: Redis for agent state
  • Fast development: Hot reload with --reload
  • Full MCP server: All tools, resources, prompts
  • Test infrastructure: Run full integration tests

Adding Features Incrementally

# Add observability (Jaeger tracing)
docker compose up -d jaeger
export ENABLE_TRACING=true
export JAEGER_ENDPOINT=http://localhost:14268/api/traces
# View traces: http://localhost:16686

# Add metrics (Prometheus)
docker compose up -d prometheus
export ENABLE_METRICS=true
# View metrics: http://localhost:9090

# Add authentication
docker compose up -d keycloak openfga
export AUTH_PROVIDER=keycloak
export OPENFGA_STORE_ID=<created-store-id>
# See docs/deployment/authentication.md for setup

Next step: When you're ready for production deployment, move to Path 3.

Full Production Setup

For production deployment with all enterprise features, see:

Common Tasks

Running Tests

# Unit tests (fast, no infrastructure needed)
make test-unit

# Integration tests (requires minimal docker-compose)
make test-integration

# All tests
make test

Development Workflow

# Format code
make format

# Lint
make lint

# Type check
make type-check

# Run fast quality checks before committing
make quick-check

Debugging

# Enable debug logging
export LOG_LEVEL=DEBUG

# Disable telemetry for cleaner logs
export OTEL_SDK_DISABLED=true

# Run with debugger
uv run python -m debugpy --listen 5678 --wait-for-client \
  -m uvicorn src.mcp_server_langgraph.mcp.server_streamable:app

Progressive Complexity Roadmap

Your learning journey:

  1. Quickstart (you are here) → Understand agent basics, MCP protocol
  2. Add Redis → Learn checkpointing, state management
  3. Add PostgreSQL → Persistent conversations, audit logs
  4. Add Authentication → Multi-user support, authorization
  5. Add Observability → Tracing, metrics, debugging in production
  6. Add Compliance Features → GDPR, HIPAA, audit trails
  7. Deploy to Kubernetes → Horizontal scaling, high availability

Each step builds on the previous, and you can stop whenever you have what you need.

Getting Help

What's Different from Production?

Feature Quickstart Local Dev Production
Persistence None (MemorySaver) Redis + PostgreSQL Redis + PostgreSQL + backups
Authentication None Optional (inmemory) Required (Keycloak + OpenFGA)
Observability None Optional Full (Jaeger + Prometheus + Grafana)
Compliance None Optional GDPR + HIPAA + audit logs
Scaling Single process Single process Kubernetes horizontal scaling
Startup time < 2 seconds ~10 seconds ~30 seconds (all services)
Code path quickstart_app.py server_streamable.py (dev mode) server_streamable.py (prod mode)

The goal of this project's architecture is to let you start simple and add complexity only when needed.

Ready to start? Pick your path above and let's go! 🚀