Tools, Resources et Prompts : les primitives MCP et votre premier serveur

Tools, Resources et Prompts : les primitives MCP et votre premier serveur

Troisième volet de la série. Après le pourquoi et le comment, on regarde ce qu'un serveur MCP peut réellement offrir, puis on en écrit un en Node.js, testé de bout en bout. La version Symfony fera l'objet du quatrième article.

Les trois primitives d'un serveur

Un serveur MCP expose ses capacités sous trois formes, appelées primitives. Ce qui les distingue, c'est surtout qui décide de les utiliser :

Tools choisis par le modèle, Resources choisies par l'application, Prompts choisis par l'utilisateur
Schéma — Tools, Resources, Prompts : trois primitives, trois « décideurs » différents.

Tools : des actions, choisies par le modèle

Un tool est une fonction que le modèle peut décider d'appeler : créer un ticket, envoyer un e-mail, lancer une requête SQL. Il est décrit par :

  • un name et une description, que le modèle lit pour savoir quand l'utiliser (la description est en fait un mini-prompt : soignez-la) ;
  • un inputSchema (JSON Schema) qui décrit les arguments, et éventuellement un outputSchema pour un résultat structuré ;
  • des annotations facultatives qui informent le host : readOnlyHint (lecture seule), destructiveHint (action destructrice), idempotentHint (le rappeler n'a pas d'effet supplémentaire), openWorldHint (contact avec l'extérieur). Ce ne sont que des indices : le host ne doit pas leur faire aveuglément confiance.

Méthodes : tools/list pour découvrir, tools/call pour exécuter. Le résultat est un tableau content (texte, image, audio, lien vers une ressource…), éventuellement un structuredContent, et isError en cas d'échec.

Resources : des données à lire, choisies par l'application

Une resource est une donnée en lecture seule identifiée par une URI : le contenu d'un fichier (file:///…), un schéma de base de données, une page de documentation. Elle peut déclarer son type MIME.

  • resources/list liste les ressources fixes ;
  • resources/templates/list liste les modèles d'URI paramétrés, par exemple users://{userId}/profile ;
  • resources/read lit le contenu ;
  • resources/subscribe permet d'être prévenu par notifications/resources/updated quand une ressource change (en 2026-07-28, l'abonnement passe par subscriptions/listen).

