vishnu2kmohan/mcp-server-langgraph

MCP Server with LangGraph + OpenFGA & Infisical

Full CI/CD status & all badges: | Telemetry Dashboard: vishnu2kmohan.github.io/mcp-server-langgraph

A production-ready cookie-cutter template for building MCP servers with LangGraph's Functional API. Features comprehensive authentication (JWT), fine-grained authorization (OpenFGA), secrets management (Infisical), and OpenTelemetry-based observability.

🎯 Opinionated, production-grade foundation for your MCP server projects.

🚀 Choose Your Path

Pick the quickstart that matches your needs:

New here? → Start with for step-by-step instructions

🔧 For Contributors: CI/CD Configuration

This project uses 19 GitHub Actions workflows with Google Cloud Platform (GCP) Workload Identity Federation for secure deployments.

Quick setup: | Full CI/CD status: | Workflow details:

📑 Table of Contents

Quick Links:

• 🚀 Use as Template - Generate your own MCP server project
• ⚡ Quick Start - Get running in 2 minutes
• 📦 Installation - Setup instructions
• 🏗️ Architecture - System design and agentic loop
• 🔐 Authentication - Security setup
• 🚢 Deployment - Production deployment guides

Main Sections:

• Template vs Project Usage - Choose your approach
• Features - Core capabilities and best practices
• Documentation - Complete guides and references
• Requirements - System and service requirements
• Usage - MCP server usage and client configuration
• Testing Strategy - Multi-layered testing approach
• Feature Flags - Dynamic feature control
• Observability - LangSmith and OpenTelemetry
• Configuration - Environment variables and settings
• Security Considerations - Production checklist
• API Gateway & Rate Limiting - Kong integration
• Quality Practices - Code quality standards
• Contributing - Contribution guidelines
• Support - Get help and report issues

🚀 Use This Template

# Generate your own MCP server project
uvx cookiecutter gh:vishnu2kmohan/mcp-server-langgraph

# Answer a few questions and get a fully configured project!

See for detailed information.

📖 Template vs Project Usage

Choose the approach that matches your goals:

💡 Recommendation: Use As Template for production projects, Clone Directly for learning and testing.

Features

⭐ Anthropic Best Practices (9.8/10 Adherence)

This project achieves reference-quality implementation of Anthropic's AI agent best practices with measurable improvements:

• 🎯 Just-in-Time Context Loading: 60% token reduction via dynamic semantic search (Qdrant)
• ⚡ Parallel Tool Execution: 1.5-2.5x faster through concurrent execution with dependency resolution
• 📝 Enhanced Structured Note-Taking: LLM-based 6-category information extraction
• ✅ Complete Agentic Loop: Gather-action-verify-repeat with 40-60% token reduction, 23% quality improvement

See: | , ,

🐍 Secure Code Execution (NEW)

Execute Python code securely with comprehensive validation and sandboxing:

• Dual Backend Support: Docker Engine (local/dev) + Kubernetes Jobs (production)
• AST-Based Validation: Import whitelist, blocks 30+ dangerous modules (os, subprocess, eval, etc.)
• Resource Limits: CPU, memory, timeout, disk quotas with enforcement
• Network Isolation: Configurable modes (none/allowlist/unrestricted)
• OWASP Top 10 Defenses: 34 security tests covering injection, deserialization, privilege escalation
• Progressive Tool Discovery: 98%+ token savings via search_tools endpoint (Anthropic best practice)
• Feature Flagged: Disabled by default (fail-closed security)

Test Coverage: 162 tests (100% passing) | Security: 96% code coverage | Backends: Docker + Kubernetes

See: | Anthropic MCP Guide

🎯 Core Capabilities

