Configuration d'un projet de serveur MCP

Une fois que vous avez décidé de construire un serveur MCP personnalisé (voir Custom MCP Server Decision Criteria) et choisi votre SDK (voir MCP SDK Selection for Data Engineering), la configuration réelle du projet prend environ 10 minutes. Ce tutoriel couvre le chemin Python avec FastMCP, le choix le plus courant pour les équipes d’ingénierie de données.

1. Initialiser le projet

Avec uv (recommandé) :

uv init my-data-mcp-server
cd my-data-mcp-server

Ou avec Python standard :

mkdir my-data-mcp-server
cd my-data-mcp-server
python -m venv .venv
source .venv/bin/activate

uv est le chemin le plus rapide — il gère automatiquement la création d’environnements virtuels, la résolution de dépendances et les fichiers de verrouillage. Si vous utilisez déjà uv pour d’autres projets Python, c’est le choix naturel.

2. Ajouter les dépendances

# MCP core avec outils CLI
uv add "mcp[cli]"

# Dépendances courantes en ingénierie de données
uv add httpx          # Client HTTP pour les appels d'API
uv add pydantic       # Validation de données (généralement inclus avec mcp)
uv add sqlalchemy     # Connexions aux bases de données
uv add asyncpg        # PostgreSQL asynchrone (si nécessaire)

Commencez léger. Vous pourrez toujours ajouter des dépendances plus tard. La seule dépendance essentielle est mcp[cli] — tout le reste dépend de ce à quoi votre serveur se connecte.

3. Créer le fichier serveur

Créez server.py en utilisant le FastMCP Server Skeleton comme point de départ, puis ajoutez vos outils. Pour un serveur d’ingénierie de données, vous devrez généralement importer les bibliothèques client de votre stack de données — le client BigQuery, le client REST d’Airflow, le SDK de votre catalogue — aux côtés du SDK MCP.

4. Tester avec MCP Inspector

npx @modelcontextprotocol/inspector uv run server.py

Ouvrez l’URL affichée dans votre navigateur. Vérifiez :

Tous les outils apparaissent dans la liste
Les descriptions sont claires et précises
Les schémas d’entrée semblent corrects (types, valeurs par défaut, contraintes)
Les outils s’exécutent sans erreur sur des entrées valides
La gestion des erreurs retourne des messages utiles

La note MCP Server Testing and Debugging couvre le workflow de test complet, y compris le piège de journalisation stderr qui vous mordra si vous utilisez des instructions print().

5. Installer dans Claude Desktop

La commande d’installation rapide crée automatiquement une entrée de configuration :

uv run mcp install server.py --name "My Data Server"

Ou modifiez manuellement claude_desktop_config.json (macOS : ~/Library/Application Support/Claude/, Windows : %APPDATA%\Claude\) :

{
  "mcpServers": {
    "my-data-server": {
      "command": "uv",
      "args": ["run", "/full/path/to/server.py"],
      "env": {
        "DATABASE_URL": "your-connection-string"
      }
    }
  }
}

Utilisez le chemin absolu complet vers server.py. Les chemins relatifs sont peu fiables car le répertoire de travail de l’application host peut ne pas être celui que vous attendez.

6. Installer dans Claude Code

Pour usage personnel :

claude mcp add my-data-server -- uv run /full/path/to/server.py

Pour les projets d’équipe (crée un fichier .mcp.json qui peut être versionné) :

claude mcp add my-data-server -s project -- uv run /full/path/to/server.py

La configuration délimitée au projet signifie que les coéquipiers clonent le dépôt et obtiennent automatiquement la même configuration MCP. Pas de configuration manuelle par développeur.

7. Tester dans le client réel

claude
> What tools does my-data-server provide?
> [Test each tool with realistic inputs]

Ce test d’intégration révèle des problèmes que l’Inspector ne détecte pas — comment l’IA interprète vos descriptions, si elle passe les paramètres correctement, et si les formats de réponse sont utiles en conversation. Voir MCP Server Testing and Debugging pour le workflow de test complet en trois étapes.

Structure du projet

Un projet de serveur MCP typique :

my-data-mcp-server/
├── pyproject.toml      # Dépendances et métadonnées
├── server.py           # Fichier serveur principal
├── tools/              # Implémentations des outils (optionnel, pour les grands serveurs)
│   ├── __init__.py
│   ├── catalog.py
│   └── quality.py
├── tests/              # Tests unitaires pour la logique métier
│   └── test_tools.py
└── README.md           # Instructions de configuration et d'utilisation

Pour les petits serveurs (3-5 outils), un seul server.py convient. Ne sur-ingénieriez pas la structure avant d’en avoir besoin. Divisez en un répertoire tools/ lorsque le serveur dépasse 200-300 lignes ou lorsque différents outils ont des dépendances différentes.

Le répertoire tests/ contient les tests unitaires pour votre logique métier — les requêtes réelles aux bases de données, les appels d’API et le traitement des données. Testez ceux-ci indépendamment de MCP, comme décrit dans MCP Server Testing and Debugging.

Prochaines étapes après la configuration

Une fois le serveur opérationnel et connecté :

Commencez petit. Un ou deux outils qui encapsulent votre système le plus interrogé.
Itérez sur les descriptions. Observez comment l’IA utilise vos outils. Si elle choisit le mauvais outil, améliorez la description.
Ajoutez des sorties structurées. Passez des retours sous forme de chaîne aux modèles Pydantic au fur et à mesure que vous identifiez quels outils ont besoin de formats de sortie cohérents. Voir MCP Tool Design Patterns.
Envisagez les ressources et les prompts. Si l’IA a besoin de contexte en lecture seule (schémas, configurations), ajoutez des ressources. Si votre équipe a des workflows répétables, ajoutez des prompts.
Planifiez la production. Quand le serveur est assez utile pour être partagé, envisagez de passer au transport HTTP pour un accès multi-utilisateurs.