Guide

SDK MCP : une façon commune de relier outils et modèles

Le Model Context Protocol décrit vos outils une fois pour tous les clients IA. Outils, ressources, transports, révision de juillet 2026, sécurité et conception.

L'équipe CodeWorlds14 min de lecture ·

Pratique Vibe coding avec Claude Code dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article10

Le Model Context Protocol résout un problème qui a bloqué pendant un an des intégrations sensées : chaque assistant avait sa propre façon de décrire les outils, donc brancher une base de données ou un système de tickets demandait un code distinct pour chacun. MCP introduit une description unique que tout client conforme comprend.

Ce que le protocole définit réellement

Côté serveur, il y a trois sortes de choses que l'on peut exposer, et la différence entre elles façonne la conception correcte d'une intégration.

Les outils sont des fonctions que le modèle peut appeler. Ils portent un nom, une description et un schéma d'arguments, et en exécuter un modifie un état ou récupère des données qui exigent une action. Envoyer un message, créer un ticket, lancer une requête sont des outils.

Les ressources sont du contenu identifié par une URI que le client peut lire et placer dans le contexte. Un fichier, un enregistrement, le résultat d'une requête. La différence essentielle est que lire une ressource n'a aucun effet de bord, donc un client peut la récupérer sans demander l'accord de l'utilisateur.

Les prompts sont des modèles d'instructions prêts à l'emploi que l'utilisateur choisit dans une liste. C'est la partie la moins utilisée du protocole, ce qui est dommage, car un modèle bien écrit évite d'expliquer chaque fois la même chose au modèle.

La distinction entre un outil et une ressource est souvent confondue, et un exemple la tranche. Lire un fichier sur le disque est une ressource, car cela ne change rien et le client peut le récupérer seul. Écrire un fichier est un outil, car il a un effet qui ne peut pas être annulé sans une décision délibérée. Cette séparation détermine quand un client demande l'accord de l'utilisateur et quand il agit discrètement.

Le client peut offrir des capacités en retour au serveur. Le sampling permet au serveur de demander un appel de modèle. L'elicitation lui permet de demander à l'utilisateur une information manquante en cours d'exécution. Les roots nomment les répertoires dans lesquels le serveur doit travailler.

Deux de ces trois capacités sont pourtant sur le départ. La révision de la spécification du 28 juillet 2026 a marqué le sampling et les roots comme dépréciés, avec la fonction distincte de logging. Ils continuent de fonctionner pendant la fenêtre de transition, mais dans une nouvelle intégration, passez les répertoires comme argument d'outil ou comme URI de ressource et appelez le modèle directement chez le fournisseur. L'elicitation reste, et après ce changement elle passe par des requêtes à allers-retours multiples.

Les transports et ce que la révision de juillet 2026 a changé

Le protocole définit deux façons de communiquer, et le choix découle de l'endroit où tourne le serveur.

Le transport par l'entrée et la sortie standard sert aux serveurs lancés localement comme sous-processus. Le client démarre le programme et lui parle par des flux, sans réseau et sans authentification. C'est le choix par défaut pour les outils qui tournent sur la machine de l'utilisateur.

Le transport par HTTP sert aux serveurs distants. Un seul endpoint accepte les requêtes POST et autorise des réponses en streaming avec des server sent events quand une opération dure longtemps.

La révision de la spécification du 28 juillet 2026 a changé quelque chose de fondamental ici : le cœur du protocole est devenu sans état. Les sessions au niveau du protocole ont disparu avec l'en-tête qui les identifiait, donc la même requête peut être traitée par n'importe quelle instance du serveur derrière un répartiteur de charge ordinaire.

La conséquence pratique est importante. Auparavant, un serveur distant exigeait d'attacher un client à une instance, ce qui compliquait le déploiement et entravait la mise à l'échelle. Désormais, un serveur MCP se déploie comme un service sans état ordinaire, sur Cloudflare par exemple, ou dans des conteneurs derrière un proxy standard.

