Serveur MCP Shamela avec Python, LangChain et agents

Vous pouvez appeler le serveur depuis votre propre code, pas seulement depuis une application de chat. Le point d’accès est un serveur MCP distant standard en HTTP streamable : toute bibliothèque cliente qui parle ce transport fonctionne :

https://qurangallery.com/mcp/shamela

Ni compte ni clé ne sont nécessaires pour l’essayer. Sans clé, vous avez les limites sans clé (10 requêtes par minute, 200 par jour, par adresse IP) ; avec une clé gratuite, vous avez 60 par minute. Voir Limites et erreurs.

Cette page contient les recettes qui ont été exécutées sur le point d’accès en ligne le 1er novembre 2026, avec les versions des paquets sur lesquelles elles ont tourné. Les recettes qui n’ont pas été exécutées ne figurent pas sur cette page.

Python 3.12.8 a été utilisé. Les deux bibliothèques ont listé 14 outils sur ce point d’accès, le même ensemble que celui décrit dans l’ensemble complet des outils. Depuis cette exécution, shamela_verify_quote a été ajouté : le point d’accès liste désormais 15 outils ; les sorties ci-dessous viennent de cette exécution.

Se connecter avec LangChain

langchain-mcp-adapters transforme chaque outil MCP en outil LangChain. Installez-le, puis pointez-le vers l’URL avec le transport http (HTTP streamable) :

pip install langchain-mcp-adapters

import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient


async def main():
    client = MultiServerMCPClient(
        {
            "shamela": {
                "transport": "http",
                "url": "https://qurangallery.com/mcp/shamela",
            }
        }
    )
    tools = await client.get_tools()
    print(len(tools), "tools")


asyncio.run(main())

La sortie lors de l’exécution était 14 tools.

Se connecter avec LlamaIndex

pip install llama-index-tools-mcp

import asyncio
from llama_index.tools.mcp import BasicMCPClient, McpToolSpec


async def main():
    client = BasicMCPClient("https://qurangallery.com/mcp/shamela")
    spec = McpToolSpec(client=client)
    tools = await spec.to_tool_list_async()
    print(len(tools), "tools")


asyncio.run(main())

La sortie lors de l’exécution était 14 tools. La liste d’outils alimente un agent LlamaIndex comme n’importe quelle autre liste d’outils.

Appeler un outil et lire la citation

Ce script appelle shamela_search_library et affiche le livre, le volume et la page imprimés, et l’endroit où les mots ont été trouvés. Il n’a besoin ni d’un modèle ni d’une clé de modèle : c’est donc le moyen le plus rapide de vérifier votre installation.

import asyncio
import json
from langchain_mcp_adapters.client import MultiServerMCPClient


async def main():
    client = MultiServerMCPClient(
        {
            "shamela": {
                "transport": "http",
                "url": "https://qurangallery.com/mcp/shamela",
            }
        }
    )
    tools = {t.name: t for t in await client.get_tools()}
    blocks = await tools["shamela_search_library"].ainvoke(
        {"query": "إنما الأعمال بالنيات", "scope": "hadith-primary", "limit": 3}
    )
    result = json.loads(blocks[0]["text"])
    for p in result["passages"]:
        print(p["book"], p["printedPage"], p["matchedIn"])


asyncio.run(main())

Sortie lors de l’exécution :

سنن ابن ماجه - ت الأرنؤوط 5/ 305 body
صحيح البخاري - ط السلطانية 1/ 6 body
سنن أبي داود - ت الأرنؤوط 3/ 526 footnote

Trois points à remarquer, chacun expliqué dans Lire un résultat :

• printedPage est le volume et la page dans cette impression, par exemple 5/ 305.
• matchedIn vaut body, footnote, both ou unknown. La troisième ligne ci-dessus correspond à une note de bas de page, qui est une note d’éditeur et non le texte de l’auteur. Voir Texte principal ou notes.
• scope est obligatoire. Voir Choisir une portée.

La requête doit être en arabe ; une requête sans mot arabe est une erreur d’outil qui demande à l’appelant de la traduire. Lorsque vous donnez ces outils à un modèle, le modèle fait cette traduction avant d’appeler.

Passer une clé

Une clé fait passer la limite de 10 à 60 requêtes par minute. Créez-en une gratuite sur accounts.qurangallery.com/developers, gardez-la dans une variable d’environnement et envoyez-la comme jeton bearer dans les headers de la connexion. Ne mettez jamais une vraie clé dans le code source.

import os

connection = {
    "transport": "http",
    "url": "https://qurangallery.com/mcp/shamela",
    "headers": {"Authorization": f"Bearer {os.environ['QG_API_KEY']}"},
}

Utilisez connection comme valeur sous "shamela" dans MultiServerMCPClient. Le BasicMCPClient de LlamaIndex a un argument headers pour le même en-tête :

client = BasicMCPClient(
    "https://qurangallery.com/mcp/shamela",
    headers={"Authorization": f"Bearer {os.environ['QG_API_KEY']}"},
)

Une clé envoyée est vérifiée. Une clé invalide reçoit un 401 au lieu de retomber sur le régime sans clé : une faute de frappe se voit donc tout de suite. Lors de l’exécution avec une fausse clé volontairement invalide, la connexion a échoué. Il n’a pas été exécuté avec une clé valide. La configuration complète, y compris les clients qui prennent une clé dans un fichier de configuration, est dans Configuration du jeton bearer.

Non couvert ici

L’outil MCP distant de l’API Responses d’OpenAI et le connecteur MCP de l’API Messages d’Anthropic peuvent aussi appeler un serveur MCP distant par URL. Ils nécessitent un compte de modèle pour s’exécuter, n’ont pas été exécutés pour cette page et ne sont donc pas décrits. Pour eux, utilisez l’URL du point d’accès ci-dessus et la documentation propre au client.

Voir aussi

• Connecter n’importe quel client MCP
• Limites et erreurs
• Construire plutôt son propre corpus