• Multi-LLM Support: 100+ providers via LiteLLM (Anthropic, OpenAI, Google, Azure, Bedrock, Ollama) + open-source models (Llama, Qwen, Mistral)
• MCP Protocol: Standard stdio & StreamableHTTP transports for AI agent exposure
• Enterprise Auth: JWT authentication, Keycloak SSO (OIDC/OAuth2), automatic token refresh, JWKS verification
• Session Management: InMemory (dev) or Redis (prod) with TTL, sliding windows, lifecycle management
• Fine-Grained Authorization: OpenFGA (Zanzibar-style) with role mapping, Keycloak sync, hierarchies
• Secrets Management: Infisical integration + env var fallback
• Observability: Dual stack (OpenTelemetry + LangSmith), Jaeger/Prometheus/Grafana, 30+ metrics, structured JSON logging
• LangGraph Platform: One-command deploy to managed cloud

🔒 GDPR & Privacy Compliance

Complete GDPR compliance with 6 API endpoints (Articles 15-21) and PostgreSQL storage backend. Features include atomic deletions, 7-year audit logs, and 14x cost savings vs Redis. Covers GDPR, HIPAA §164.312/§164.316, and SOC2 CC6.6/PI1.4.

See: | | |

📦 Optional Dependencies

Install optional features on demand: Code Execution ([code-execution]), Secrets Management ([secrets]), Self-Hosted Embeddings ([embeddings]), All Features ([all]). Production requires persistent storage (PostgreSQL/Redis) for GDPR compliance—in-memory mode is blocked.

Code Execution: Requires Docker (local) or Kubernetes (production). Enable with ENABLE_CODE_EXECUTION=true.

See: | |

🧪 Quality & Testing

27+ property tests, 20+ contract tests, performance regression tracking, mutation testing (80%+ target), strict typing (gradual rollout), OpenAPI validation. See .

🚀 Production Deployment

Kubernetes-ready for GKE/EKS/AKS with Helm charts, Kustomize overlays, automated CI/CD, HA (anti-affinity, HPA, PDB), 25+ Prometheus alerts, 4 Grafana dashboards. Service mesh compatible. See .

📚 Documentation

Primary Resources:

• Mintlify Documentation - Complete guides, tutorials, API references
• API Docs - Interactive OpenAPI/Swagger UI (local)
• - Key ADRs: , , ,

Deployment & Operations:

• | |

Examples: with demos for dynamic context loading, parallel execution, note-taking, and complete workflows

Requirements

System Requirements

• Python: 3.10, 3.11, or 3.12
• Memory: 2GB RAM minimum (4GB recommended for production)
• Disk: 500MB for dependencies + 1GB for optional vector databases
• OS: Linux, macOS, or Windows with WSL2

Required Services (for full features)

• Redis: Session storage (or use in-memory mode)
• PostgreSQL: Compliance data storage (optional)
• OpenFGA: Fine-grained authorization (optional)

Optional Components

• Qdrant/Weaviate: Vector database for semantic search
• Jaeger: Distributed tracing visualization
• Prometheus + Grafana: Metrics and monitoring

See for detailed requirements.

Installation

Using uv (10-100x faster than pip, reproducible builds):

# From PyPI
uv pip install mcp-server-langgraph

# Or clone and develop
git clone https://github.com/vishnu2kmohan/mcp-server-langgraph.git
cd mcp-server-langgraph
uv sync  # Installs all dependencies from pyproject.toml + uv.lock

Verify: python -c "import mcp_server_langgraph; print(mcp_server_langgraph.__version__)"

See: for Docker, venv setup, optional dependencies, and configuration

Architecture

System Flow: MCP Client → Auth Middleware (JWT + OpenFGA) → LangGraph Agent → Observability Stack (Jaeger/Prometheus/Grafana)

Agentic Loop: Implements Anthropic's gather-action-verify-repeat cycle with 6 enhancements:

• Just-in-Time Context Loading: Dynamic semantic search (60% token reduction)
• Context Compaction: Prevents overflow (40-60% token reduction)
• Parallel Tool Execution: Concurrent execution (1.5-2.5x speedup)
• Enhanced Note-Taking: LLM-based 6-category extraction
• Output Verification: LLM-as-judge pattern (23% quality improvement)
• Iterative Refinement: Up to 3 self-correction attempts

See: | | |

Database Architecture

Multi-Database Design: Single PostgreSQL instance with dedicated databases per service for clear separation of concerns and optimized schema management.

