Tutoriel sur le serveur MCP : installation, exemples et premier outil pour débutants

Votre assistant d’IA peut écrire un sonnet sur les tableurs, mais demandez-lui la taille d’un fichier sur votre ordinateur et il haussera les épaules. Le Model Context Protocol comble cet écart. Un serveur MCP est un petit programme qui donne à un assistant de vraies capacités : lire un dossier, interroger une base de données, appeler une API, voire générer une image. Ce tutoriel en construit un à partir d’un dossier vide, avec un premier outil fonctionnel en une vingtaine de minutes, sans expérience préalable du protocole.

Vous allez installer le SDK, écrire un outil, le tester dans l’Inspector, le brancher sur un vrai client, puis voir comment le même schéma alimente la génération d’images et de vidéos sur PicassoIA. Tout fonctionne avec du Python classique : si vous savez lire une fonction, vous pouvez suivre.

Ce que fait un serveur MCP

L’analogie avec l’USB-C

Avant l’USB-C, chaque appareil exigeait son propre câble. MCP fait pour l’IA ce que ce port unique a fait pour le matériel. Sans lui, chaque assistant avait besoin d’un code spécifique pour chaque service, ce qui représentait N assistants fois M services de colle logicielle. Avec lui, vous écrivez un seul serveur et tout client compatible MCP peut l’utiliser.

Anthropic a présenté le protocole fin 2024, et depuis, de nombreuses applications de chat, éditeurs de code et frameworks d’agents l’ont adopté. Cette adoption est la vraie raison de s’y intéresser : un outil que vous créez aujourd’hui n’est pas lié à un seul produit, et les compétences acquises se transposent à tout client qui parle le protocole.

Hôte, client et serveur

Trois rôles apparaissent dans chaque conversation MCP, et les débutants les confondent souvent.

Les messages circulent en JSON-RPC 2.0. Un serveur local communique via stdio : l’hôte lance votre script comme processus enfant et échange des messages par ses flux d’entrée et de sortie. Un serveur distant communique via Streamable HTTP, comme le font les connecteurs hébergés.

Voici ce qui se passe quand vous posez une question :

1. L’hôte démarre votre serveur, et son client demande : « Que pouvez-vous faire ? »
2. Le serveur répond avec une liste d’outils et le schéma de chacun.
3. Vous posez une question. Le modèle juge qu’un outil convient et émet un appel avec ses arguments.
4. L’hôte affiche une demande d’autorisation, puis transmet l’appel à votre serveur.
5. Votre fonction s’exécute, le résultat remonte, et le modèle rédige la réponse finale.

Outils, ressources et prompts

Un serveur peut proposer trois types d’éléments, et chacun a un propriétaire différent.

💡 Commencez par les outils. Ce sont les primitives les plus largement prises en charge, et un seul outil qui fonctionne vous apprend l’essentiel de ce que le protocole attend de vous.

Préparer votre environnement

De quoi avez-vous besoin

Rassemblez quatre éléments avant de taper le moindre code :

• Python 3.10 ou plus récent. Vérifiez avec python --version.
• Node.js 18 ou plus récent, uniquement pour le débogueur Inspector, qui s’exécute via npx.
• Un terminal et n’importe quel éditeur de code, même un éditeur simple.
• Un client MCP, comme Claude Desktop, Claude Code ou un éditeur compatible.

Windows, macOS et Linux fonctionnent tous. Seule la commande d’activation de l’environnement virtuel change, et le code ci-dessous est identique sur tous les systèmes.

Python ou TypeScript ?

Des SDK officiels existent pour plusieurs langages. Deux sont les choix les plus sûrs pour un premier serveur :

Ce tutoriel utilise Python. Les concepts, des outils aux transports, se transposent sans changement à tous les autres SDK.

Écrire votre premier outil

Créer le projet

Créez un dossier, ajoutez un environnement isolé et installez le SDK :

mkdir word-counter
cd word-counter
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install "mcp[cli]"

Copier le prompt

L’extra [cli] installe la commande mcp, qui inclut un lanceur de développement pour des tests rapides.

Votre outil en 15 lignes

Créez server.py avec ce contenu :

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("word-counter")

@mcp.tool()
def count_words(text: str) -> dict:
    """Count the words, characters and lines in a piece of text."""
    return {
        "words": len(text.split()),
        "characters": len(text),
        "lines": len(text.splitlines()),
    }

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

Copier le prompt

Trois détails font tout le travail :

