Tutoriel · Les agents IA sur les réseaux sociaux

Écrire un serveur MCP : outils, transport et le premier appel client

Par Antoine Blanco··7 min de lecture

Un serveur MCP est un programme qui répond à tools/list avec une liste d'outils et à tools/call en exécutant l'un d'eux. Avec le SDK Python, ça fait douze lignes. Tout ce qui suit a été exécuté aujourd'hui, le 20 novembre 2026, sur mcp 2.3.0 face à la révision 2026-07-28 du protocole, sorties brutes incluses.

Ce qu'un serveur MCP doit savoir répondre

Trois choses, et seule la première est obligatoire.

Un serveur déclare ses capacités (tools, resources, prompts), répond à tools/list avec un ensemble déterministe de définitions d'outils, et répond à tools/call en exécutant l'un d'eux et en renvoyant du contenu. Les resources et les prompts sont optionnels. La plupart des serveurs qui valent la peine d'être écrits sont un sac d'outils et rien d'autre.

La définition d'un outil demande un name, une description et un inputSchema qui soit un objet JSON Schema valide. title, outputSchema et annotations sont optionnels. La spécification des outils dit que les noms devraient faire de 1 à 128 caractères pris dans les lettres, les chiffres, le tiret bas, le tiret et le point, et être uniques dans le serveur. Pour un outil sans argument, le schéma recommandé est {"type": "object", "additionalProperties": false}, jamais null.

Écrire un serveur MCP avec le SDK Python MCP

Installe le SDK et son extra CLI :

pip install "mcp[cli]"      # or: uv add "mcp[cli]"

C'est mcp 2.3.0, publié sur PyPI le 2 octobre 2026. Le point d'entrée est MCPServer, qui a remplacé l'ancien nom FastMCP :

from mcp.server import MCPServer

mcp = MCPServer("word-count", version="1.0.0")


@mcp.tool()
def count_words(text: str) -> int:
    """Count the words in a block of text."""
    return len(text.split())


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

Trois choses se passent sans que tu les écrives. La docstring devient la description de l'outil, la seule chose que le modèle lit pour décider s'il l'appelle : écris-la pour le modèle, pas pour tes collègues. Les annotations de type deviennent l'inputSchema. Et l'annotation de retour devient un outputSchema, si bien que le résultat arrive en JSON structuré, pas seulement en texte.

Teste-le avant de brancher le moindre client :

mcp dev server.py

Ça ouvre le MCP Inspector, qui liste les outils et te laisse les appeler à la main. C'est le moyen le plus rapide de découvrir qu'un nom d'argument que tu croyais évident ne l'est pas.

stdio ou Streamable HTTP

mcp.run() part en stdio par défaut. La révision 2026-07-28 définit exactement deux transports standard, et le choix porte sur qui lance le processus, pas sur les fonctionnalités : la sémantique du protocole est identique sur tous les transports.

stdio Streamable HTTP
Qui le lance le client, en sous-processus toi, en service
Cadrage des messages JSON-RPC délimité par des retours à la ligne sur stdin et stdout un POST HTTP par message
Accessible à d'autres personnes non oui
Auth hérite du processus local OAuth ou une clé d'API
Annulation notifications/cancelled le client ferme le flux
Adapté à un outil sur ta propre machine tout ce que d'autres personnes utilisent

Une règle que tout le monde casse le premier jour : en stdio, stdout appartient au protocole. Un print() égaré corrompt le flux. Logge sur stderr.

Change de transport avec un seul argument :

mcp.run(transport="streamable-http")
INFO  StreamableHTTP session manager started
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

L'endpoint est /mcp, donc http://127.0.0.1:8000/mcp.

Le premier appel client, pour de vrai

Pointe le client du SDK lui-même sur le serveur stdio :

import asyncio, sys
from mcp import Client, StdioServerParameters

async def main():
    params = StdioServerParameters(command=sys.executable, args=["server.py"])
    async with Client(params) as client:
        print("protocol:", client.protocol_version)
        tools = await client.list_tools()
        for t in tools.tools:
            print("tool:", t.name, "|", t.description)
        res = await client.call_tool("count_words", {"text": "one two three four"})
        print("content:", res.content)
        print("structured:", res.structured_content)

