Corso
Sviluppare applicazioni LLM con LangChain
3 ore
52K
Il Model Context Protocol (MCP) è uno standard aperto per collegare i modelli di IA a strumenti esterni, API e fonti di dati. Fornisce un modo standardizzato per i large language model (LLM) di interagire con sistemi esterni.
Man mano che il mondo si muove verso i workflow agentici, in cui i sistemi di IA agiscono come agenti autonomi, imparare MCP è diventato sempre più importante. L’ecosistema Gradio offre il modo più semplice ed efficiente per creare server MCP, consentendo agli sviluppatori di realizzare potenti strumenti di IA con il minimo sforzo.
In questo tutorial, noi:
- Configuriamo in locale un semplice server MCP di Gradio e lo testiamo.
- Creiamo un server MCP pronto per la produzione con più strumenti.
- Lo distribuiamo su Hugging Face Spaces.
- Lo testiamo con Cursor AI e Claude Desktop.
Se vuoi metterti subito all’opera con Designing Agentic Systems with LangChain, ti consiglio di dare un’occhiata al nostro corso.
Prime mosse con Gradio MCP
L’ultima versione di Gradio (5.32.0) supporta nativamente MCP, rendendo semplicissimo creare ed eseguire server MCP. Ti basta abilitare il supporto MCP tramite un semplice argomento di codice o una variabile d’ambiente.
I server MCP di Gradio usano il protocollo Server-Sent Events (SSE), che fornisce una comunicazione in tempo reale e a senso unico dal server al client—perfetta per lo streaming delle risposte degli LLM.
1. Installa l’ultima versione di Gradio con supporto MCP.
pip install -U "gradio[mcp]"2. Crea un’app Gradio che prende il nome di una città in input e restituisce i dati meteo (in questo caso, dati fittizi). È un ottimo punto di partenza, soprattutto se conosci già il 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. Ci sono due modi per abilitare il supporto MCP in Gradio:
- Usando l’argomento
mcp_server:demo.launch(mcp_server=True) - Usando una variabile d’ambiente:
export GRADIO_MCP_SERVER=True
4. Salva il file Python test.py ed eseguilo.
$ 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/sseNel terminale vedrai due URL:
- URL dell’app: http://127.0.0.1:7860 (apre l’app Gradio nel browser).
- URL del server MCP: http://127.0.0.1:7860/gradio_api/mcp/sse (usato dai client compatibili con MCP).
5. Apri l’URL dell’app (http://127.0.0.1:7860) nel browser. Inserisci il nome di una città (ad es., Tokyo) e verifica il meteo.
6. In fondo all’app, clicca sul pulsante "Use via API or MCP". Verranno mostrate informazioni aggiuntive sull’API della tua app e sul server MCP.
7. Per testare il server MCP con Cursor AI, apri le impostazioni di Cursor, vai alla scheda “MCP” e clicca sul pulsante “+ Add new global MCP server”.
8. Aggiungi la seguente configurazione JSON al file delle impostazioni MCP:
{
"mcpServers": {
"gradio": {
"url": "http://127.0.0.1:7860/gradio_api/mcp/sse"
}
}
}9. Salva il file. Ora vedrai un server MCP attivo chiamato gradio con lo strumento check_weather.
Per testare questo server MCP, creeremo una nuova chat in modalità agente di Cursor usando (CTRL +T) e chiederemo il meteo a Tokyo. Cursor chiederà l’autorizzazione per eseguire lo strumento MCP. Approvalo.
Di conseguenza, il server MCP recupererà i dati meteo e restituirà il risultato:
Creare un server MCP multi-strumento con Gradio
Creiamo qualcosa di pratico e pronto per la produzione. In questo progetto costruiremo un server MCP multi-strumento usando Gradio.
Il server includerà due strumenti:
- Strumento meteo live: recupera i dati meteo in tempo reale tramite l’API Tavily.
- Strumento notizie sulla città: recupera le ultime 5 notizie su una città usando l’API Tavily.
Questo server aiuterà chi viaggia a pianificare fornendo sia aggiornamenti meteo che notizie rilevanti.
Imposteremo il server MCP, lo testeremo in locale, lo distribuiremo su Hugging Face Spaces e testeremo il server distribuito con Cursor AI e Claude Desktop.
1. Configurazione
Dobbiamo creare i nuovi Space andando su https://huggingface.co/new-space, aggiungendo il nome dell’app, inserendo una breve descrizione e selezionando Gradio come template.
Fonte: new-space
Una volta creato, verrai reindirizzato al tuo nuovo Space. Segui le istruzioni fornite per configurarlo.
Clona il repository nella directory del tuo progetto locale
git clone https://huggingface.co/spaces/kingabzpro/live-city-mcpPer questo progetto useremo l’API Tavily per le funzionalità di ricerca sul web: crea un account su Tavily AI e genera una chiave API.
Fonte: Tavily AI
Poi salva la chiave API come variabile d’ambiente sul tuo sistema locale
TAVILY_API_KEY="API-KEY"Dopodiché, installa il SDK Python di Tavily
pip install tavily-python2. Creazione del server MCP
Questo server MCP ha due strumenti, entrambi usano l’API Tavily per accedere alle informazioni più recenti dal web. Il primo strumento prende il nome di una città e genera un report meteo dettagliato, mentre il secondo prende il nome della città e elenca i titoli delle prime cinque notizie dell’area. Abbiamo creato un’interfaccia grafica per ciascuno strumento e poi le abbiamo combinate usando una Tabbed Interface.
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. Test del server MCP in locale
Prima di distribuire il server MCP, è essenziale testarlo in locale. Avvia il server eseguendo il seguente comando nel terminale:
python app.pyOutput:
* 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/sseApri il browser e vai su http://127.0.0.1:7860 quindi inserisci il nome di una città nel campo di input. Il server restituirà informazioni meteo dettagliate in formato JSON.
L’applicazione dovrebbe funzionare senza problemi, fornendo dati meteo e notizie accurati per la città inserita.
4. Distribuire il server MCP su Hugging Face Spaces
Per distribuire il server, segui questi passi:
1. Crea il file requirements.txt e aggiungi la seguente dipendenza:
tavily-python==0.7.32. Effettuiamo il commit delle modifiche e poi le pushiamo nello Space di Hugging Face.
git add .
live-city-mcp git commit -m "weather and news MCP"
git push Dopo il push, lo Space di Hugging Face inizierà la build.
Fonte: Live City Mcp
Dopo circa un minuto, il server MCP sarà online e accessibile su Live City Mcp.
Fonte: Live City Mcp
3. Prima di usarlo come server MCP, dobbiamo impostare la variabile d’ambiente con il token di accesso Tavily. Per farlo, vai alle impostazioni dello Space, scorri verso il basso e clicca sul pulsante "New Secret". Poi aggiungi la chiave API e il nome dell’API Tavily.
Fonte: live-city-mcp/settings
5. Test del server MCP distribuito con Cursor AI
Il nostro MCP è distribuito e funziona correttamente. Ora configureremo il client MCP. Per prima cosa configuriamo Cursor AI. Vai alle impostazioni di Cursor, clicca sulla scheda MCP e poi sul pulsante “+Add new global MCP server”. Inserisci il seguente codice:
{
"mcpServers": {
"weather-news": {
"url": "https://kingabzpro-live-city-mcp.hf.space/gradio_api/mcp/sse"
}
}
}Vedrai che il MCP weather-news è in esecuzione con due strumenti. Chiediamo informazioni sul meteo a Islamabad.
Come vedi, ha risposto in modo rapido e accurato.
Possiamo verificarne la correttezza cercando online e controllando il meteo su AccuWeather.
Fonte: AccuWeather
Poi testiamo il secondo strumento chiedendo le notizie su Islamabad.
Come risultato, abbiamo ricevuto un elenco di quattro titoli di notizie sul Pakistan. Se l’API Tavily non trova nulla di recente su Islamabad, passerà alle notizie a livello nazionale.
6. Test del server MCP distribuito con Claude Desktop
Configuriamo Claude Desktop andando nelle impostazioni, cliccando su “Developer” e poi su “Edit Config”. Verrai portato nella cartella in cui devi modificare il file claude_desktop_config.json.
Claude Desktop al momento non supporta i server MCP basati su SSE. In questi casi, puoi usare uno strumento chiamato mcp-remote.
Per eseguire mcp-remote, devi prima installare Node.js visitando la pagina Download Node.js®. Poi aggiungi il seguente codice al tuo file 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"
]
}Ecco un esempio di aggiunta della configurazione del server MCP.
Una volta completato, esci dall’applicazione Claude Desktop e riavviala. Vedrai l’accesso al nuovo server MCP chiamato “Live City MCP”, che include due strumenti disponibili.
Sto per viaggiare in Irlanda, quindi ho chiesto il meteo a Dublino e ho ottenuto ottimi risultati.
Il modo migliore per accedere al server MCP è tramite Claude Desktop. È interattivo e offre funzionalità extra per l’uso degli strumenti e per mostrare le informazioni in modo chiaro.
Conclusione
Se hai già familiarità con la creazione di applicazioni Gradio per progetti di machine learning, convertire la tua app esistente in un server MCP non è mai stato così facile. Con un solo argomento (mcp_server=True), la tua app Gradio può funzionare anche come server MCP, abilitando un’integrazione senza soluzione di continuità con strumenti come Cursor AI e Claude Desktop. Questo apre possibilità interessanti per collegare le tue applicazioni di IA a sistemi e workflow esterni.
In questo tutorial divertente abbiamo esplorato le basi di Gradio MCP, imparato a creare e testare un server MCP e realizzato un progetto pratico usando l’API Tavily per ottenere dati meteo live e notizie sulla città. Alla fine, abbiamo distribuito il progetto su Hugging Face Spaces e lo abbiamo testato con popolari client compatibili con MCP.
Se vuoi approfondire l’IA agentica e gli altri concetti trattati in questo tutorial, ti consiglio le risorse qui sotto:
