Définir des ressources MCP

Deuxième primitive MCP après les outils : les ressources. Elles permettent au serveur d’exposer des données aux clients, et l’analogie la plus parlante est celle des endpoints GET d’un serveur HTTP classique : une adresse, des données en retour, aucun effet de bord. C’est leur ligne de partage avec les outils — les ressources sont idéales pour récupérer des informations, jamais pour exécuter des actions. Et comme un GET, elles sont adressées par une URI, dont le schéma est libre : nos documents vivront sous docs://.

Deux types de ressources

Ressources directes

Premier type : les URIs statiques, sans paramètres — une adresse fixe qui renvoie toujours la même catégorie de données.

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

Le décorateur @mcp.resource suit la même philosophie que @mcp.tool : la fonction Python fait le travail, le SDK s’occupe du protocole. Le mime_type annonce au client le format de la réponse — ici du JSON, puisque la fonction retourne une liste d’identifiants que le SDK sérialise. Cette ressource jouera le rôle d’un annuaire : « quels documents existent ? »

Ressources avec template

Second type : les URIs à paramètres, dont des segments sont extraits automatiquement.

@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 {doc_id} non trouve")
    return docs[doc_id]

Une seule définition couvre ici une famille entière d’adresses : docs://documents/report.pdf, docs://documents/plan.md, et ainsi de suite. Le SDK parse l’URI entrante, en extrait les paramètres et les passe comme arguments nommés — avec une exigence stricte : les noms dans l’URI ({doc_id}) doivent correspondre exactement aux noms de paramètres de la fonction. Notez aussi la garde d’entrée : un identifiant inconnu lève une erreur explicite plutôt que de laisser échouer un accès au dictionnaire — le client recevra un message exploitable.

Tester avec l’inspecteur

uv run mcp dev mcp_server.py

L’inspecteur reflète la distinction des deux types : une section Resources liste les ressources statiques, une section Resource Templates les ressources avec template — pour ces dernières, l’interface propose de remplir les paramètres avant d’exécuter la requête. Comme pour les outils, testez les deux chemins : la liste complète, et la récupération d’un document existant comme d’un document inconnu.

Cas d’usage pratique

Ces deux ressources ne sont pas un exercice de style : elles préparent la fonctionnalité de mentions du chatbot. Quand un utilisateur tape @ pour mentionner un document, l’application interroge la ressource directe pour peupler l’autocomplétion — la liste des identifiants disponibles — puis, une fois la mention choisie, la ressource avec template pour récupérer le contenu du document sélectionné et l’injecter dans le contexte de la conversation. Deux requêtes, deux types de ressources, et un rappel de la grille de lecture MCP : c’est l’application qui pilote ces accès, pas Claude — signature caractéristique des ressources.

Points clés à retenir

• Les ressources sont les « GET » de MCP : récupérer des données, sans effet de bord — les actions restent aux outils
• Ressource directe = URI statique ; ressource template = URI à paramètres extraits automatiquement
• Les noms de paramètres de l’URI et de la fonction doivent correspondre exactement
• mime_type annonce le format ; les erreurs explicites (ValueError) donnent au client des messages exploitables
• Cas d’usage type : autocomplétion via la liste, injection de contexte via le template — piloté par l’application