1. La docstring est ce que le modèle lit pour décider quand appeler l’outil. Rédigez-la comme une description de poste en une ligne.
2. Les indications de type (text: str) deviennent le schéma JSON qui indique au client quels arguments existent et quel type chacun attend.
3. La valeur de retour est sérialisée et renvoyée au modèle comme résultat de l’outil.

Quand un client se connecte, il demande à votre serveur la liste des outils. FastMCP répond avec le nom count_words, votre docstring comme description et un schéma d’entrée généré à partir de la signature : un objet avec une propriété obligatoire de type chaîne appelée text. Ce minuscule document JSON est tout ce que le modèle connaît de votre fonction, c’est pourquoi le nommage et la formulation comptent davantage que le code astucieux.

💡 Si un outil n’est jamais appelé, la cause est presque toujours une docstring vague, et non un bug dans votre code.

Le tester dans l’Inspector

Ne connectez pas encore d’application de chat. Déboguez dans le MCP Inspector, un banc d’essai dans le navigateur :

npx @modelcontextprotocol/inspector python server.py

Copier le prompt

Une page locale s’ouvre. Ensuite :

1. Cliquez sur Connect pour lancer votre serveur.
2. Ouvrez l’onglet Tools et appuyez sur List Tools. count_words doit apparaître.
3. Sélectionnez-le, saisissez une phrase dans le champ text et lancez-le.
4. Vérifiez que le résultat JSON affiche les bons décomptes.

⚠️ N’utilisez jamais print() dans un serveur stdio. La sortie standard est le canal des messages, et un print parasite le corrompt. Envoyez les journaux vers stderr ou utilisez le module logging de Python.

Le connecter à un vrai client

Une fois que l’Inspector passe au vert, enregistrez le serveur auprès d’un client. Pour Claude Desktop, ajoutez ceci au fichier claude_desktop_config.json :

