Guide du serveur Gradio MCP : créer, tester, déployer et intégrer

Le Model Context Protocol (MCP) est une norme ouverte pour connecter des modèles d’IA à des outils, API et sources de données externes. Il offre un moyen standardisé pour les grands modèles de langage (LLM) d’interagir avec des systèmes externes. 

À mesure que le monde évolue vers des workflows agentiques, où les systèmes d’IA agissent comme des agents autonomes, apprendre MCP devient essentiel. L’écosystème Gradio offre la façon la plus simple et la plus efficace de créer des serveurs MCP, permettant aux développeurs de bâtir des outils d’IA puissants avec un minimum d’efforts.

Dans ce tutoriel, nous allons :

1. Configurer localement un serveur Gradio MCP simple et le tester.
2. Construire un serveur MCP prêt pour la production avec plusieurs outils.
3. Le déployer sur Hugging Face Spaces.
4. Le tester avec Cursor AI et Claude Desktop.

Si vous souhaitez vous exercer sur Designing Agentic Systems with LangChain, nous vous recommandons notre cours. 

Premiers pas avec Gradio MCP

La dernière version de Gradio (5.32.0) prend désormais en charge MCP nativement, ce qui rend la création et l’exécution de serveurs MCP extrêmement simples. Il suffit d’activer la prise en charge MCP via un argument de code ou une variable d’environnement. 

Les serveurs Gradio MCP utilisent le protocole Server-Sent Events (SSE), qui offre une communication temps réel unidirectionnelle du serveur vers le client — idéal pour le streaming de réponses des LLM.

1. Installez la dernière version de Gradio avec le support MCP.

pip install -U "gradio[mcp]"

2. Créez une application Gradio qui prend en entrée le nom d’une ville et renvoie des données météo (données factices ici). C’est un excellent point de départ, surtout si vous connaissez déjà le framework Gradio.

import gradio as gr


def check_weather(city):
    """
    Simple weather checker function (mock data for demonstration).

    Args:
        city (str): The city name to check weather for

    Returns:
        str: Weather information for the city
    """
    # Mock weather data for demonstration
    weather_data = {
        "london": "Cloudy, 15°C",
        "paris": "Sunny, 22°C",
        "tokyo": "Rainy, 18°C",
        "new york": "Partly cloudy, 20°C",
        "sydney": "Sunny, 25°C",
    }

    city_lower = city.lower().strip()

    if city_lower in weather_data:
        return f"Weather in {city.title()}: {weather_data[city_lower]}"
    else:
        return f"Weather data not available for {city}. Try: London, Paris, Tokyo, New York, or Sydney"


demo = gr.Interface(
    fn=check_weather,
    inputs=[gr.Textbox("London", label="Enter city name")],
    outputs=[gr.Textbox(label="Weather Info")],
    title="Simple Weather Checker",
    description="Enter a city name to check the weather (demo with mock data).",
)

if __name__ == "__main__":
    demo.launch(mcp_server=True)

3. Il existe deux façons d’activer MCP dans Gradio :

• Avec l’argument mcp_server : demo.launch(mcp_server=True)
• Avec une variable d’environnement : export GRADIO_MCP_SERVER=True

4. Enregistrez le fichier Python test.py et exécutez-le. 

$ python test.py                                            
* Running on local URL:  http://127.0.0.1:7860
* To create a public link, set `share=True` in `launch()`.

🔨 MCP server (using SSE) running at: http://127.0.0.1:7860/gradio_api/mcp/sse

Vous verrez deux URL dans la sortie du terminal :

• URL de l’app : http://127.0.0.1:7860 (ouvre l’application Gradio dans votre navigateur).
• URL du serveur MCP : http://127.0.0.1:7860/gradio_api/mcp/sse (utilisée par les clients compatibles MCP).