La même révision a apporté les requêtes à allers-retours multiples, le routage par en-têtes, des résultats de listes pouvant être mis en cache, un durcissement de l'autorisation et un mécanisme formel d'extensions. Avec une intégration existante, vérifiez quelle version du protocole votre bibliothèque prend en charge, car le passage à l'absence d'état touche la couche de transport.

Votre premier serveur

Bash
npm install @modelcontextprotocol/sdk zod
TypeScript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { z } from 'zod'

const server = new McpServer({ name: 'orders', version: '1.0.0' })

server.registerTool(
  'order_status',
  {
    description: 'Returns order status by number in ORD-12345 format. Call this when the user asks about a specific order.',
    inputSchema: { number: z.string().describe('Order number, ORD-12345 format') },
  },
  async ({ number }) => {
    const order = await db.orders.findUnique({ where: { number } })
    return {
      content: [{ type: 'text', text: order ? JSON.stringify(order) : 'not found' }],
    }
  }
)

await server.connect(new StdioServerTransport())

L'enregistrement passe par la méthode registerTool, qui prend un nom, un objet de configuration et une fonction de traitement. L'ancienne forme tool, avec la description et le schéma comme arguments séparés, fonctionne encore, mais la bibliothèque TypeScript la marque comme dépréciée, donc le nouveau code doit utiliser la première forme.

La description de l'outil est la partie la plus importante de ce code. Le modèle ne voit que le nom, la description et le schéma des arguments, donc une phrase qui dit clairement quand appeler l'outil améliore la précision plus que n'importe quel réglage côté prompt. Une description qui dit « gère les données » ne règle rien.

En Python, la forme est analogue, et le schéma des arguments découle des annotations de types de la fonction, donc la description est générée à partir de la signature et de la docstring.

Connexion aux clients

La configuration côté client se réduit à indiquer comment lancer le serveur ou où le trouver.

JSON
{
  "mcpServers": {
    "orders": {
      "command": "node",
      "args": ["/path/to/server/index.js"],
      "env": { "DATABASE_URL": "postgres://..." }
    }
  }
}

Le même serveur fonctionne dans tous les clients conformes : dans l'application Claude, dans Cursor, dans les outils en ligne de commande et dans les bibliothèques d'agents. C'est tout l'intérêt du protocole : vous écrivez l'intégration une seule fois.

Testez un serveur qui tourne en local avant de le brancher à un assistant. L'outil d'inspection du kit de développement lance le serveur et permet d'appeler chaque fonction à la main, ce qui ramène le diagnostic d'une heure de tâtonnements à quelques minutes. Sans cette étape, un défaut dans un schéma d'arguments se manifeste comme un comportement inexplicable du modèle.

Il faut savoir que certaines plateformes exposent leurs intégrations via MCP plutôt que par une API propriétaire. Zapier ouvre ainsi des centaines de connexions d'applications, donc au lieu d'écrire votre propre serveur, brancher un serveur existant suffit parfois.

La sécurité, la partie que l'on ne peut pas sauter

Un serveur MCP donne à un modèle la capacité d'agir, et cela change le tableau des menaces par rapport à un simple chat.

Le premier sujet est la confiance dans le serveur lui-même. Installer le serveur de quelqu'un d'autre lui donne accès à tout ce que vous configurez : clés, fichiers, bases de données. Traitez cela comme l'installation d'une dépendance avec la permission d'exécuter du code, car c'est exactement ce que c'est.

Le deuxième est le contenu qui passe par les outils. Un document, un message ou une page lus par un outil peuvent porter des instructions visant le modèle plutôt que l'utilisateur. Le résultat d'un outil doit être traité comme une donnée, jamais comme une commande, et il est utile de le dire clairement dans l'instruction système.

Le troisième est la portée des permissions. Un serveur qui lit des tickets n'a pas besoin du droit de les supprimer. Des identifiants distincts avec des permissions minimales coûtent cinq minutes de configuration et limitent les conséquences d'une erreur du modèle. Avec une base de données, c'est la seule frontière qui tient, car une restriction écrite dans le code de l'outil peut être contournée : dans le serveur de référence PostgreSQL, aujourd'hui retiré, le mode lecture seule est tombé face à une requête qui fermait la transaction ouverte.

