Aller au contenu
English

Transport local

  • Leçon 9
  • 55 min
  • Module 3 : Créer et examiner un serveur local

Où nous en sommes

Dans la leçon précédente, nous avons lu des messages JSON-RPC à la main. Maintenant, nous créons support-mcp et nous l'exécutons comme processus local qu'une application d'IA démarre. Mais les messages et les journaux ne doivent pas se mélanger, et le serveur doit apprendre qui est l'appelant. Dans cette leçon, nous exécutons le serveur sur stdio, comme une cuisine avec un seul passe-plat pour les commandes et les assiettes.

Lue depuis YouTube. Rien ne se charge depuis YouTube avant que vous appuyiez sur lecture. Confidentialité

Ce que vous saurez faire

Exécutez le serveur MCP de Larkfield comme processus local. Vous voyez comment une application d’IA le démarre et comment les requêtes et les réponses circulent sur stdin et stdout. Vous voyez aussi pourquoi chaque ligne de journal doit plutôt aller sur stderr. Enfin, vous voyez où le serveur apprend qui est l’appelant.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 55 minutes

Ce que vous devez savoir

Votre projet

  • ~/projects/support-mcp avec le nouvel environnement de Choisir une trousse SDK maintenue : python -m pytest -q affiche 20 passed (20 tests réussis).
  • Le dépôt des exercices dans ~/projects/nextia-learning-labs, présenté au module 1. Si vous l’avez cloné, récupérez d’abord les fichiers les plus récents : git -C nextia-learning-labs pull.

Imaginez une petite cuisine de restaurant avec un passe-plat dans le mur. Les bons de commande entrent par cette ouverture. Les assiettes préparées sortent par la même ouverture. Le serveur apporte à une table tout ce qui s’y trouve.

Le cuisinier prend aussi des notes : « plus de basilic », « le four 2 est lent ». Il les écrit sur un tableau blanc dans la cuisine, jamais sur la tablette des assiettes. S’il pose une note sur cette tablette, le serveur l’apporte à un client. Au mieux, le client ne comprend pas. Au pire, le serveur laisse tomber le plateau.

Un autre détail. Le propriétaire ouvre la cuisine le matin et la ferme le soir. Il indique aussi au cuisinier de quel restaurant il s’agit. Les clients ne peuvent pas dire : « aujourd’hui, vous cuisinez pour le restaurant d’à côté ».

Amira crée la première version de support-mcp. Deux problèmes surviennent dès le premier jour.

D’abord, elle ajoute une ligne pour voir ce qui se passe : print("support-mcp is starting"). Elle démarre le serveur avec scripts/trace.py, le script qui envoie des requêtes JSON-RPC à la main. Il plante et s’arrête :

answer = json.loads(out)
^^^^^^^^^^^^^^^
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

Le script attendait une réponse JSON, mais il a lu support-mcp is starting (support-mcp démarre) à la place. La note s’est retrouvée sur la tablette des assiettes.

Ensuite, le serveur doit connaître l’organisation. Tomás propose un argument tenant (locataire) pour chaque outil : get_ticket(tenant, ticket_id). Kwame pose sa question habituelle : « Qui est l’appelant, et dans quelle organisation? » Avec la conception de Tomás, le modèle fournit l’organisation. Le texte d’un billet de soutien pourrait alors demander au modèle de lire les billets de l’autre commerce. Le modèle pourrait obéir.

Chaque programme qui s’exécute sur votre ordinateur est un processus, et chaque processus possède trois flux standard. L’entrée standard (stdin) est le flux qu’il lit. La sortie standard (stdout) est le flux où il écrit ses résultats. L’erreur standard (stderr) est une deuxième sortie, destinée aux messages sur le programme lui-même. Dans un terminal, vous tapez dans stdin, et les deux sorties apparaissent à l’écran.

Le transport stdio de MCP utilise ces flux. Un transport est le moyen par lequel les messages circulent entre le client et le serveur. Avec stdio, l’hôte démarre le serveur comme processus enfant, un processus qu’il crée et qui lui appartient. Il écrit les requêtes sur stdin du processus enfant, une ligne JSON par requête, et lit les réponses sur stdout. stdout transporte uniquement les messages du protocole. stderr est disponible, donc le serveur y écrit ses journaux. Ce sont le passe-plat, la tablette des assiettes et le tableau blanc.

