Définir des ressources MCP

Le serveur a des outils ; place à la deuxième primitive. Les ressources dans les serveurs MCP permettent d’exposer des données aux clients, similairement aux gestionnaires de requêtes GET dans un serveur HTTP classique : une adresse, des données en retour, aucun effet de bord. Elles alimenteront la fonctionnalité de mention @ du chatbot — la liste des documents pour l’autocomplétion, leur contenu pour le contexte.

Ressources vs outils

L’analogie GET/POST de la dernière ligne est le meilleur guide de conception : comme un GET, une ressource doit être sûre — la lire ne change rien au système, on peut la relire cent fois sans conséquence. Dès qu’une opération modifie quelque chose, c’est un outil. Cette frontière nette garde votre serveur prévisible pour tous ses clients.

Types de ressources

• Ressources directes : URIs statiques (docs://documents)
• Ressources avec template : URIs avec paramètres (docs://documents/{doc_id})

L’URI directe est une adresse fixe — toujours la même catégorie de données. L’URI à template couvre une famille entière d’adresses avec une seule définition : docs://documents/report.pdf, docs://documents/plan.md, et toute autre valeur du paramètre. Le schéma docs:// est libre — vous inventez le vocabulaire d’adressage qui décrit vos données.

Implémentation

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

# Ressource avec template (récupère un document)
@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 trouvé")
    return docs[doc_id]

Le pattern décorateur vous est familier depuis les outils : la fonction fait le travail, le décorateur déclare l’adresse et le format. Deux détails à noter. La correspondance des noms est stricte : le paramètre de l’URI ({doc_id}) doit porter exactement le nom du paramètre de la fonction — c’est elle qui permet au SDK d’injecter automatiquement la valeur extraite de l’adresse. Et la garde d’entrée reste de rigueur : un identifiant inconnu lève une erreur explicite, que le client recevra en message exploitable plutôt qu’en échec obscur.

Types MIME

Le paramètre mime_type indique aux clients le type de données retourné :

• application/json → données JSON structurées
• text/plain → texte brut

Le SDK Python sérialise automatiquement vos valeurs de retour — la liste de list_docs devient du JSON sans conversion manuelle. Côté client, ce type MIME pilotera le traitement : nous verrons bientôt le client parser le JSON et transmettre le texte brut tel quel, en se fiant uniquement à cette annonce. Déclarer le bon type ici, c’est épargner des devinettes à tous les clients.

Tester dans l’inspecteur

uv run mcp dev mcp_server.py

Dans l’inspecteur, vous verrez les deux sections refléter vos deux types : Resources (statiques) et Resource Templates (paramétriques) — pour ces derniers, l’interface propose de saisir les paramètres avant l’appel. Le rituel habituel s’applique : testez la liste, un document existant, et un doc_id inconnu pour vérifier que l’erreur remonte proprement. Chaque ressource validée ici est une ressource que le client consommera sans surprise — c’est justement l’objet de la prochaine leçon.

Points clés à retenir

• Les ressources sont les GET de MCP : exposer des données, jamais d’effet de bord — les actions restent aux outils
• Directe = adresse fixe ; template = famille d’adresses, paramètres injectés par correspondance de noms
• Le mime_type annonce le format ; le SDK sérialise les retours automatiquement
• Erreurs explicites (ValueError) : le client reçoit un message exploitable
• Validez les deux types dans l’inspecteur — sections Resources et Resource Templates