Le quatrième est la confirmation des opérations irréversibles. Le protocole permet à un client de demander à l'utilisateur avant d'exécuter un outil, et pour tout ce qui envoie des messages ou modifie des données, cela vaut la peine d'en profiter.

La révision de juillet 2026 a durci la couche d'autorisation, donc avec des serveurs distants, vérifiez si votre bibliothèque prend en charge les exigences actuelles avant de rien exposer publiquement.

Concevoir des outils que le modèle utilisera vraiment

Le serveur fonctionne correctement et le modèle l'ignore ou l'utilise mal. C'est la plainte la plus courante lors d'une première intégration, et elle se ramène presque toujours aux descriptions plutôt qu'au code.

Un nom doit décrire l'action, pas le système. Un nom comme crm_query ne dit rien au modèle, tandis que find_customer_by_email décrit ce qui se passe. Le modèle compare les noms à l'intention de l'utilisateur, donc plus on est proche d'une formulation naturelle, mieux c'est.

La description doit porter la condition de déclenchement. Pas « récupère les données client », mais « à appeler quand l'utilisateur interroge sur un client précis et a fourni une adresse e-mail ou un identifiant ». Cette seule phrase fait plus pour la précision que le reste de la configuration.

Décrivez les arguments avec un format et un exemple. Un champ texte nommé date sans indication de format produit trois notations différentes sur des appels consécutifs. Une annotation qui dit « format ISO, par exemple 2026-07-28 » règle la question une fois pour toutes.

Renvoyez des résultats filtrés et étiquetés. Le modèle gère mieux cinq champs lisibles par un humain qu'une réponse complète d'API. Quand il n'y a pas de résultat, dites-le clairement au lieu de renvoyer une structure vide, car le modèle y lit un succès.

Le dernier point concerne la granularité. Un outil qui fait cinq choses selon un paramètre est plus difficile à appeler avec précision que cinq outils séparés aux descriptions claires. Découpez selon l'intention de l'utilisateur plutôt que selon la structure de votre API.

MCP face aux autres approches

ApprocheAvantageInconvénientÀ choisir quand
MCPUne intégration pour tous les clients, une description standardProtocole jeune, changements entre révisionsUn outil utilisé par différents assistants
Function calling dans l'API d'un fournisseurPlus simple avec un seul modèle, contrôle totalCode séparé par fournisseurApplication liée à un seul modèle
Le plugin d'un outil précisLa meilleure intégration avec cet outilNe fonctionne que làÉtendre un seul éditeur
API REST simpleConnue de tous, matureLe modèle ne sait ni quand ni comment l'utiliserIntégration de système à système, sans modèle

Ces approches se combinent. Un serveur MCP exposé à l'extérieur sert les assistants, tandis que le même code appelé directement sert votre propre application, sans logique dupliquée.

Le choix dépend du nombre de clients qui doivent utiliser l'intégration. Avec une seule application construite sur OpenAI ou Claude, appeler directement des fonctions est souvent plus simple. Avec un outil destiné à une équipe qui utilise différents assistants, MCP évite d'écrire trois fois la même chose.

Déployer un serveur distant

Un serveur local suffit pour des outils personnels, tandis qu'une intégration utilisée par une équipe ou par un produit exige une édition distante, et cela entraîne d'autres exigences.

Commencez par l'authentification. Un serveur exposé à une adresse publique sans contrôle d'accès donne à tout le monde ce qu'il donnait au modèle. La révision de juillet 2026 a durci les exigences ici, donc vérifiez si votre bibliothèque les met en œuvre avant de rien exposer.

L'absence d'état simplifie le reste. Comme n'importe quelle instance peut traiter une requête, le déploiement se réduit à un service ordinaire derrière un répartiteur de charge, sans client attaché à un processus particulier. C'est une bonne nouvelle pour les déploiements en conteneurs et serverless.

