Les racines (roots)

Mise à jour du 2 novembre 2026 — roots. La spécification MCP 2026-07-28 déprécie les Roots. La recommandation officielle est de transmettre les répertoires ou fichiers par les paramètres des outils, par des URI de ressources ou par la configuration du serveur. Ce que vous apprenez ici reste utile pour maintenir des serveurs existants. Dans le SDK Python v2, la forme recommandée est le résolveur ListRoots(), reçu par Annotated[ListRootsResult, Resolve(fonction)] ; ctx.session.list_roots() reste disponible sur les connexions de l’ère 2025, avec un avertissement de dépréciation. Les roots sont une indication, pas un contrôle d’accès. Source : Sampling and roots (SDK Python v2).

Les racines (roots) sont un moyen d’accorder à des serveurs MCP l’accès à des fichiers et dossiers spécifiques sur votre machine locale. Pensez-y comme un système de permissions qui dit au serveur MCP : « Tu peux accéder à ces fichiers », mais les roots font bien plus que d’accorder des permissions. À la fin de cette leçon, vous saurez quel problème elles résolvent, pourquoi le SDK ne les impose pas, et comment vérifier un chemin correctement.

Le problème que les roots résolvent

Sans roots, vous rencontreriez un problème courant. Imaginez un serveur MCP avec un outil de conversion vidéo qui prend un chemin de fichier et convertit un MP4 en MOV.

Un utilisateur demande à Claude : “Convertis biking.mp4 en format mov”. Claude appellerait l’outil avec juste le nom de fichier. Mais voilà le problème — Claude n’a aucun moyen de parcourir tout votre système de fichiers pour trouver où se trouve ce fichier.

Votre système de fichiers peut être complexe, avec des fichiers éparpillés dans différents répertoires. L’utilisateur sait que biking.mp4 est dans son dossier Vidéos, mais Claude n’a pas ce contexte.

Vous pourriez exiger que les utilisateurs fournissent toujours des chemins complets, mais ce n’est pas très ergonomique.

Les roots en action

Voici comment le workflow change avec les roots :

1. L'utilisateur demande de convertir une vidéo
2. Claude appelle list_roots pour voir quels répertoires sont accessibles
3. Claude appelle read_dir sur les répertoires accessibles pour trouver le fichier
4. Une fois trouvé, Claude appelle l'outil de conversion avec le chemin complet

Tout cela se passe automatiquement — les utilisateurs peuvent toujours simplement dire “convertis biking.mp4” sans fournir de chemins complets.

Sécurité et limites d’accès

Les roots offrent aussi une sécurité en limitant l’accès. Si vous n’accordez l’accès qu’à votre dossier Bureau, le serveur MCP ne peut pas accéder aux fichiers dans d’autres emplacements comme Documents ou Téléchargements.

Quand Claude essaie d’accéder à un fichier en dehors des roots approuvées, il reçoit une erreur et peut informer l’utilisateur que le fichier n’est pas accessible dans la configuration actuelle du serveur.

Détails d’implémentation

Le SDK MCP n’applique pas automatiquement les restrictions de roots — vous devez l’implémenter vous-même. Un pattern typique est de créer une fonction helper is_path_allowed() qui :

1. Prend un chemin de fichier demandé
2. Obtient la liste des roots approuvées
3. Vérifie si le chemin demandé est dans l’une de ces roots
4. Retourne True / False pour la permission d’accès

Vous appelez ensuite cette fonction dans tout outil qui accède à des fichiers ou répertoires avant d’effectuer l’opération réelle :

@mcp.tool()
async def read_file(path: str, ctx: Context) -> str:
    # Vérifier que le chemin est dans les roots autorisées
    roots = await ctx.session.list_roots()
    
    if not is_path_allowed(path, roots):
        raise ValueError(f"Accès refusé : {path} n'est pas dans les roots autorisées")
    
    with open(path) as f:
        return f.read()

def is_path_allowed(path: str, roots) -> bool:
    abs_path = Path(path).resolve()
    for root in roots:
        root_path = Path(root.uri.replace("file://", "")).resolve()
        if abs_path.is_relative_to(root_path):
            return True
    return False

Avantages clés

Les roots rendent les serveurs MCP à la fois plus puissants et plus sûrs en donnant à Claude le contexte dont il a besoin pour trouver des fichiers, tout en maintenant des limites claires sur ce à quoi il peut accéder. Un dernier rappel, parce qu’il évite des accidents : la spécification elle-même présente les roots comme une indication fournie par le client, pas comme un contrôle d’accès ; la vérification est à votre charge, et elle doit porter sur des chemins résolus (Path(...).resolve()), jamais sur des chaînes.

À vous de jouer

1. Écrivez is_path_allowed() avec des chemins résolus, et testez-la avec ../ dans le chemin demandé : la traversée est-elle bloquée ?
2. Listez les outils de votre serveur qui touchent au système de fichiers, et ajoutez la vérification à chacun, avant toute opération.
3. Pour un serveur neuf (2026-07-28), réécrivez l’interface sans roots : le dossier autorisé passe-t-il en argument d’outil, en URI de ressource, ou en configuration du serveur ? Justifiez.

Sources officielles : Roots (Claude Academy) · Roots (spécification 2026-07-28, déprécié) · Registre des dépréciations · Sampling and roots (SDK Python v2)

Points clés à retenir

• Les roots donnent au serveur la liste des dossiers accessibles (file:///…) : plus de chemins complets à taper, recherche ciblée, périmètre déclaré par le client.
• Le SDK n’impose rien : is_path_allowed() sur des chemins résolus, appelée avant chaque accès, est à votre charge.
• Déprécié en 2026-07-28 : passer dossiers et fichiers par les paramètres d’outils, les URI de ressources ou la configuration ; résolveur ListRoots() en SDK v2.