Database Overview

Environment-Based Naming

Databases use environment-aware naming for clear separation:

# Development/Staging/Production
gdpr, openfga, keycloak

# Test Environment
gdpr_test, openfga_test, keycloak_test

Detection: Automatic environment detection from POSTGRES_DB variable (suffix _test triggers test mode)

Automatic Initialization

Database initialization is fully automated via migrations/000_init_databases.sh:

1. Environment detection (dev vs test)
2. Create all 3 databases (idempotent)
3. Apply GDPR schema migrations
4. Validate table structure (5 GDPR tables)

Validation: Runtime validation via src/mcp_server_langgraph/health/database_checks.py ensures architecture compliance per ADR-0056.

Quick Database Setup

# Docker Compose (automatic initialization)
docker-compose up -d postgres

# Manual validation
python -c "
from mcp_server_langgraph.health.database_checks import validate_database_architecture
import asyncio
result = asyncio.run(validate_database_architecture())
print(f'Valid: {result.is_valid}')
print(f'Databases: {list(result.databases.keys())}')
"

See: | |

Quick Start

🐳 Docker Compose (Recommended)

Get the complete stack running in 2 minutes:

# Quick start script handles everything
./scripts/docker-compose-quickstart.sh

This starts:

• Agent API: http://localhost:8000 (MCP agent)
• OpenFGA: http://localhost:8080 (authorization)
• OpenFGA Playground: http://localhost:3001
• Jaeger UI: http://localhost:16686 (distributed tracing)
• Prometheus: http://localhost:9090 (metrics)
• Grafana: http://localhost:3000 (visualization, admin/admin)
• PostgreSQL: localhost:5432 (OpenFGA storage)

Then setup OpenFGA:

python scripts/setup/setup_openfga.py
# Add OPENFGA_STORE_ID and OPENFGA_MODEL_ID to .env
docker-compose restart agent

Test the agent:

curl http://localhost:8000/health

See for details.

🐍 Local Python Development

uv sync                              # Install dependencies
make git-hooks                       # Setup git hooks (REQUIRED for contributors)
cp .env.example .env                 # Configure (add GOOGLE_API_KEY)
docker-compose up -d openfga postgres  # Start infrastructure
python scripts/setup/setup_openfga.py  # Setup auth (save IDs to .env)
python -m mcp_server_langgraph.mcp.server_streamable  # Run agent
curl http://localhost:8000/health    # Test

Git Hooks (2-stage validation):

• Pre-commit (< 30s): Fast validation on changed files - commit frequently!
• Pre-push (8-12 min): Comprehensive validation matching CI - prevents surprises!

See: | |

👤 Creating Test Users

SECURITY NOTE: As of version 2.8.0, InMemoryUserProvider no longer seeds default users (alice, bob, admin) to prevent hard-coded credential vulnerabilities (CWE-798).

For testing/development with InMemoryUserProvider, explicitly create users:

from mcp_server_langgraph.auth.user_provider import InMemoryUserProvider

# Create provider with password hashing
provider = InMemoryUserProvider(use_password_hashing=True)

# Add test users
provider.add_user(
    username="testuser",
    password="secure-password-123",
    email="testuser@example.com",
    roles=["user", "premium"]
)

provider.add_user(
    username="admin",
    password="admin-secure-password",
    email="admin@example.com",
    roles=["admin"]
)

For Production: Use KeycloakUserProvider instead of InMemoryUserProvider. See Authentication for configuration details.

Usage

Running the MCP Server

python -m mcp_server_langgraph.mcp.server_stdio

Testing with Example Client

python examples/client_stdio.py

MCP Client Configuration

Add to your MCP client config (e.g., Claude Desktop):

{
  "mcpServers": {
    "langgraph-agent": {
      "command": "python",
      "args": ["/path/to/mcp_server_langgraph/src/mcp_server_langgraph/mcp/server_stdio.py"]
    }
  }
}

Authentication & Authorization

Enterprise-grade authentication and fine-grained authorization powered by Keycloak and OpenFGA:

Quick Example (JWT Authentication):

# 1. Login to get JWT
response = httpx.post("http://localhost:8000/auth/login",
    json={"username": "alice", "password": "alice123"})
token = response.json()["access_token"]

# 2. Use token in tool calls
response = httpx.post("http://localhost:8000/message",
    json={"method": "tools/call", "params": {"name": "agent_chat", "arguments": {"token": token, "message": "Hello!"}}})

Development Users (⚠️ Plaintext passwords - dev only):

• alice / alice123 (premium user) | bob / bob123 (standard user) | admin / admin123 (admin)

Production: Use AUTH_PROVIDER=keycloak with proper SSO. See for setup.

CI/CD Pipeline

Production-grade pipeline with 19 GitHub Actions workflows organized into four categories:

• 🔄 CI/CD: Main pipeline (Python 3.10-3.12, multi-arch Docker), E2E tests, quality tests (property/contract/mutation), coverage tracking
• 🔒 Security: Trivy/CodeQL/secrets scanning, GCP compliance validation, drift detection (6-hour intervals)
• 🚀 Deployment: Automated staging deploys, manual production approval, version management
• 🤖 Automation: Dependabot auto-merge, link checking, stale issue management

Key Metrics: 12 min avg build (66% faster), 80%+ coverage enforced, ~$40/month cost, automated staging + manual prod approval

See: | |

Testing Strategy

Multi-layered testing approach ensuring production quality:

Quick Start: make test (runs unit + integration tests) Coverage Report: make test-coverage (opens htmlcov/index.html) Complete Details: See for metrics, strategies, and CI/CD integration

CI/CD Test Execution

Tests run in parallel across multiple GitHub Actions workflows for comprehensive quality assurance:

Infrastructure:

• ci.yaml: Fast unit tests with mocked dependencies
• integration-tests.yaml: Full Docker stack with 4x parallelization via pytest-split (PostgreSQL:9432, Redis:9379, OpenFGA:9080, Keycloak:9082, Qdrant:9333)
• e2e-tests.yaml: Full Docker stack on offset ports for complete user journey validation
• quality-tests.yaml: Property-based testing (Hypothesis), contract validation (MCP protocol), performance regression tracking

Parallelization:

• integration-tests.yaml uses pytest-split with matrix strategy (4 groups) for 4x faster execution
• Each group runs independently for maximum CI efficiency

Pre-push Hooks:

• Fast mode (default): Optimized unit tests (~2-3 min) via pytest-xdist parallel execution
• Comprehensive mode: make validate-pre-push runs all test suites including integration tests (~8-12 min)

Best Practice: All workflows run in parallel for fast feedback. Integration tests now have full CI visibility with parallelization, catching infrastructure issues before merge.

Feature Flags

Control features dynamically without code changes:

# Enable/disable features via environment variables
FF_ENABLE_PYDANTIC_AI_ROUTING=true      # Type-safe routing (default: true)
FF_ENABLE_LLM_FALLBACK=true             # Multi-model fallback (default: true)
FF_ENABLE_OPENFGA=true                  # Authorization (default: true)
FF_OPENFGA_STRICT_MODE=false            # Fail-closed vs fail-open (default: false)
FF_PYDANTIC_AI_CONFIDENCE_THRESHOLD=0.7 # Routing confidence (default: 0.7)

# All flags with FF_ prefix (20+ available)

Key Flags:

• enable_pydantic_ai_routing: Type-safe routing with confidence scores
• enable_llm_fallback: Automatic fallback to alternative models
• enable_openfga: Fine-grained authorization (disable for development)
• openfga_strict_mode: Fail-closed (deny on error) vs fail-open (allow on error)
• enable_experimental_*: Master switches for experimental features

See: src/mcp_server_langgraph/core/feature_flags.py for all flags and validation

Observability

Dual observability stack: OpenTelemetry for infrastructure + LangSmith for LLM-specific tracing.

LangSmith (LLM Observability)

Set LANGSMITH_API_KEY for automatic tracing of all LLM calls. Features: prompt engineering, evaluations, user feedback, cost tracking, debugging. View at smith.langchain.com.