Différence avec un tool : une resource ne fait rien, elle fournit du contexte. C'est généralement l'application (ou l'utilisateur, via un sélecteur) qui décide de l'ajouter à la conversation.

Prompts : des modèles d'instructions, choisis par l'utilisateur

Un prompt MCP est un modèle de message réutilisable et paramétré, proposé par le serveur : « fais la revue de ce code », « résume mes notes sur tel ton ». L'utilisateur le déclenche explicitement ; dans Claude Code, par exemple, les prompts apparaissent comme des commandes /mcp__serveur__prompt. Méthodes : prompts/list et prompts/get, qui renvoie une liste de messages prêts à envoyer au modèle.

Le client aussi offre des capacités

La communication n'est pas à sens unique : le serveur peut, lui aussi, faire des demandes au client, à condition que le client ait déclaré la capacité correspondante (elicitation, roots…). En révision 2025-11-25, le serveur envoie ces requêtes lui-même. En 2026-07-28, il répond plutôt « j'ai besoin d'une information » (input_required) et le client relance sa requête avec la réponse : c'est le mécanisme MRTR, présenté dans le deuxième article.

Le serveur demande une information manquante, le client affiche un formulaire, l'utilisateur répond
Schéma — L'elicitation : le serveur demande une information manquante à l'utilisateur, via le client.
  • Elicitation (elicitation/create) : en plein milieu d'une opération, le serveur demande une information à l'utilisateur, sous forme de formulaire typé. L'utilisateur peut accepter, refuser ou annuler. Règle de sécurité : on ne demande jamais de mot de passe ni de clé d'API par ce biais.
  • Roots (roots/list) : le client indique au serveur les dossiers (file://) sur lesquels travailler. Attention, c'est une indication de périmètre, pas une barrière de sécurité. Déprécié en 2026-07-28 : on passe désormais les chemins en paramètres d'outil ou en URI de ressource.
  • Sampling (sampling/createMessage) : le serveur demande au client de faire générer une réponse par le modèle. Déprécié dans la révision 2026-07-28 : un serveur qui a besoin d'un modèle l'appelle désormais directement, via l'API d'un fournisseur.

Le grand schéma : une session MCP complète

Voici, sur un seul schéma, tout ce qui circule pendant une session MCP en révision 2025-11-25, celle que parlent la plupart des outils aujourd'hui. Trois colonnes : le host (l'application, avec le modèle et l'utilisateur), le client MCP et le serveur MCP. Pour le lire :

  • flèche pleine : une requête, qui attend une réponse ;
  • flèche en pointillés : la réponse à cette requête ;
  • flèche à pointe ouverte : une notification, envoyée sans attendre de réponse.
Diagramme de séquence complet d'une session MCP entre host, client et serveur : initialisation, découverte, utilisation, requêtes du serveur et notifications
Schéma — Une session MCP complète (révision 2025-11-25) : qui parle à qui, dans quel ordre, et dans quel sens. (Cliquez sur le schéma pour l'agrandir.)

Ce qu'il faut remarquer :

  • L'initialisation, la découverte et l'utilisation vont surtout du client vers le serveur : le client découvre, puis appelle.
  • Dans le bloc « Le serveur demande », c'est le serveur qui prend l'initiative (elicitation/create, roots/list) et le client qui répond. Ces requêtes peuvent arriver à tout moment : roots/list souvent juste après l'initialisation, elicitation/create pendant le traitement d'un tools/call. En 2026-07-28, elles passent par MRTR.
  • Le modèle ne parle jamais directement au serveur : tout passe par le host et le client.

Pour garder le schéma lisible, quelques méthodes plus rares n'y figurent pas (modèles d'URI, abonnements, autocomplétion, logs).

Votre premier serveur MCP : un carnet de notes

Pour tout mettre en pratique, voici un serveur minimal qui expose les trois primitives : un tool pour ajouter une note, une resource pour les lire, un prompt pour les résumer. Il est construit avec le SDK TypeScript officiel (open source, sous licence Apache-2.0 ; le projet a quitté la licence MIT), dont il reprend l'exemple de démarrage.

Un assistant IA relié en MCP au serveur carnet-de-notes, qui expose ajouter_note, notes://toutes et resumer_notes
Schéma — Le serveur carnet-de-notes : un tool, une resource, un prompt.

Installation (Node.js 20 ou plus) :

mkdir carnet-de-notes && cd carnet-de-notes
npm init -y && npm pkg set type=module
npm install @modelcontextprotocol/server zod

Le fichier server.js :

// server.js — un mini serveur MCP « carnet de notes »
// Basé sur l'exemple officiel du SDK TypeScript MCP (open source).
import { McpServer } from '@modelcontextprotocol/server';
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';

const notes = ['Acheter du café', 'Relire l\'article sur MCP'];

const server = new McpServer({ name: 'carnet-de-notes', version: '1.0.0' });

// 1. Un TOOL : une action que le modèle peut décider d'appeler
server.registerTool(
    'ajouter_note',
    {
        description: 'Ajoute une note au carnet',
        inputSchema: z.object({
            texte: z.string().describe('Le contenu de la note'),
        }),
    },
    async ({ texte }) => {
        notes.push(texte);
        return { content: [{ type: 'text', text: `Note ajoutée (${notes.length} au total).` }] };
    }
);

// 2. Une RESOURCE : des données en lecture seule, identifiées par une URI
server.registerResource(
    'liste-des-notes',
    'notes://toutes',
    { title: 'Toutes les notes', mimeType: 'text/plain' },
    async (uri) => ({
        contents: [{ uri: uri.href, text: notes.map((n, i) => `${i + 1}. ${n}`).join('\n') }],
    })
);

// 3. Un PROMPT : un modèle d'instruction réutilisable, choisi par l'utilisateur
server.registerPrompt(
    'resumer_notes',
    {
        description: 'Demande un résumé des notes du carnet',
        argsSchema: z.object({ ton: z.string().describe('Ex. : « sérieux » ou « drôle »') }),
    },
    ({ ton }) => ({
        messages: [{
            role: 'user',
            content: { type: 'text', text: `Résume mes notes sur un ton ${ton} :\n${notes.join('\n')}` },
        }],
    })
);

// Transport stdio : le serveur parle via l'entrée/sortie standard
await server.connect(new StdioServerTransport());
console.error('Serveur MCP « carnet-de-notes » prêt'); // stderr : stdout est réservé au protocole

Deux choses à remarquer :

  • Le schéma Zod sert à tout : le SDK en tire le JSON Schema envoyé au client dans tools/list (puis transmis au modèle), et valide les arguments avant d'appeler votre fonction.
  • Le tool et le prompt sont identifiés par un nom, la resource par une URI (notes://toutes).

Le tester sans IA : le MCP Inspector

Avant de brancher une IA, testez votre serveur avec l'outil officiel, qui ouvre une interface web pour lister et appeler tools, resources et prompts à la main :

npx @modelcontextprotocol/inspector node server.js

En dehors de l'Inspector, j'ai fait le test avec un petit client automatisé : voici les vraies réponses du serveur.

tools/list     -> ajouter_note, inputSchema { texte: string, requis }
tools/call     -> Note ajoutée (3 au total).
resources/read -> 1. Acheter du café / 2. Relire l'article sur MCP / 3. Tester MCP
prompts/get    -> Résume mes notes sur un ton drôle : …
appel invalide -> isError = true (texte attendu, nombre reçu)

Le brancher sur une IA

Dans Claude Code, une commande suffit (chemin absolu vers votre fichier) :

claude mcp add carnet -- node /chemin/vers/carnet-de-notes/server.js

Dans Claude Desktop, ajoutez le serveur au fichier claude_desktop_config.json, puis redémarrez l'application :

{
  "mcpServers": {
    "carnet": {
      "command": "node",
      "args": ["/chemin/vers/carnet-de-notes/server.js"]
    }
  }
}

Demandez ensuite « Ajoute une note : préparer l'entretien MCP » : le modèle choisit seul le tool ajouter_note, et le host vous demande l'autorisation avant de l'exécuter.

Et en PHP ?

On peut écrire exactement le même serveur en PHP, et même l'intégrer à une application Symfony grâce au MCP Bundle : vos services deviennent des tools, des resources et des prompts avec de simples attributs PHP. C'est l'objet du quatrième article, avec le même carnet de notes.

Les bons réflexes de sécurité

  • Validez côté serveur, toujours : la validation du client ne remplace jamais la vôtre.
  • Moindre privilège : un serveur qui lit des fichiers n'a pas besoin d'en écrire. Isolez en conteneur ce qui n'est pas de confiance.
  • Méfiez-vous des serveurs inconnus : les descriptions d'outils sont lues par le modèle, et une description malveillante peut le manipuler (on parle d'empoisonnement d'outil, une forme d'injection de prompt).
  • Gardez un humain dans la boucle pour les actions destructrices : c'est le rôle des confirmations du host.

Questions d'entretien : les réponses courtes

Tool, resource ou prompt ?
Tool : une action, choisie par le modèle. Resource : une donnée en lecture, identifiée par une URI, choisie par l'application. Prompt : un modèle d'instruction, choisi par l'utilisateur.
Comment le modèle sait-il quels outils existent ?
Le client appelle tools/list ; le host transmet au modèle le nom, la description et le JSON Schema de chaque outil.
Le serveur peut-il prendre l'initiative ?
Oui, avec des notifications (list_changed, progress…). Pour demander une information : en 2025-11-25, il envoie lui-même une requête au client (elicitation/create…), si le client a déclaré la capacité ; en 2026-07-28, il répond input_required et le client relance sa requête (MRTR).
Que sont les annotations d'un tool ?
Des indices (readOnlyHint, destructiveHint…) qui aident le host à décider s'il faut demander confirmation. Ce ne sont pas des garanties de sécurité.
Pourquoi ne jamais écrire sur stdout dans un serveur stdio ?
Parce que stdout transporte les messages JSON-RPC : n'importe quel texte parasite casse le protocole. Les logs vont sur stderr.

Pour aller plus loin : le dépôt modelcontextprotocol/servers rassemble des serveurs de référence open source (fichiers, Git, mémoire, récupération de pages web…), parfaits pour lire du vrai code MCP.

Suite et fin : créer ce même serveur MCP avec Symfony et le MCP Bundle.

Continuer la lecture

Article suivant — Outils IA Créer un serveur MCP avec Symfony : le MCP Bundle pas à pas Explorer tout : Outils IA

Commentaires

Soyez le premier à laisser un commentaire — le robot attend.

Laisser un commentaire

Les champs obligatoires sont indiqués avec *