5. Ouvrez l’URL de l’app (http://127.0.0.1:7860) dans votre navigateur. Saisissez le nom d’une ville (par ex. Tokyo) et consultez la météo.

6. En bas de l’application, cliquez sur le bouton « Use via API or MCP ». Des informations supplémentaires sur l’API de votre app et le serveur MCP s’affichent.

7. Pour tester le serveur MCP avec Cursor AI, ouvrez les paramètres de Cursor, allez à l’onglet « MCP », puis cliquez sur « + Add new global MCP server ».

8. Ajoutez la configuration JSON suivante au fichier de paramètres MCP :

{
  "mcpServers": {
    "gradio": {
      "url": "http://127.0.0.1:7860/gradio_api/mcp/sse"
    }
  }
}

9. Enregistrez le fichier. Vous verrez maintenant un serveur MCP actif nommé gradio avec l’outil check_weather.

Pour tester ce serveur MCP, créez une nouvelle discussion en mode agent dans Cursor (CTRL + T) et demandez la météo à Tokyo. Cursor vous demandera l’autorisation d’exécuter l’outil MCP. Validez.

Le serveur MCP récupère alors les données météo et renvoie le résultat :

Créer un serveur MCP multi-outils avec Gradio

Créons quelque chose de concret et prêt pour la production. Dans ce projet, nous allons construire un serveur MCP multi-outils avec Gradio. 

Le serveur inclura deux outils :

1. Outil météo en direct : récupère la météo en temps réel via l’API Tavily.
2. Outil actualités de la ville : retourne les 5 derniers titres d’actualité sur une ville via l’API Tavily.

Ce serveur aide les utilisateurs à préparer leurs voyages en fournissant à la fois des mises à jour météo et des actualités pertinentes. 

Nous allons configurer le serveur MCP, le tester en local, le déployer sur Hugging Face Spaces, puis tester le serveur déployé avec Cursor AI et Claude Desktop.

1. Configuration

Créez un nouvel Space en vous rendant sur https://huggingface.co/new-space, ajoutez le nom de l’app, une courte description et sélectionnez Gradio comme modèle.

Source : new-space

Une fois créé, vous serez redirigé vers votre nouveau Space. Suivez les instructions fournies pour le configurer.

Clonez le dépôt dans votre répertoire de projet local

git clone https://huggingface.co/spaces/kingabzpro/live-city-mcp

Pour ce projet, nous utiliserons l’API Tavily pour la recherche web. Créez un compte sur Tavily AI et générez une clé d’API.

Source : Tavily AI

Ensuite, enregistrez la clé API comme variable d’environnement sur votre système local

TAVILY_API_KEY="API-KEY"

Après cela, installez le SDK Python de Tavily

pip install tavily-python

2. Création du serveur MCP

Ce serveur MCP comprend deux outils s’appuyant tous deux sur l’API Tavily pour accéder aux informations les plus récentes du web. Le premier outil prend le nom d’une ville et génère un rapport météo détaillé, tandis que le second récupère les titres des cinq principales actualités de la zone. Nous avons créé une interface graphique pour chaque outil, puis les avons combinées via une interface à onglets.

app.py :

import gradio as gr
from tavily import TavilyClient


def get_city_weather_info(city_name):
    """
    Search for current weather information about a city using Tavily search API

    Args:
        city_name (str): Name of the city
        api_key (str): Your Tavily API key

    Returns:
        dict: Search results containing weather information
    """
    # Initialize Tavily client
    client = TavilyClient()

    # Search for current weather information
    search_query = f"current weather in {city_name} temperature humidity conditions"

    try:
        # Perform the search
        response = client.search(
            query=search_query, search_depth="basic", max_results=5
        )

        # Extract relevant information from search results
        weather_info = {"city": city_name, "search_query": search_query, "results": []}

        # Process each search result
        for result in response.get("results", []):
            weather_info["results"].append(
                {
                    "title": result.get("title", ""),
                    "content": result.get("content", ""),
                    "url": result.get("url", ""),
                }
            )

        # Add the answer if available
        if "answer" in response:
            weather_info["summary"] = response["answer"]

        return weather_info

    except Exception as e:
        return {
            "city": city_name,
            "error": f"Failed to fetch weather information: {str(e)}",
        }


def get_city_news(city_name):
    """
    Fetches the top 5 news articles for a given city using the Tavily API.

    Args:
        city_name (str): Name of the city

    Returns:
        dict: News results containing the top 5 articles or an error message
    """
    # Initialize Tavily client
    client = TavilyClient()

    # Search query for news about the city
    search_query = f"Top 5 latest news articles about {city_name}, including major events, politics, economy, and local updates."

    try:
        # Perform the search
        response = client.search(
            query=search_query,
            search_depth="advanced",
            max_results=5,
        )

        # Extract relevant information from search results
        news_info = {"city": city_name, "search_query": search_query, "articles": []}

        # Process each search result
        for result in response.get("results", []):
            news_info["articles"].append(
                {
                    "title": result.get("title", ""),
                    "content": result.get("content", ""),
                    "url": result.get("url", ""),
                }
            )

        # Add the answer if available
        if "answer" in response:
            news_info["summary"] = response["answer"]

        return news_info

    except Exception as e:
        return {"city": city_name, "error": f"Failed to fetch news: {str(e)}"}


# Create Gradio interfaces
weather_demo = gr.Interface(
    fn=get_city_weather_info,
    inputs=gr.Textbox(label="Enter City Name", placeholder="e.g., New York"),
    outputs=gr.JSON(label="Weather Information"),
    description="Get current weather details for a city.",
)

news_demo = gr.Interface(
    fn=get_city_news,
    inputs=gr.Textbox(label="Enter City Name", placeholder="e.g., London"),
    outputs=gr.JSON(label="News Articles"),
    description="Get the latest news articles for a city.",
)

# Create tabbed interface
demo = gr.TabbedInterface(
    [weather_demo, news_demo], ["Weather", "News"], title="City Information Hub"
)

if __name__ == "__main__":
    # Launch without MCP server to avoid initialization issues
    demo.launch(share=False, mcp_server=True, debug=True)

3. Tester le serveur MCP en local

Avant de déployer le serveur MCP, il est essentiel de le tester en local. Démarrez le serveur en exécutant la commande suivante dans le terminal : 

python app.py

Sortie :

* Running on local URL:  http://127.0.0.1:7860
* To create a public link, set `share=True` in `launch()`.

🔨 MCP server (using SSE) running at: http://127.0.0.1:7860/gradio_api/mcp/sse

Ouvrez votre navigateur et allez sur http://127.0.0.1:7860 puis saisissez le nom d’une ville dans le champ de saisie. Le serveur renverra des informations météo détaillées au format JSON.

L’application doit fonctionner sans problème et fournir des données météo et d’actualités fiables pour la ville saisie.

4. Déployer le serveur MCP sur Hugging Face Spaces

Pour déployer le serveur, procédez comme suit :

1. Créez le fichier requirements.txt et ajoutez la dépendance suivante :

tavily-python==0.7.3

2. Validez les modifications puis poussez-les vers le Space Hugging Face.

git add .                                                                                                
live-city-mcp  git commit -m "weather and news MCP"                                                                     
git push  

Une fois poussées, la construction du Space Hugging Face démarre. 

Source : Live City Mcp

Au bout d’environ une minute, le serveur MCP sera en ligne et accessible sur Live City Mcp.

Source : Live City Mcp

3. Avant de l’utiliser comme serveur MCP, nous devons définir la variable d’environnement avec le jeton d’accès Tavily. Pour ce faire, accédez aux paramètres du Space, descendez et cliquez sur le bouton « New Secret ». Ajoutez ensuite la clé API et le nom de l’API Tavily.

Source : live-city-mcp/settings

5. Tester le serveur MCP déployé avec Cursor AI

Notre MCP est déployé et fonctionne correctement. Nous allons maintenant configurer le client MCP. Commencez par paramétrer Cursor AI. Ouvrez les paramètres de Cursor, cliquez sur l’onglet MCP, puis sur « +Add new global MCP server ». Saisissez le code suivant :

{
  "mcpServers": {
    "weather-news": {
      "url": "https://kingabzpro-live-city-mcp.hf.space/gradio_api/mcp/sse"
    }
  }
}

Vous verrez que le MCP weather-news tourne correctement avec deux outils. Posons une question sur la météo à Islamabad. 

Comme on peut le voir, la réponse est rapide et précise.

Nous pouvons vérifier l’exactitude en cherchant en ligne et en consultant la météo sur AccuWeather. 

Source : AccuWeather

Testons ensuite le deuxième outil en demandant les actualités autour d’Islamabad.

Nous obtenons une liste de quatre titres d’actualité sur le Pakistan. Si l’API Tavily ne trouve rien de récent propre à Islamabad, elle bascule sur des actualités au niveau du pays.

6. Tester le serveur MCP déployé avec Claude Desktop

Configurons Claude Desktop en allant dans les paramètres, puis « Developer », et en cliquant sur « Edit Config ». Vous accéderez alors au dossier où modifier le fichier claude_desktop_config.json.

Claude Desktop ne prend pas encore en charge les serveurs MCP basés sur SSE. Dans ce cas, vous pouvez utiliser un outil appelé mcp-remote. 

Pour exécuter mcp-remote, vous devez d’abord installer Node.js en visitant la page Download Node.js®. Ajoutez ensuite le code suivant à votre fichier claude_desktop_config.json :

 "Live City MCP": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://kingabzpro-live-city-mcp.hf.space/gradio_api/mcp/sse",
        "--transport",
        "sse-only"
      ]
    }