asyncio.run(main())

Ce que ça a affiché :

protocol: 2026-07-28
tool: count_words | Count the words in a block of text.
content: [TextContent(type='text', text='4', annotations=None, meta=None)]
structured: {'result': 4}

Remarque les deux orthographes. Le format sur le câble est en camelCase (inputSchema, structuredContent, isError) ; les objets Python sont en snake_case (input_schema, structured_content, is_error). Lire t.inputSchema lève une AttributeError, et c'est là que j'ai perdu mes cinq premières minutes.

En HTTP, curl a besoin de quatre en-têtes, et les rater, c'est toute la session de débogage :

curl -s -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'mcp-method: tools/list' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{
       "io.modelcontextprotocol/protocolVersion":"2026-07-28",
       "io.modelcontextprotocol/clientCapabilities":{}}}}'
{"jsonrpc":"2.0","id":1,"result":{"cacheScope":"private","resultType":"complete",
 "tools":[{"description":"Count the words in a block of text.",
 "inputSchema":{"type":"object","properties":{"text":{"title":"Text","type":"string"}},
 "required":["text"],"title":"count_wordsArguments"},"name":"count_words",
 "outputSchema":{"properties":{"result":{"title":"Result","type":"integer"}},
 "required":["result"],"type":"object"}}],"ttlMs":0}}

Deux erreurs que tu vas rencontrer dans cet ordre. Enlève _meta et tu obtiens -32602 : params._meta must be an object carrying the required 'io.modelcontextprotocol/protocolVersion' and 'io.modelcontextprotocol/clientCapabilities' envelope keys. Garde _meta mais oublie l'en-tête et tu obtiens -32020 : mcp-method header does not match the request body's method. Un tools/call en demande un troisième, mcp-name, qui porte le nom de l'outil, sinon le même -32020 revient.

Avec tous, l'appel renvoie les deux formes :

{"id":2,"result":{"content":[{"text":"4","type":"text"}],"isError":false,
 "resultType":"complete","structuredContent":{"result":4}}}

Ce que la révision 2026-07-28 a changé

Si tu suis un tutoriel écrit pour 2025-06-18 ou 2025-11-25, trois choses ont bougé.

Il n'y a plus de poignée de main initialize. Chaque requête déclare sa propre version de protocole et les capacités du client dans params._meta, et le serveur accepte ou refuse chaque requête indépendamment. Streamable HTTP recopie ces valeurs dans des en-têtes pour qu'un proxy puisse router sans lire le corps, et le corps reste la source de vérité.

La découverte tient en un seul appel optionnel. server/discover renvoie d'un coup les versions supportées, les capacités et l'identité :

{"id":3,"result":{"capabilities":{"prompts":{"listChanged":true},
 "resources":{"listChanged":true,"subscribe":true},"tools":{"listChanged":true}},
 "supportedVersions":["2026-07-28"]}}

Et il n'y a plus de session de protocole. Un serveur ne peut pas garder d'état par connexion, donc tout ce qui s'étend sur plusieurs appels doit passer par un identifiant explicite que tu renvoies depuis un outil et que tu acceptes en argument au suivant. Envoie une requête à l'ancienne à ce serveur et il retombe sur le chemin à session, qui répond Bad Request: Missing session ID. C'est la compatibilité ascendante qui fonctionne, pas un bug. Ce que ça implique pour le déploiement est dans l'hébergement d'un serveur MCP.

Le chemin d'erreur qui apprend au modèle

La spec coupe les erreurs en deux. Une requête mal formée ou une méthode inconnue est une erreur JSON-RPC. Un échec que le modèle pourrait corriger en réessayant autrement est un résultat d'outil avec isError: true, parce que les clients les renvoient au modèle, qui peut alors se corriger.

Le SDK fait presque bien tout seul. Un outil inconnu renvoie un résultat, pas une erreur de protocole :

{"id":4,"result":{"content":[{"text":"Unknown tool: nope","type":"text"}],"isError":true}}

Mais lève une exception dans un outil et le message est avalé :

raise ValueError("text is empty, pass at least one word")
is_error: True
content: Error executing tool count_words

