🤖 Server MCP - Agent LangGraph avec outils Math & Météo

🎯 Objectif pédagogique : Ce projet a pour but de montrer comment utiliser le protocole MCP (Model Context Protocol) pour connecter un agent IA à des outils externes, en utilisant les deux types de transport : stdio et streamable_http.

Un projet d'agent IA basé sur LangChain, LangGraph et le protocole MCP (Model Context Protocol), connectant un modèle LLM Groq à des outils externes via des serveurs MCP, avec observabilité via LangSmith et Langfuse.

Qu'est-ce que MCP ?

Le Model Context Protocol est un standard ouvert qui permet à un LLM de communiquer avec des outils externes (serveurs MCP) de manière structurée. Il définit comment un agent peut découvrir, appeler et recevoir les résultats d'outils distants, quel que soit le langage ou la plateforme utilisée.

Ce projet illustre deux modes de communication MCP :

📁 Structure du projet

Server_mcp/
├── src/
│   ├── client.py          # Agent principal (LangGraph + Groq)
│   ├── mathserver.py      # Serveur MCP — outils mathématiques (stdio)
│   └── weather.py         # Serveur MCP — outil météo (streamable_http)
├── .env                   # Clés API (non versionné)
├── .env.example           # Modèle de variables d'environnement
├── .gitignore
├── .python-version        
├── .venv/                
├── pyproject.toml         # Configuration du projet
├── requitements.txt      
├── uv.lock               
└── README.md

⚙️ Prérequis

• Python 3.11+ (voir .python-version)

• uv — gestionnaire de paquets (recommandé)

• Un compte Groq pour la clé API LLM

• Un compte LangSmith pour le tracing

• Un compte Langfuse pour l'observabilité

🚀 Installation

Avec uv (recommandé)

cd Server_mcp
uv sync

Avec pip classique

cd Server_mcp
python -m venv .venv
source .venv/bin/activate  # Sur Windows : .venv\Scripts\activate
pip install -r requitements.txt

Configurer les variables d'environnement

Copier le fichier .env.example et remplir les valeurs :

cp .env.example .env

Contenu du .env :

# LLM
GROQ_API_KEY=votre_clé_groq_ici

# LangSmith (tracing & évaluation)
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=votre_clé_langsmith_ici
LANGCHAIN_PROJECT=server_mcp

# Langfuse (observabilité & analytics)
LANGFUSE_PUBLIC_KEY=votre_clé_publique_langfuse_ici
LANGFUSE_SECRET_KEY=votre_clé_secrète_langfuse_ici
LANGFUSE_HOST=https://cloud.langfuse.com

🧩 Architecture

Ce projet utilise deux types de transport MCP :

src/client.py
    ├── MultiServerMCPClient
    │       ├── math (stdio)    → src/mathserver.py
    │       └── weather (http)  → src/weather.py :8000
    ├── ChatGroq (openai/gpt-oss-120b)
    ├── create_agent (LangChain)
    ├── LangSmith  ──────────────────────→ smith.langchain.com
    └── Langfuse   ──────────────────────→ cloud.langfuse.com

📊 Observabilité

LangSmith

Trace automatiquement toutes les invocations de l'agent, les appels aux outils MCP et les réponses du modèle. Accessible sur smith.langchain.com sous le projet server_mcp.

Langfuse

Fournit des analytics détaillés sur les coûts, latences et qualité des réponses LLM. Accessible sur cloud.langfuse.com.

🛠️ Les outils disponibles

Serveur Math (src/mathserver.py)

Serveur Météo (src/weather.py)

▶️ Lancer le projet

Étape 1 — Démarrer le serveur météo (Terminal 1)

source .venv/bin/activate
python src/weather.py

Le serveur démarre sur http://127.0.0.1:8000/mcp

Étape 2 — Lancer le client agent (Terminal 2)

source .venv/bin/activate
python src/client.py

Résultat attendu

Les outils disponibles: ['add', 'subtract', 'get_weather']
La réponse à votre question: (4+5) = 9 et (54-50) = 4

🐛 Erreurs fréquentes

📚 Technologies utilisées

• LangChain - Framework LLM

• LangGraph - Agent ReAct

• langchain-mcp-adapters -Intégration MCP

• FastMCP - Création de serveurs MCP

• Groq — Inférence LLM ultra-rapide

• LangSmith - Tracing & évaluation des chaînes LLM

• Langfuse - Observabilité & analytics LLM

• uv - Gestionnaire de paquets moderne

• python-dotenv- Gestion des variables d'environnement

👤 Auteur

BANE Seydina Mouhamet