Voici un exemple d’ajout de la configuration du serveur MCP.

Lorsque cela est fait, quittez l’application Claude Desktop puis relancez-la. Vous verrez alors un nouvel accès au serveur MCP « Live City MCP », accompagné de deux outils disponibles.

Je voyage bientôt en Irlande, j’ai donc demandé la météo à Dublin et obtenu d’excellents résultats.

La meilleure façon d’accéder au serveur MCP est via Claude Desktop. C’est interactif et cela offre des capacités supplémentaires pour l’usage des outils et une présentation claire des informations.

Conclusion

Si vous savez déjà créer des applications Gradio pour des projets de machine learning, convertir votre application existante en serveur MCP n’a jamais été aussi simple. Avec un seul argument (mcp_server=True), votre app Gradio peut aussi agir comme serveur MCP, pour une intégration fluide avec des outils comme Cursor AI et Claude Desktop. Cela ouvre des perspectives intéressantes pour connecter vos applications d’IA à des systèmes et workflows externes.

Dans ce tutoriel ludique, nous avons découvert les bases de Gradio MCP, appris à créer et tester un serveur MCP, et réalisé un projet concret utilisant l’API Tavily pour récupérer la météo en direct et les actualités d’une ville. À la fin, nous avons déployé le projet sur Hugging Face Spaces et l’avons testé avec des clients compatibles MCP populaires.

Si vous souhaitez approfondir l’IA agentique et les autres notions abordées, nous vous recommandons les ressources ci-dessous :

• Comprendre les agents d’IA : l’avenir des systèmes autonomes
• Claude Code : guide avec exemples pratiques
• Working with Hugging Face | Guide du Hub (cours)
• Build dynamic LangChain agents (cours)
• Chrome DevTools MCP : automatisation et débogage du navigateur par l’IA