{
  "mcpServers": {
    "word-counter": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Copier le prompt

Pour Claude Code, une seule commande fait le même travail :

claude mcp add word-counter -- /absolute/path/to/.venv/bin/python /absolute/path/to/server.py

Copier le prompt

Redémarrez complètement l’application, puis demandez : « Combien de mots contient ce paragraphe ? » suivi d’un texte. Le client demande l’autorisation, exécute count_words et répond avec les chiffres exacts plutôt qu’une estimation.

Si rien n’apparaît, vérifiez ces points dans l’ordre :

• Chemins absolus uniquement. Les chemins relatifs échouent, car l’hôte lance le processus depuis son propre dossier.
• Pointez vers l’interpréteur du venv. Un simple python trouve souvent une autre installation sans le SDK.
• Quittez complètement l’application. Fermer la fenêtre la laisse généralement tourner en arrière-plan, dans la zone de notification.
• Lisez les journaux. Les clients écrivent des journaux par serveur qui montrent la trace d’erreur exacte.

Quand un simple script local ne suffit plus, changez de transport avec mcp.run(transport="streamable-http"), hébergez le serveur derrière HTTPS et ajoutez une authentification. Le code des outils reste exactement le même, et c’est le bénéfice discret de construire sur un protocole.

Trois exemples à reproduire

Une ressource en lecture seule

Les ressources exposent des données par URI. Celle-ci sert un fichier de notes :

from pathlib import Path

@mcp.resource("notes://today")
def todays_notes() -> str:
    """Return the contents of today's notes file."""
    return Path("notes/today.md").read_text(encoding="utf-8")

Copier le prompt

L’application peut l’attacher comme contexte sans que le modèle n’appelle quoi que ce soit. Les ressources peuvent aussi utiliser des modèles d’URI comme notes://{date}, si bien qu’une seule fonction dessert toute une famille de fichiers.

Un modèle de prompt

Un prompt est un point de départ réutilisable que l’utilisateur choisit dans un menu. Contrairement à un outil, le modèle ne décide jamais de l’exécuter : l’utilisateur le choisit, et le résultat devient le message d’ouverture de la conversation.

@mcp.prompt()
def review_code(code: str) -> str:
    """Ask for a short, friendly code review."""
    return f"Review this code and list the three most important fixes:\n\n{code}"

Copier le prompt

Un outil qui appelle une API

La plupart des serveurs réels encapsulent un service web. Celui-ci vérifie si un site est en ligne :

import httpx

@mcp.tool()
async def check_site(url: str) -> str:
    """Return the HTTP status code of a website."""
    async with httpx.AsyncClient(timeout=10) as client:
        response = await client.get(url, follow_redirects=True)
    return f"{url} answered with status {response.status_code}"

Copier le prompt

httpx est déjà fourni avec le SDK, et déclarer la fonction async permet au serveur de rester réactif pendant qu’il attend le réseau. Les appels réseau échouent, donc interceptez l’exception et renvoyez un message court et lisible. Un modèle qui voit « le site a expiré après 10 secondes » peut s’adapter et essayer autre chose, alors qu’une trace brute le désoriente.

Les erreurs qui font perdre votre après-midi

Le nommage aide autant que le tableau ci-dessus. Choisissez des verbes qui disent ce qui se passe, comme count_words ou check_site, limitez chaque outil à une seule tâche et réduisez les arguments à ceux dont le modèle a vraiment besoin. Un outil appelé process avec six champs facultatifs invite à deviner de travers.

Verrouiller l’accès

Un outil est du code que le modèle peut exécuter sur votre machine, traitez-le avec précaution :

• Privilégiez la lecture seule. N’ajoutez des outils d’écriture ou de suppression que lorsque c’est vraiment nécessaire.
• Validez les entrées. Un outil de fichiers doit refuser les chemins situés en dehors d’un dossier choisi.
• Gardez les secrets hors du code. Passez les tokens par le champ env de la configuration du client, ce qui les tient à l’écart de votre dépôt.
• Lisez la demande d’autorisation. N’approuvez pas un appel d’outil que vous ne pouvez pas expliquer.

Connecter PicassoIA via MCP

Ce que propose le connecteur

Les serveurs ne se limitent pas aux scripts locaux. PicassoIA expose la génération d’images et de vidéos aux clients MCP, si bien qu’un assistant peut créer des médias directement depuis une conversation. Le connecteur et l’API développeur partagent les mêmes quatre modèles :

Sous le capot, l’API suit un schéma familier : créer une prédiction, interroger son statut, puis récupérer le résultat. Les requêtes utilisent un Bearer token, les prompts peuvent atteindre 4 000 caractères, et un compte peut exécuter jusqu’à 5 prédictions simultanées, partagées entre les tokens et les connexions MCP. Gérez vos connexions depuis la page MCP de votre compte PicassoIA, et consultez votre offre pour savoir ce que comprend l’accès MCP.

Rédiger le code d’outil avec un grand modèle de langage (LLM)

Vous n’êtes pas obligé d’écrire chaque outil à la main. Les grands modèles de langage transforment une phrase simple en premier brouillon que vous pouvez tester dans l’Inspector :

Décrivez l’outil en une phrase, demandez une version FastMCP, puis exécutez-la dans l’Inspector avant de lui faire confiance. Les modèles écrivent du code plausible, et l’Inspector est le moyen de repérer les parties plausibles mais fausses.

Générer des images depuis une conversation

Une fois connecté, le flux de travail est court :

1. Ouvrez votre conversation compatible MCP et vérifiez que le connecteur PicassoIA est actif.
2. Décrivez la prise de vue avec des détails concrets : sujet, objectif, lumière et ambiance. Une phrase comme « une tasse en céramique sur un bureau en chêne, lumière douce de fenêtre à gauche, objectif 50 mm » vaut mieux que « belle photo de café ».
3. Laissez l’assistant appeler PicassoIA Image et attendez le résultat.
4. Affinez avec PicassoIA Image Editor Pro au lieu de tout recommencer.
5. Animez la meilleure image avec PicassoIA Video.

Traitez chaque prompt comme une courte liste de contrôle : sujet et action, décor, direction de la lumière, objectif et texture de surface. Gardez une seule idée par image, et générez par petits lots pour rester sous la limite de cinq simultanées pendant que les premiers résultats sont encore en cours de rendu.

💡 La génération est asynchrone. Si un client affiche « en attente », il interroge le serveur, il n’échoue pas.

Essayez-le sur Picasso IA dès aujourd’hui

Vous avez maintenant les éléments : un serveur, un premier outil, un test dans l’Inspector et une connexion à un client. Ajoutez un deuxième outil cette semaine, transformez l’un de vos scripts en serveur, et voyez à quelle vitesse votre assistant devient utile.

Passez ensuite au volet créatif. Rendez-vous sur Picasso IA, choisissez un modèle comme PicassoIA Image, et générez votre première image à partir d’une seule phrase. Testez l’éclairage, les objectifs et les ambiances, envoyez le meilleur résultat vers Seedance 2.5 Lite pour lui donner vie, et voyez jusqu’où mène un bon prompt.