L’hôte définit aussi l’environnement du processus enfant : les valeurs nommées, comme PATH, qu’un processus reçoit au démarrage. C’est là que le serveur de Larkfield trouve l’identité de l’appelant. Trois variables indiquent la personne qui l’a démarré, l’organisation et les autorisations : SUPPORT_USER, SUPPORT_TENANT et SUPPORT_SCOPES. Une portée est une autorisation nommée, comme tickets:read, présentée dans le cours sur l’authentification. Aucun outil n’a d’argument pour l’organisation, donc un modèle ne peut même pas en demander une autre.

Deux grands rectangles. À gauche, le processus hôte : l'application d'IA; dans ce module, scripts/trace.py, Client de la trousse SDK ou Inspector. Il contient un client MCP qui écrit les requêtes et lit les réponses. Une note indique qu'il démarre le processus enfant python -m support_mcp avec les variables d'environnement SUPPORT_USER=usr-sam, SUPPORT_TENANT=larkfield et SUPPORT_SCOPES=knowledge:read tickets:read. À droite, le processus enfant support-mcp, avec __main__.py (exécution sur stdio), server.py (outils, ressources, requête; MCPServer de la trousse SDK 2.3.0), identity.py (l'appelant selon l'environnement : Sam, Larkfield, membre du personnel), knowledge.py et les données (une organisation), et logs.py (une ligne JSON par événement). Une flèche bleue du client vers server.py : stdin, une requête JSON par ligne. Une flèche verte en sens inverse : stdout, uniquement les réponses, une par ligne. Une flèche grise de logs.py vers un rectangle en pointillé : stderr, vers le terminal ou le journal de l'hôte, jamais analysé comme MCP. Une note rouge : un print() sur stdout place du texte dans le flux des réponses; un client strict s'arrête avec JSONDecodeError; le client de la trousse SDK journalise Failed to parse JSONRPC message (échec de l'analyse du message JSONRPC); écrivez sur stderr. Une note à gauche : fermez stdin et le serveur s'arrête; l'hôte décide quand le serveur s'exécute.
Le transport stdio : l'hôte démarre support-mcp comme processus enfant. Les requêtes entrent sur stdin, les réponses sortent sur stdout et les journaux vont sur stderr.
Description textuelle du diagramme

Le processus hôte (ici scripts/trace.py, le Client de la trousse SDK ou Inspector) contient le client MCP. Il démarre le processus enfant python -m support_mcp avec trois variables d’environnement : SUPPORT_USER=usr-sam, SUPPORT_TENANT=larkfield et SUPPORT_SCOPES=knowledge:read tickets:read.

Le processus enfant contient cinq parties. __main__.py exécute le serveur sur stdio. server.py contient les outils, les ressources et la requête, créés avec MCPServer de la trousse SDK 2.3.0. identity.py trouve l’appelant dans l’environnement : Sam, Larkfield, membre du personnel. knowledge.py avec data/ lit les données d’une organisation, et logs.py écrit une ligne JSON par événement.

  • stdin, du client vers le serveur : une requête JSON par ligne.
  • stdout, du serveur vers le client : uniquement les réponses, une par ligne.
  • stderr, depuis logs.py : vers le terminal ou le journal de l’hôte. Il n’est jamais lu comme MCP.

Un print() sur stdout place du texte dans le flux des réponses. Un client strict s’arrête avec JSONDecodeError, et le client de la trousse SDK journalise « Failed to parse JSONRPC message » (échec de l’analyse du message JSONRPC). Écrivez sur stderr. Quand l’hôte ferme stdin, le serveur s’arrête : l’hôte décide quand le serveur s’exécute.

Voici un appel réel, enregistré du début à la fin. L’hôte est scripts/trace.py. Il démarre le serveur, envoie un tools/call pour le billet T-30002, lit la réponse et ferme l’entrée.

Une séquence entre trois participants : l'hôte scripts/trace.py, le serveur python -m support_mcp et stderr (le terminal). L'hôte démarre le processus enfant avec SUPPORT_USER, SUPPORT_TENANT et SUPPORT_SCOPES. Sur stdin, à 0,1 ms : tools/call get_ticket T-30002, id 1, 325 octets. Une note : Python et la trousse SDK démarrent; la première réponse attend environ 250 à 290 ms. À 285,2 ms, le serveur écrit une ligne de journal JSON sur stderr : event tool_call, tool get_ticket, outcome ok. Sur stdout, à 285,7 ms : result id 1, isError false, 1 325 octets. L'hôte ferme stdin, fin de l'entrée. Une note : le serveur s'arrête, code de sortie 0.
Un appel enregistré sur stdio. La ligne de journal va sur stderr; seule la réponse va sur stdout.
Description textuelle du diagramme
  1. L’hôte démarre le processus enfant, avec SUPPORT_USER, SUPPORT_TENANT et SUPPORT_SCOPES dans son environnement.
  2. À 0,1 ms, l’hôte écrit tools/call get_ticket pour T-30002 (id 1) sur stdin du serveur : 325 octets.
  3. Python et la trousse SDK démarrent. La première réponse d’un nouveau serveur attend environ 250 à 290 ms.
  4. À 285,2 ms, le serveur écrit une ligne de journal JSON sur stderr : "event": "tool_call", "tool": "get_ticket", "outcome": "ok".
  5. À 285,7 ms, la réponse arrive sur stdout : un résultat avec l’id 1, isError: false, 1 325 octets.
  6. L’hôte ferme stdin (fin de l’entrée), et le serveur s’arrête avec le code de sortie 0.

Remarquez que l’hôte a envoyé la requête immédiatement, sans échange préalable. Dans la révision 2026-07-28, chaque requête transporte sa propre enveloppe _meta. Un client peut donc commencer par n’importe quelle requête. Les 285 ms représentent le coût du démarrage d’un processus, pas celui de l’appel. Sur le portable de l’équipe du cours, le même appel à un serveur déjà en marche prenait une médiane de 0,68 ms.

Le serveur comprend quatre fichiers dans support_mcp/, plus un script et deux fichiers de tests. Vous les copiez depuis l’instantané end-of-m03, puis vous lisez les parties importantes.

  1. Dans ~/projects/support-mcp, avec l’environnement virtuel actif, copiez les fichiers de cette leçon :

    Fenêtre de terminal
    S=../nextia-learning-labs/C28/snapshots/end-of-m03
    cp "$S"/support_mcp/{__main__,server,identity,logs}.py support_mcp/
    cp "$S/scripts/trace.py" scripts/
    cp "$S/tests/test_server.py" "$S/tests/test_stdio.py" tests/
    cp "$S/.env.example" "$S/README.md" .
  2. Exécutez les tests :

    Fenêtre de terminal
    python -m pytest -q
    ........................................ [100%]
    40 passed in 2.51s

    Les 20 nouveaux tests démarrent le serveur de plusieurs façons. Cinq d’entre eux le démarrent comme véritable processus enfant.

  3. Envoyez les cinq requêtes de découverte à la main :

    Fenêtre de terminal
    python -m scripts.trace discovery --width 90
    == discovery
    0.1 ms -> {"jsonrpc": "2.0", "id": 1, "method": "server/discover", "params": {"_meta": {"io.modelcon …
    242.1 ms <- {"jsonrpc": "2.0", "id": 1, "result": {"cacheScope": "private", "capabilities": {"prompts" …
    242.1 ms -> {"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {"_meta": {"io.modelcontextp …
    242.7 ms <- {"jsonrpc": "2.0", "id": 2, "result": {"cacheScope": "private", "resultType": "complete", …
    242.7 ms -> {"jsonrpc": "2.0", "id": 3, "method": "resources/list", "params": {"_meta": {"io.modelcont …
    243.2 ms <- {"jsonrpc": "2.0", "id": 3, "result": {"cacheScope": "private", "resources": [{"descriptio …
    243.2 ms -> {"jsonrpc": "2.0", "id": 4, "method": "resources/templates/list", "params": {"_meta": {"io …
    243.6 ms <- {"jsonrpc": "2.0", "id": 4, "result": {"cacheScope": "private", "resourceTemplates": [{"de …
    243.6 ms -> {"jsonrpc": "2.0", "id": 5, "method": "prompts/list", "params": {"_meta": {"io.modelcontex …
    244.1 ms <- {"jsonrpc": "2.0", "id": 5, "result": {"cacheScope": "private", "prompts": [{"arguments": …

    --width 90 coupe chaque ligne après 90 caractères, avec la marque …. Vos durées seront différentes. La première réponse attend le démarrage du processus; les autres suivent en quelques millisecondes.

  4. Appelez un outil et repérez la ligne de journal :

    Fenêtre de terminal
    python -m scripts.trace valid-call --width 90
    == valid-call
    0.1 ms -> {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_ticket", "argu …
    log {"ts": "…", "event": "tool_call", "user": "usr-sam", "tenant":
    237.0 ms <- {"jsonrpc": "2.0", "id": 1, "result": {"content": [{"text": "{\n \"ticket_id\": \"T-30002 …

    Le script lit aussi stderr et affiche chaque ligne sous log (journal). Le champ ts contient l’heure de votre exécution.

Le script scripts/trace.py est un petit hôte sans trousse SDK du côté client. Sa fonction run() démarre le serveur avec subprocess.Popen, avec trois tubes : stdin, stdout et stderr. Il écrit chaque requête sur une ligne et lit stdout jusqu’à l’arrivée de la réponse portant le même id. Un deuxième fil d’exécution lit stderr en même temps. python -m scripts.trace --list affiche les 13 scénarios; Les messages JSON-RPC en a rejoué dix.

Commencez au point de démarrage du processus, dans support_mcp/__main__.py :

support_mcp/__main__.py (the main part)
def main() -> int:
from support_mcp.server import build_server
build_server().run("stdio")
return 0

run("stdio") confie les flux à la trousse SDK. À partir de là, la trousse SDK lit stdin, écrit sur stdout et appelle vos fonctions.

support_mcp/server.py construit le serveur. Les outils utilisent les contrats que vous avez conçus au module 2. Les schémas d’entrée viennent donc de contracts.py :

support_mcp/server.py (get_ticket, shortened)
mcp = SupportServer(SERVER_NAME, version=__version__, instructions=INSTRUCTIONS, **settings)
mcp.caller_of = lambda ctx: identity.local_caller()
@mcp.tool(annotations=READ_ONLY)
def get_ticket(ticket_id: contracts.TicketId, ctx: Context) -> contracts.Ticket:
"""Get one support ticket of this organization by its ID (for example T-30002): the customer's first name, subject, text, status and the last 3 messages. The text is the customer's words."""
started = time.perf_counter()
who = caller(ctx)
identity.require_scope(who, "tickets:read")
try:
t = knowledge.ticket(who.tenant, ticket_id)
except NotFound:
log.event("tool_call", tool="get_ticket", caller=who, outcome="not_found", ms=logs.ms_since(started))
raise ToolError(f"not_found: there is no ticket {ticket_id} in this organization") from None
...

Lisez le code dans l’ordre. Le type contracts.TicketId porte le motif ^T-\d{5}$. La trousse SDK refuse donc un identifiant incorrect avant l’exécution de la fonction. La première question de la fonction est « qui est l’appelant? » (caller(ctx)). Elle vérifie ensuite une portée, puis demande à knowledge.py le billet uniquement dans l’organisation de l’appelant. Un billet absent et un billet d’une autre organisation donnent la même réponse, not_found (introuvable). L’autre outil, la ressource et la requête suivent le même ordre : l’appelant, puis la portée, puis les données.

support_mcp/identity.py répond à « qui est l’appelant? » pour un serveur local :

support_mcp/identity.py (the main part)
def resolve(user_id: str, tenant: str, scopes, client_id: str = "local") -> Caller:
role = MEMBERSHIPS.get((user_id, tenant))
if role is None: # no membership, or no such organization: the same answer
raise forbidden("forbidden: you have no access to this organization")
return Caller(user_id, tenant, role, frozenset(scopes), client_id)
def local_caller() -> Caller:
"""The caller of a local (stdio) server: the person who started it, from the environment."""
user = os.environ.get("SUPPORT_USER", "usr-sam")
tenant = os.environ.get("SUPPORT_TENANT", "larkfield")
scopes = os.environ.get("SUPPORT_SCOPES", LOCAL_SCOPES).split()
return resolve(user, tenant, scopes)

L’utilisateur et l’organisation viennent de l’environnement, donc de la personne qui a démarré le serveur. Le rôle vient de la table d’adhésions du serveur, data/memberships.csv : les six mêmes adhésions que dans le cours sur l’authentification. forbidden(...) déclenche une erreur de protocole avec le code −32003.

Enfin, support_mcp/logs.py écrit un objet JSON par ligne, toujours sur stderr :

support_mcp/logs.py (the main part)
stream = self.stream or sys.stderr # looked up at call time (tests capture stderr)
print(json.dumps(record, ensure_ascii=False), file=stream, flush=True)

.env.example énumère les trois variables et leurs valeurs par défaut, et indique « Never put a real key in .env.example » (ne mettez jamais de vraie clé dans .env.example). Le projet lit l’environnement, pas ce fichier : définissez une variable dans votre interpréteur de commandes si vous avez besoin d’une autre valeur.

  1. Démarrez vous-même le serveur et envoyez stderr vers un fichier :

    Fenêtre de terminal
    python -m support_mcp 2> server-log.jsonl

    2> envoie le flux numéro 2, stderr, vers un fichier. stdout reste à l’écran. Cela fonctionne de la même façon dans PowerShell.

  2. Collez cette requête et appuyez sur Entrée :

    {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_ticket","arguments":{"ticket_id":"T-30002"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"by-hand","version":"1.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}

    Une ligne apparaît : la réponse, qui commence par {"jsonrpc":"2.0","id":1,"result":{"content":[{"text":"{\n \"ticket_id\": \"T-30002\",. Aucune ligne de journal n’apparaît à l’écran.

  3. Arrêtez le serveur avec Ctrl+D (Windows : Ctrl+Z, puis Entrée) et lisez le fichier :

    Fenêtre de terminal
    cat server-log.jsonl
    {"ts": "…", "event": "tool_call", "user": "usr-sam", "tenant": "larkfield", "role": "staff", "client": "local", "tool": "get_ticket", "outcome": "ok", "ms": 0.06}

    La ligne de journal indique l’appelant, l’outil et le résultat. Elle n’a jamais atteint le client.

  4. Supprimez le fichier : rm server-log.jsonl (Windows : Remove-Item server-log.jsonl).

À vous de jouer : démarrer le serveur sous une autre identité

Section intitulée « À vous de jouer : démarrer le serveur sous une autre identité »

Changez une seule chose : l’environnement. Avant d’exécuter chaque commande, prédisez la réponse.

Fenêtre de terminal
SUPPORT_TENANT=bramble python -m scripts.trace valid-call --width 90
SUPPORT_USER=usr-camille SUPPORT_TENANT=bramble python -m scripts.trace other-tenant --width 90
Afficher les réponses
== valid-call
0.1 ms -> {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_ticket", "argu …
234.3 ms <- {"jsonrpc": "2.0", "id": 1, "error": {"code": -32003, "message": "forbidden: you have no a …
== other-tenant
0.1 ms -> {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_ticket", "argu …
log {"ts": "…", "event": "tool_call", "user": "usr-camille", "tena
235.6 ms <- {"jsonrpc": "2.0", "id": 1, "result": {"content": [{"text": "{\n \"ticket_id\": \"T-40003 …

Sam n’a aucune adhésion chez Bramble Books. Chaque appel est donc refusé avec −32003, « forbidden : you have no access to this organization » (interdit : vous n’avez pas accès à cette organisation). Camille a un accès en lecture seule chez Bramble Books, donc T-40003, un billet de Bramble, est trouvé. La même requête qui donnait « not_found » à Sam chez Larkfield réussit maintenant, car l’appelant a changé, pas la requête. Une faute de frappe comme SUPPORT_TENANT=lark donne le même −32003 que Bramble : le serveur ne révèle pas si une organisation existe.

scripts/trace.py transmet tout votre environnement au serveur. Un véritable hôte est plus prudent. Voici comment un hôte Python démarre le serveur avec le client de la trousse SDK, tiré de tests/test_stdio.py :

tests/test_stdio.py (the first test, shortened)
params = StdioServerParameters(command=sys.executable, args=["-m", "support_mcp"])
async with Client(params) as client:
names = [t.name for t in (await client.list_tools()).tools]
r = await client.call_tool("get_ticket", {"ticket_id": "T-30002"})

StdioServerParameters indique quoi démarrer : une commande, ses arguments et, au besoin, env (variables d’environnement supplémentaires) et cwd (dossier de travail). Le client démarre le processus et l’arrête à la fin du bloc async with.

L’équipe du cours a vérifié ce que le client de la trousse SDK transmet au serveur. Elle avait défini SUPPORT_TENANT=bramble dans l’interpréteur de commandes :

the SDK passes by default: HOME, LOGNAME, PATH, SHELL, TERM, USER
1. StdioServerParameters(command, args, cwd) -> result, isError False: Charged twice for order LK-182074
2. ... env={'SUPPORT_TENANT': 'bramble'} -> error -32003: forbidden: you have no access to this organization

Sans env, le serveur n’a jamais reçu bramble. La trousse SDK 2.3.0 transmet seulement six variables sûres sur macOS et Linux. Le serveur a donc utilisé ses valeurs par défaut : Sam chez Larkfield. Avec env, l’hôte a transmis l’organisation volontairement. C’est un bon comportement par défaut. Votre interpréteur de commandes peut contenir des clés et des jetons. Un serveur devrait recevoir uniquement ce que son hôte choisit. Les assistants de bureau et les éditeurs de code qui démarrent des serveurs locaux ont une configuration avec les mêmes éléments. Elle indique une commande, ses arguments et les variables d’environnement. Le cours ne les a pas testés.

Utilisez stdio quand le serveur s’exécute sur le même ordinateur que l’hôte, pour une seule personne. Par exemple, un assistant sur le portable de Sam, un éditeur de code ou un test. Il ne nécessite aucun port réseau, et aucun autre ordinateur ne peut y accéder. La personne qui le démarre est l’appelant. L’environnement est donc un endroit raisonnable pour l’identité de l’appelant.

Il comporte aussi des coûts :

  • Un processus par hôte. Chaque hôte qui se connecte démarre sa propre copie. Chaque démarrage coûte environ un quart de seconde ici. Le cours a mesuré une médiane de 296,5 ms pour démarrer le serveur et énumérer ses outils.
  • Un seul ordinateur. L’application d’un partenaire ou un service de soutien partagé ne peut pas accéder à un processus sur le portable de Sam. Le module 5 ajoute Streamable HTTP, un transport sur le réseau.
  • L’identité est celle de la personne qui l’a démarré. Cela convient sur l’ordinateur personnel d’une personne. Cela ne suffit pas pour un serveur partagé, où chaque requête doit fournir sa propre preuve d’identité. Le module 5 remplace l’environnement par des jetons d’accès.
  • Gardez stdout propre. Un seul print() mal placé peut briser le flux, comme le montre l’encadré suivant.

Erreur courante

JSONDecodeError, ou : Failed to parse JSONRPC message from server (échec de l'analyse du message JSONRPC du serveur)

Symptôme : vous ajoutez un print() au serveur, et le script strict plante :

answer = json.loads(out)
^^^^^^^^^^^^^^^
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

Avec le client de la trousse SDK, l’appel fonctionne encore, mais stderr affiche un long message qui commence ainsi :

Failed to parse JSONRPC message from server
Traceback (most recent call last):
…
Invalid JSON: expected value at line 1 column 1 [type=json_invalid, input_value='support-mcp is starting', input_type=str]

Cause : un print() a écrit du texte brut dans stdout, le flux réservé aux messages du protocole. L’équipe du cours a testé un message d’accueil avant run("stdio") et un print() de débogage dans get_ticket. La trousse SDK 2.3.0 redirige stdout vers stderr pendant le traitement, mais pas toujours à temps. Dans les deux tests, le texte a atteint le client de la trousse SDK. D’autres hôtes pourraient plutôt fermer la connexion. L’équipe du cours ne les a pas testés.

Solution : écrivez tous les journaux dans stderr : print("debug:", ticket_id, file=sys.stderr), ou utilisez logs.py. Cherchez print( dans le serveur avant chaque commit (enregistrement des modifications).

Erreur courante

L'outil s'est exécuté, mais aucune réponse n'est arrivée

Symptôme : server-log.jsonl indique "outcome": "ok" (résultat : succès), mais stdout n’a rien affiché. Cela arrive quand l’entrée se ferme juste après la requête, par exemple avec echo '{…}' | python -m support_mcp.

Cause : la fin de l’entrée indique au serveur de s’arrêter. Il s’est arrêté après l’exécution de l’outil, mais avant d’écrire la réponse. L’équipe du cours a observé exactement cela : la ligne de journal avec "outcome": "ok", stdout vide et le code de sortie 0.

Solution : gardez stdin ouvert jusqu’à l’arrivée de la réponse. Un hôte le fait; scripts/trace.py aussi. À la main, collez la ligne dans le serveur en cours d’exécution et attendez la réponse avant d’appuyer sur Ctrl+D.

Réinitialisation. Si votre projet ne fonctionne plus, copiez l’instantané end-of-m03 comme dans La place de MCP, avec end-of-m03 plutôt que start. Il contient aussi la section du README pour la prochaine leçon.

Vérifiez votre compréhension

Nommez les trois flux standard du serveur stdio et dites ce qui passe dans chacun.

Afficher la réponse

stdin : les requêtes et notifications JSON-RPC du client, une par ligne. stdout : les réponses du serveur, une par ligne, et rien d’autre. stderr : les journaux du serveur, ici un objet JSON par ligne provenant de logs.py, plus les avertissements de la trousse SDK. L’hôte peut afficher stderr ou l’enregistrer, mais ne le lit jamais comme du MCP.

Vérifiez votre compréhension

Prédisez : un hôte démarre support-mcp avec le client de la trousse SDK. Son env définit SUPPORT_USER à usr-omar et rien d'autre. Omar a un accès en lecture seule chez Larkfield. Le client appelle get_ticket pour T-30002. Que reçoit-il, et pourquoi le modèle ne peut-il pas changer d'organisation?

Afficher la réponse

Un résultat normal avec le billet T-30002, isError: false (aucune erreur). Omar est membre de Larkfield, l’organisation par défaut, et les portées par défaut comprennent tickets:read (lecture des billets). Un accès en lecture seule n’empêche pas de lire un billet. L’organisation provient de SUPPORT_TENANT dans l’environnement choisi par l’hôte. Aucun outil n’a d’argument pour l’organisation. Rien de ce que le modèle écrit ne peut donc désigner une autre organisation.

Vérifiez votre compréhension

Vérification pratique : démarrez python -m support_mcp en redirigeant stderr vers server-log.jsonl, comme dans les étapes ci-dessus. Envoyez une requête get_ticket à la main et arrêtez le serveur. Qu'est-ce que l'écran a affiché, et que contient server-log.jsonl?

Afficher la réponse

L’écran affiche une seule ligne, la réponse : {"jsonrpc":"2.0","id":1,"result":…} avec le billet T-30002. Le fichier contient une ligne JSON avec "event": "tool_call" (événement : appel d’outil), "user": "usr-sam" (utilisateur), "tenant": "larkfield" (locataire), "tool": "get_ticket" (outil) et "outcome": "ok". stdout a transporté le protocole, et stderr a transporté le journal. Si l’écran affiche aussi la ligne de journal, il manque la partie 2> dans la commande.

Récapitulatif

  • Avec le transport stdio, l’hôte démarre le serveur comme processus enfant. Les requêtes entrent par stdin, les réponses sortent par stdout et les journaux vont dans stderr.
  • Un print() envoyé par erreur dans stdout perturbe le flux. Écrivez toujours les journaux dans stderr.
  • L’hôte choisit l’environnement du serveur. Le serveur de Larkfield détermine l’appelant à partir de SUPPORT_USER, SUPPORT_TENANT et SUPPORT_SCOPES. Il détermine le rôle à partir de sa propre table d’adhésions. Aucun outil n’accepte d’organisation.
  • Le client de la trousse SDK transmet seulement quelques variables sûres; un hôte transmet les autres avec env.

Votre projet contient maintenant le serveur, scripts/trace.py et 40 tests. Ensuite, vous examinez le serveur avec MCP Inspector, comme le ferait un développeur d’un autre hôte.

Leçon suivante : Examiner le comportement