Limitez les identifiants par installation. Si le serveur dessert de nombreux clients, chacun doit tourner avec ses propres données d'accès plutôt qu'avec une clé partagée aux pleines permissions. Avec une seule clé, une erreur de filtrage signifie un accès aux données de quelqu'un d'autre.

Journalisez les appels d'outils avec qui les a faits et avec quels arguments. Pour diagnostiquer un signalement du type « l'assistant a fait quelque chose d'étrange », c'est la seule source de réponses, et avec des outils qui modifient des données, c'est souvent aussi une exigence d'audit.

Le dernier point est le versionnement. Changer le schéma des arguments ou le sens d'un outil affecte tous les clients connectés en même temps, donc traitez la description d'un outil comme une API publique plutôt que comme un détail d'implémentation interne.

Erreurs courantes

La première, ce sont des descriptions d'outils génériques. Le modèle choisit un outil d'après sa description, donc « gère les données » garantit des appels aléatoires ou aucun.

La deuxième est d'exposer trop d'outils à la fois. Trente fonctions dans un seul serveur allongent le prompt à chaque appel et augmentent le taux de mauvais choix. Répartissez-les sur quelques serveurs thématiques.

La troisième est de renvoyer des réponses d'API brutes. Le modèle reçoit alors trois cents lignes de JSON dont il n'a besoin que de trois champs. Filtrez le résultat de votre côté, car cela réduit le coût et améliore la précision.

La quatrième est l'absence de gestion d'erreurs. Un outil qui lève une exception au lieu de renvoyer un message lisible bloque l'agent sans aucune information sur ce qui n'a pas marché.

La cinquième est d'ignorer la version du protocole lors d'une mise à niveau. Un changement dans la couche de transport peut déconnecter des clients construits sur une ancienne bibliothèque, donc lisez la liste des changements avant d'augmenter la version.

La sixième est de garder des clés en clair dans la configuration du client. Ce fichier est synchronisé ou arrive dans un dépôt, donc il vaut mieux fournir les secrets par les variables d'environnement du système.

FAQ

En quoi MCP diffère-t-il du function calling ?

Le function calling est un mécanisme interne à l'API d'un fournisseur précis : vous décrivez les outils dans le format de ce fournisseur et vous les gérez dans votre code. MCP est un protocole au-dessus, qui permet au même serveur de fonctionner avec tous les clients conformes sans changement. En dessous, le client utilise toujours le function calling.

Dois-je écrire le serveur dans un langage particulier ?

Non, des bibliothèques existent pour plusieurs langages, et le protocole repose sur un échange de messages, donc une implémentation dans n'importe quel environnement est possible. TypeScript et Python ont la prise en charge la plus mature.

Qu'a changé la révision du 2026-07-28 ?

Le changement principal est un cœur de protocole sans état : les sessions et l'en-tête qui les identifie ont disparu, donc un serveur distant se met à l'échelle comme un service sans état ordinaire. Elle a aussi apporté les requêtes à allers-retours multiples, le routage par en-têtes, les listes pouvant être mises en cache, une autorisation durcie et des extensions formelles. La même révision a marqué le sampling, les roots et le logging comme dépréciés, donc les nouvelles implémentations ne doivent plus les ajouter.

Un serveur MCP est-il sûr ?

Le protocole lui-même ne règle pas la question de la confiance. Installer le serveur de quelqu'un d'autre lui donne accès aux ressources que vous configurez, donc traitez-le comme une dépendance avec des droits d'exécution. Limitez les permissions des identifiants, exigez une confirmation pour les opérations irréversibles et traitez les résultats des outils comme des données plutôt que comme des commandes.

Par où commencer ?

Par un seul outil qui résout un problème précis que vous répétez aujourd'hui à la main. Un serveur avec une seule fonction et une bonne description apporte plus que dix fonctions décrites à la hâte, et en chemin il montre comment le modèle lit réellement vos descriptions. Branchez des intégrations existantes plutôt que de les écrire là où c'est possible, via LangChain ou via des serveurs exposés par des plateformes d'automatisation.

La spécification se trouve sur modelcontextprotocol.io, et le résumé des changements sur le blog du projet.

À lire aussi