Le modèle sait maintenant que l'appel a échoué et rien sur le pourquoi, donc il réessaie avec les mêmes arguments. Si tu veux que le modèle se corrige, renvoie l'explication dans le texte de l'outil au lieu de lever une exception. Cette seule habitude vaut plus que tout le travail sur les schémas.

Avant de laisser un agent s'en approcher

Un serveur qui marche sur ton portable n'est pas un serveur que tu confies à quelqu'un d'autre. Deux pièces manquent, et chacune a sa page ici : l'authentification, traitée dans OAuth pour un serveur MCP, et le choix de l'hébergement. La spécification est directe sur le reste : valide chaque entrée, limite le débit des appels, et ne marque jamais un secret avec x-mcp-header, parce que la valeur d'un en-tête est visible par tous les intermédiaires du trajet.

Ça vaut aussi la peine de se demander si tu dois écrire ce serveur. Pour quelque chose comme la publication sociale, le dur n'est pas MCP, c'est huit API de plateformes, huit flux OAuth et le rafraîchissement des tokens : c'est pour ça que PlugKit fait tourner un serveur MCP hébergé sur https://api.plugkit.co/mcp au lieu de livrer un gabarit, à 49 $ par mois pour 5 comptes connectés, résiliable à tout moment, ou 97 $ par mois pour 30, après sept jours gratuits avec une carte demandée à l'inscription et rien de prélevé avant le 7e jour. Vérifié le 20 novembre 2026. Écris le tien quand les outils sont les tiens : ta base de données, ton API interne, ton système de build. MCP ou API REST pour ton agent est la décision d'un niveau au-dessus, et le serveur MCP Instagram montre à quoi ressemble le résultat fini côté client.

FAQ

Dans quel langage écrire un serveur MCP ?

Celui dans lequel tes outils vivent déjà. La liste officielle des SDK en compte dix : TypeScript, Python, C#, Go, Rust et Ruby au tier 1, Java au tier 2, Swift, PHP et Kotlin au tier 3, le tier disant à quel point il est complet et maintenu. Ils parlent tous le même JSON-RPC. Le serveur est une fine enveloppe autour de code que tu as déjà, donc réécrire ce code dans un autre langage est l'erreur qui coûte cher.

Est-ce que j'ai besoin de Streamable HTTP, ou stdio suffit ?

stdio suffit quand le seul utilisateur c'est toi sur cette machine : le client lance ton script en sous-processus et rien n'est exposé. Dès qu'une deuxième personne ou un agent hébergé en a besoin, il te faut Streamable HTTP, une URL et de l'authentification.

Comment tester un serveur MCP sans client ?

mcp dev server.py ouvre le MCP Inspector, qui liste tes outils et les appelle avec les arguments que tu tapes. Ensuite, curl sur l'endpoint HTTP montre le JSON exact qu'un vrai client envoie, et c'est comme ça que tu attrapes un schéma que le modèle lira de travers.

Pourquoi mon outil marche dans l'Inspector mais pas dans l'agent ?

En général, la description. Le modèle choisit ses outils en lisant description et les titres d'arguments, et une docstring du genre « gère le truc » ne lui donne rien à quoi s'accrocher. Réécris la docstring comme une consigne, dis ce que l'outil renvoie, et nomme les arguments comme un appelant les devinerait.

Combien d'outils un serveur MCP devrait-il exposer ?

Moins que tu n'en as envie. Chaque définition reste dans le contexte du modèle à chaque tour, donc cent outils coûtent de vrais tokens et de vraies confusions entre quasi-doublons. Groupe par tâche, renvoie du contenu structuré pour qu'un outil réponde à plusieurs questions, et sépare en plusieurs serveurs avant de découper un serveur en cent noms.

AB
Antoine BlancoFondateur de PlugKit. Gère ses propres comptes Instagram, YouTube et X via l'API et le serveur MCP décrits ici.

Un plug pour chaque plateforme que ton agent touche

49 $ par mois pour 5 comptes connectés, résiliable à tout moment. Toutes les fonctionnalités dans tous les forfaits.

Récupère ta clé API →
Français ▾