OpenTelemetry (Infrastructure)

End-to-end distributed tracing with Jaeger (http://localhost:16686), metrics with Prometheus (http://localhost:9090), structured JSON logging with trace correlation. Automatic collection of 30+ metrics (tool calls, auth failures, response duration).

Quick Start: Run docker compose up to launch full observability stack (Jaeger, Prometheus, Grafana).

See: | |

LangGraph Agent

The agent uses the functional API with:

• State Management: TypedDict-based state with message history
• Conditional Routing: Dynamic routing based on message content
• Tool Integration: Extensible tool system (extend in src/mcp_server_langgraph/core/agent.py)
• Checkpointing: Conversation persistence with MemorySaver

Extending the Agent

Add tools in src/mcp_server_langgraph/core/agent.py:

def custom_tool(state: AgentState) -> AgentState:
    # Your tool logic
    return state

workflow.add_node("custom_tool", custom_tool)
workflow.add_edge("router", "custom_tool")

Configuration

All settings via environment variables, Infisical, or .env file. Key variable categories:

• LLM: ANTHROPIC_API_KEY, MODEL_NAME (Claude Sonnet 4.5 default), GOOGLE_API_KEY
• Auth/Session: JWT_SECRET_KEY, OPENFGA_STORE_ID, OPENFGA_MODEL_ID, AUTH_PROVIDER (inmemory/keycloak)
• Observability: OTLP_ENDPOINT, LANGSMITH_API_KEY, LOG_LEVEL
• Anthropic Features: Dynamic context loading, parallel execution, verification (all disabled by default)
• Secrets Loading: Infisical (preferred) → Environment variables → Defaults

See: | |

Monitoring Dashboard

Access Grafana at http://localhost:3000 (admin/admin) and create dashboards using:

• Prometheus datasource: Metrics visualization
• Jaeger datasource: Trace exploration

Example queries:

• Request rate: rate(agent_tool_calls_total[5m])
• Error rate: rate(agent_calls_failed_total[5m])
• P95 latency: histogram_quantile(0.95, agent_response_duration_bucket)

Security Considerations

🔒 Production Checklist:

• Store JWT secret in Infisical
• Use production Infisical project with proper access controls
• Configure OpenFGA with PostgreSQL backend (not in-memory)
• Enable OpenFGA audit logging
• Enable TLS for all services (OTLP, OpenFGA, PostgreSQL)
• Implement rate limiting on MCP endpoints
• Use production-grade user database
• Review and minimize OpenFGA permissions
• Set up secret rotation in Infisical
• Enable monitoring alerts for auth failures
• Implement token rotation and revocation
• Use separate OpenFGA stores per environment
• Enable MFA for Infisical access

Deployment Options

Choose your deployment platform based on operational needs:

Kubernetes Platform Maturity:

• GKE: Full automation (dev/staging/prod), 32 Kustomize overlays, Cloud SQL, Workload Identity
• EKS: Full automation (dev/staging/prod), Karpenter autoscaling, IRSA, RDS/ElastiCache
• AKS: Manual deployment only, Terraform automation under development
• Rancher/Tanzu: Generic manifests, community-supported

Quick Kubernetes Deploy:

# Helm deployment
helm install langgraph-agent ./deployments/helm/langgraph-agent --set image.tag=v1.0.0

# Or Kustomize
kubectl apply -k deployments/kustomize/overlays/production

See: | |

API Gateway & Rate Limiting

Kong API Gateway integration provides:

• Rate Limiting: Tiered limits (60-1000 req/min) per consumer/tier
• Authentication: JWT, API Key, OAuth2
• Traffic Control: Request transformation, routing, load balancing
• Security: IP restriction, bot detection, CORS
• Monitoring: Prometheus metrics, request logging

# Deploy with Kong rate limiting
helm install langgraph-agent ./deployments/helm/langgraph-agent \
  --set kong.enabled=true \
  --set kong.rateLimitTier=premium

# Or apply Kong manifests directly
kubectl apply -k deployments/kubernetes/kong/

See for complete Kong setup and rate limiting configuration.

MCP Transports & Registry

The agent supports multiple MCP transports:

• StreamableHTTP (Recommended): Modern HTTP streaming for production
• stdio: For Claude Desktop and local applications

# StreamableHTTP (recommended for web/production)
python -m mcp_server_langgraph.mcp.server_streamable

# stdio (local/desktop)
python -m mcp_server_langgraph.mcp.server_stdio

# Access StreamableHTTP endpoints
POST /message         # Main MCP endpoint (streaming or regular)
GET /tools            # List tools
GET /resources        # List resources

Why StreamableHTTP?

• ✅ Modern HTTP/2+ streaming
• ✅ Better load balancer/proxy compatibility
• ✅ Proper request/response pairs
• ✅ Full MCP spec compliance
• ✅ Works with Kong rate limiting

Registry compliant - Includes manifest files for MCP Registry publication.

See for registry deployment and transport configuration.

Quality Practices

Quality Score: 9.6/10 across 7 dimensions (Code Organization, Testing, Type Safety, Documentation, Error Handling, Observability, Security).

Quality Gates: Pre-commit hooks (Ruff linting + formatting, mypy type checking, bandit security scanning) + CI/CD (unit/integration/property/contract/regression/mutation tests, OpenAPI validation). All tests run on Python 3.10-3.12.

Linting & Formatting (consolidated to Ruff for 10-100x faster performance):

• make lint-check - Run Ruff linter (replaces flake8 + isort checks)
• make lint-fix - Auto-fix linting issues + format code (replaces black + isort)
• make lint-format - Format code only (replaces black)
• make lint-type-check - Run mypy type checking (unchanged)
• make lint-security - Run bandit security scan (unchanged)

Testing:

• make test-unit - Fast unit tests with mocked dependencies
• make test-integration - End-to-end with real infrastructure
• make test-coverage - Generate coverage report
• make validate-pre-push - Quick validation (skip integration tests)
• CI_PARITY=1 make validate-pre-push - Full CI-equivalent validation (includes integration tests)

Development: Branch protection, conventional commits, code review required, 59 ADRs documenting architectural decisions.

See: | |

Contributors

Thanks to all the amazing people who have contributed to this project! 🙌

This project follows the all-contributors specification.

Want to be listed here? See !

Support

Need help? Check out our for:

• 📚 Documentation links
• 💬 Where to ask questions
• 🐛 How to report bugs
• 🔒 Security reporting

License

MIT - see file for details

Acknowledgments

Built with:

• LangGraph - Agent framework
• MCP - Model Context Protocol
• OpenFGA - Authorization
• LiteLLM - Multi-LLM support
• OpenTelemetry - Observability

Special thanks to the open source community!

Contributing

We welcome contributions from the community! 🎉

Quick Start for Contributors

1. Read the guides:

   • - Contribution guidelines
   • - Developer setup

2. Find something to work on:

   • Good First Issues
   • Help Wanted

3. Get help:

   • GitHub Discussions

Git Hook Performance

This project uses tiered validation hooks optimized for developer productivity:

Key Points:

• Pre-push uses dev profile (25 property test examples) for faster iteration
• CI uses ci profile (100 property test examples) for thorough validation
• Integration tests included in pre-push for CI parity
• Bypass for emergencies: git push --no-verify (use sparingly!)

Validation Tiers:

make validate-commit      # Tier-1: < 30s (quick checks)
make validate-push        # Tier-2: 3-5min (focused validation)
make validate-pre-push    # Tier-3: 8-12min (CI-equivalent, includes integration)

See for detailed validation workflow.

Contribution Areas

• 💻 Code: Features, bug fixes, performance improvements
• 📖 Documentation: Guides, tutorials, API docs
• 🧪 Testing: Unit tests, integration tests, test coverage
• 🔒 Security: Security improvements, audits
• 🌐 Translations: i18n support (future)
• 💡 Ideas: Feature requests, architecture discussions

All contributors will be recognized in our Contributors section!