Définir des ressources

Les ressources constituent la deuxième primitive du protocole. Elles permettent à un serveur MCP d’exposer des données aux clients, de façon comparable aux handlers GET d’un serveur HTTP classique : on demande quelque chose par son adresse, on reçoit un contenu, et rien n’est modifié au passage. Cette parenté n’est pas qu’une image pédagogique — elle indique le bon terrain d’emploi des ressources, à savoir les scénarios où vous avez besoin de récupérer des informations plutôt que d’effectuer des actions.

Le besoin concret derrière la primitive

Prenons un cas que vous avez déjà vu dans d’autres interfaces. Vous voulez construire une fonctionnalité de mention de documents, où l’utilisateur tape @nom_du_document pour référencer un fichier. Cette petite fonctionnalité demande en réalité deux opérations distinctes : obtenir la liste de tous les documents disponibles, afin d’alimenter l’autocomplétion pendant la frappe, puis récupérer le contenu d’un document précis une fois qu’il a été mentionné.

Le point décisif se joue à la seconde opération. Quand un utilisateur mentionne un document, votre système injecte automatiquement son contenu dans le prompt envoyé à Claude — sans que Claude ait besoin d’utiliser des outils pour récupérer l’information. Le modèle reçoit le texte déjà présent dans sa fenêtre de contexte, comme si l’utilisateur l’avait collé lui-même.

Mécaniquement, les ressources suivent un modèle requête-réponse familier. Quand votre client a besoin de données, il envoie une ReadResourceRequest accompagnée d’un URI qui identifie la ressource souhaitée ; le serveur MCP traite cette requête et retourne les données dans un ReadResourceResult. Vous reconnaissez la convention de nommage croisée dans la première partie du cours.

Ressources directes et ressources avec templates

Les ressources directes ont des URIs statiques qui ne changent jamais. Elles conviennent aux opérations sans paramètres, typiquement celle qui répond à la question « qu’est-ce qui existe ? » :

@mcp.resource(
    "docs://documents",
    mime_type="application/json"
)
def list_docs() -> list[str]:
    return list(docs.keys())

Cette ressource répond à l’URI docs://documents et retourne la liste des identifiants, exactement ce dont l’autocomplétion a besoin. Les ressources avec templates, elles, incluent des paramètres dans leurs URIs. Le SDK Python analyse automatiquement ces paramètres et les passe comme arguments mot-clé à votre fonction, ce qui vous évite tout travail de parsing :

@mcp.resource(
    "docs://documents/{doc_id}",
    mime_type="text/plain"
)
def fetch_doc(doc_id: str) -> str:
    if doc_id not in docs:
        raise ValueError(f"Document avec l'id {doc_id} introuvable")
    return docs[doc_id]

Le segment {doc_id} de l’URI devient le paramètre doc_id de la fonction. Notez que le contrôle d’existence est traité de la même façon que dans les outils : une ValueError explicite plutôt qu’un retour silencieux.

Déclarer le type de contenu

Les ressources peuvent retourner n’importe quel type de données. Le paramètre mime_type sert à indiquer aux clients à quoi s’attendre, et donc comment interpréter ce qu’ils reçoivent.

Le SDK MCP Python sérialise automatiquement vos valeurs de retour. Dans l’exemple list_docs, vous retournez une liste Python et non une chaîne JSON : il n’y a aucune conversion manuelle à écrire, il suffit de retourner la structure de données et de laisser le SDK s’en occuper.

Tester ce que vous venez d’écrire

L’inspecteur reste votre boucle de vérification la plus courte :

uv run mcp dev mcp_server.py

Une fois connecté depuis le navigateur, vous constaterez que l’inspecteur distingue deux zones : Resources liste vos ressources directes ou statiques, tandis que Resource Templates liste vos ressources paramétrées. Cliquez sur l’une d’elles pour la tester ; pour une ressource avec template, l’inspecteur vous demandera d’abord une valeur pour chaque paramètre de l’URI, ici un doc_id.

Ce qui distingue une ressource d’un outil

Le tableau suivant résume les quatre différences à garder en tête au moment de choisir la primitive adaptée.

Les ressources offrent donc un moyen propre d’exposer des données en lecture seule depuis votre serveur MCP, et rendent la récupération d’informations plus simple qu’un appel d’outil. Reste à les consommer côté client : c’est l’objet de la leçon suivante.