Configuration du transport MCP

La note MCP Protocol Architecture explique les deux mécanismes de transport de façon conceptuelle. Cette note couvre la configuration pratique — comment configurer stdio pour le développement et l’HTTP streamable pour la production, et quand basculer entre les deux.

stdio pour le développement local

Le transport Standard I/O exécute le serveur comme un sous-processus. L’application hôte démarre le processus serveur, et toute la communication se fait via des pipes stdin/stdout.

Côté serveur, la configuration se résume à une ligne :

if __name__ == "__main__":
    mcp.run(transport="stdio")

Côté client pour Claude Desktop (claude_desktop_config.json) :

{
  "mcpServers": {
    "my-data-server": {
      "command": "uv",
      "args": ["run", "/path/to/server.py"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/analytics"
      }
    }
  }
}

Côté client pour Claude Code :

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

Pourquoi stdio est le mode par défaut

stdio vous offre plusieurs avantages gratuitement :

Aucune configuration réseau. Pas de ports à ouvrir, pas de certificats TLS, pas de résolution DNS.
Isolation des identifiants. Les identifiants transitent via des variables d’environnement, sans jamais toucher le réseau. Ils restent dans l’environnement du processus.
Isolation des processus. Chaque client obtient sa propre instance de serveur. Le crash d’un client n’affecte pas les autres.
Débogage simple. Les logs du serveur vont dans stderr, que le client peut capturer et afficher. Pas besoin d’agrégation de logs.

Pour le développement individuel et les outils internes utilisés par une seule personne à la fois, stdio est souvent tout ce dont vous avez besoin. De nombreuses équipes de data engineering ne passent jamais au-delà.

HTTP streamable pour la production

Quand vous avez besoin d’un serveur partagé par plusieurs clients — à travers une équipe, plusieurs environnements, ou déployé sur une infrastructure cloud — le transport HTTP est le bon choix.

Côté serveur :

mcp = FastMCP("RemoteDataServer", stateless_http=True)

if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="0.0.0.0", port=8000)

Configuration côté client :

{
  "mcpServers": {
    "remote-data-server": {
      "type": "http",
      "url": "https://mcp.votreentreprise.com",
      "headers": {
        "Authorization": "Bearer ${MCP_API_KEY}"
      }
    }
  }
}

Ce qu’HTTP ajoute

Le transport HTTP nécessite plus d’infrastructure mais permet :

Accès multi-client. Une instance serveur sert plusieurs utilisateurs. Utile pour les serveurs partagés d’équipe ou l’accès centralisé aux données.
Authentification. OAuth 2.1 pour les déploiements en production. La note Security Posture for AI Agents couvre les principes de sécurité ; le transport HTTP est là où vous les implémentez.
Équilibrage de charge. Déployez derrière des load balancers standard pour la haute disponibilité.
Server-Sent Events. Réponses en streaming pour les opérations longues. Le client reçoit des mises à jour incrémentielles pendant que le serveur traite une requête.
Déploiement centralisé. Le serveur tourne dans votre environnement cloud, proche des données, plutôt que sur la machine de chaque développeur.

Le flag `stateless_http`

Le paramètre stateless_http=True dans le constructeur FastMCP indique au serveur de ne pas maintenir d’état de session entre les requêtes. C’est important pour les déploiements en production derrière des load balancers — n’importe quelle requête peut aller vers n’importe quelle instance de serveur. Si votre serveur doit maintenir un état entre les appels (rare pour les cas d’usage en data engineering), omettez ce flag et assurez des sessions persistantes dans votre load balancer.

Quand basculer

La progression pour la plupart des équipes :

Commencer avec stdio. Construire le serveur, tester avec le MCP Inspector, connecter Claude Desktop ou Claude Code. Cela couvre l’usage individuel.
Rester avec stdio si le serveur est utilisé par une seule personne à la fois, si les sources de données sont accessibles depuis la machine du développeur, et s’il n’y a pas d’exigence de conformité pour la journalisation centralisée des accès.
Passer à HTTP quand plusieurs personnes ont besoin d’accéder au même serveur, quand les sources de données ne sont accessibles que depuis un environnement cloud, quand la sécurité nécessite une authentification centralisée et une journalisation d’audit, ou quand vous souhaitez un serveur actif 24h/24 sans avoir besoin de laisser un ordinateur portable allumé.

Le même code Python ou TypeScript fonctionne avec les deux transports. Le seul changement est l’appel mcp.run() et la configuration du client. Vous ne réécrivez pas les outils, ressources ou prompts lors du changement de transport.

Schémas de variables d’environnement

Les deux transports utilisent des variables d’environnement pour les identifiants, mais les schémas diffèrent :

stdio : définissez les variables d’environnement dans la configuration du client. Chaque instance client obtient son propre environnement. Simple et isolé.

{
  "env": {
    "DATABASE_URL": "postgresql://localhost/analytics",
    "API_KEY": "secret"
  }
}

HTTP : définissez les variables d’environnement sur l’hôte du serveur (environnement de conteneur, fichier d’environnement systemd, gestionnaire de secrets du fournisseur cloud). Tous les clients partagent le même environnement serveur.

# Dans votre configuration de déploiement
DATABASE_URL=postgresql://prod-host/analytics
API_KEY=secret

Pour les déploiements HTTP, préférez un gestionnaire de secrets (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault) aux variables d’environnement en texte clair. Le serveur lit les identifiants au démarrage, donc le gestionnaire de secrets n’a besoin d’être accessible que pendant l’initialisation.