Crea un tool MCP per dati web live

01Cosa succede quando l'assistente chiede dei dati

• La tua app si connette a https://api.everydata.io/mcp e chiede quali tool sono disponibili – ad esempio amazon_product_by_asin, amazon_search, amazon_reviews, walmart_search, zalando_search, otto_search, youtube_video, youtube_comments e yahoo_quotes.
• Quando una domanda richiede dati live, il modello sceglie un tool e ne compila gli input, come un ASIN o l'ID di un video.
• everydata.io carica la pagina, restituisce i dati e il modello risponde usandoli.
• La tua chiave API accompagna ogni richiesta, quindi ogni chiamata a un tool viene conteggiata nel tuo piano come una normale richiesta API – con gli stessi pesi. Le chiamate che falliscono per causa nostra non vengono addebitate.

Due tool coprono tutto il resto: list_endpoints elenca ogni endpoint di dati con i suoi input e call_endpoint ne chiama uno qualsiasi. account_quota dice al modello quanta quota mensile ti resta. L'elenco completo dei tool è nella documentazione del server MCP.

02Collega Claude Desktop

Il modo più rapido: in Claude Desktop (o su claude.ai) apri Impostazioni → Connettori → Aggiungi connettore personalizzato e inserisci https://api.everydata.io/mcp. Claude ti porta su everydata.io, accedi con il link via e-mail e approvi l'accesso – nessuna chiave da copiare. Preferisci usare una chiave API? Collegati tramite mcp-remote, un piccolo bridge che Claude Desktop avvia sul tuo computer e che inoltra ogni richiesta – con la tua chiave – al server hosted, come mostrato qui sotto.

Apri Impostazioni → Sviluppatore → Modifica configurazione, aggiungi la voce seguente a claude_desktop_config.json, inserisci la tua chiave dopo Bearer e riavvia Claude Desktop.

{
  "mcpServers": {
    "everydata": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.everydata.io/mcp",
        "--header",
        "Authorization:${EVERYDATA_AUTH}"
      ],
      "env": {
        "EVERYDATA_AUTH": "Bearer ds_your_key"
      }
    }
  }
}

La chiave sta in env e l'header non ha spazio dopo i due punti di proposito: Claude Desktop su Windows non passa correttamente gli spazi dentro args, e mcp-remote compila ${EVERYDATA_AUTH} a partire da env. La stessa voce funziona anche su macOS.

Dopo il riavvio, fai una domanda che richiede dati live (vedi il test più sotto) – Claude chiede il permesso di usare un tool everydata. Se non compare nessun tool, Impostazioni → Sviluppatore mostra se il bridge è in esecuzione e il suo ultimo errore. La causa più comune è Node.js mancante (npx non trovato).

03Collega Claude Code

Claude Code comunica direttamente con i server MCP remoti. Un solo comando registra il server con la tua chiave:

export EVERYDATA_KEY="ds_your_key"
claude mcp add --transport http everydata https://api.everydata.io/mcp \
  --header "Authorization: Bearer $EVERYDATA_KEY"

# check that it is connected
claude mcp list

La shell sostituisce $EVERYDATA_KEY quando esegui il comando, e Claude Code salva l'header nelle sue impostazioni. Aggiungi --scope user per usare il server in tutti i progetti, non solo in quello corrente. In Claude Code, /mcp mostra la connessione e i suoi tool.

04Usalo dall'API di OpenAI o di Anthropic

Se costruisci un tuo agente, entrambe le API possono chiamare un server MCP remoto al posto tuo: passi l'indirizzo e la chiave, e il provider elenca i tool, li chiama e consegna i risultati al modello. Non devi scrivere codice per i tool. Entrambi gli esempi leggono la chiave dalla variabile d'ambiente EVERYDATA_KEY.

OpenAI Responses API – un tool mcp con la chiave in headers:

import os

from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-6-astra",
    input="How many views does the Despacito video on YouTube have right now?",
    tools=[{
        "type": "mcp",
        "server_label": "everydata",
        "server_url": "https://api.everydata.io/mcp",
        "headers": {"Authorization": f"Bearer {os.environ['EVERYDATA_KEY']}"},
        "require_approval": "never",
    }],
)
print(resp.output_text)

Anthropic Messages API – il connettore MCP prende il server in mcp_servers, un mcp_toolset corrispondente in tools e l'header beta mcp-client-2025-11-20 (l'SDK lo imposta da betas):

import os

import anthropic

client = anthropic.Anthropic()

resp = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "How many views does the Despacito video on YouTube have right now?"}],
    mcp_servers=[{
        "type": "url",
        "url": "https://api.everydata.io/mcp",
        "name": "everydata",
        "authorization_token": os.environ["EVERYDATA_KEY"],  # sent as "Authorization: Bearer …"
    }],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "everydata"}],
    betas=["mcp-client-2025-11-20"],
)
print(resp.content[-1].text)

Nell'app ChatGPT, aggiungi un connettore personalizzato con l'URL https://api.everydata.io/mcp (l'opzione dipende dal tuo piano ChatGPT). Accederai a everydata.io e approverai l'accesso; puoi revocarlo in qualsiasi momento dalla dashboard, alla voce Chiavi API.

05Provalo: una domanda, una chiamata a un tool

Chiedi al tuo assistente “Quante visualizzazioni ha in questo momento il video di Despacito su YouTube?”. Il modello sceglie youtube_video e invia l'ID del video:

{
  "name": "youtube_video",
  "arguments": { "id": "kJQP7kiw5Fk" }
}

Il tool restituisce la stessa risposta dell'endpoint REST e l'assistente risponde con i numeri attuali. Esempio documentato, abbreviato:

{
  "responseStatus": "PAGE_FOUND",
  "responseMessage": "Page successfully found!",
  "videoId": "kJQP7kiw5Fk",
  "title": "Luis Fonsi - Despacito ft. Daddy Yankee",
  "channelName": "LuisFonsiVEVO",
  "viewCount": 9125159593,
  "likeCount": 56673581,
  "commentCount": 4300000,
  "publishedAt": "2017-01-12T21:00:02-08:00"
}

Questa chiamata conta come una richiesta. Le risposte molto lunghe – tante recensioni o risultati di ricerca – vengono accorciate per il modello, e il tool gli suggerisce di chiedere meno dati, ad esempio una pagina più piccola.

06Quando una chiamata a un tool fallisce

Gli errori tornano al modello come chiamata al tool fallita, con il codice di stato nel testo, così di solito l'assistente riesce a dirti cosa è andato storto.

• 401 – la chiave o l'accesso mancano o sono errati. Verifica che l'header sia Authorization: Bearer ds_… (oppure invia la chiave come x-api-key). Con l'accesso tramite connettore, disconnettiti e ricollegati.
• 429 – troppe richieste contemporanee per il tuo piano. Attendi i secondi indicati nel messaggio e riprova. Un 403 significa che la quota di questo mese è esaurita; account_quota mostra quanto resta.
• 503 o un altro 5xx – al momento il sito non si carica. Queste chiamate non vengono addebitate; riprova semplicemente poco dopo.
• Timeout – una chiamata a un tool ha 50 secondi di tempo. Le pagine lente (molte recensioni, ricerche ampie) possono richiedere di più; la chiamata allora fallisce, non viene addebitata e di solito una richiesta più mirata funziona.

I limiti per piano sono in Limiti e quota.

07Alternativa: esegui un tuo server MCP

Se vuoi decidere esattamente quali endpoint e campi vede il modello, puoi scrivere tu un piccolo server con l'SDK Python ufficiale di MCP (pip install "mcp[cli]>=2" requests, oppure lascia che uv installi entrambi). Ogni tool è una funzione: una richiesta a everydata.io, pochi campi selezionati. La docstring è ciò che il modello legge.

"""A minimal MCP server that gives AI assistants live product and video data from everydata.io."""
import os

import requests
from mcp.server.mcpserver import MCPServer

API = "https://api.everydata.io"
KEY = os.environ["EVERYDATA_API_KEY"]

mcp = MCPServer("everydata")


def _get(path: str, params: dict) -> dict:
    """One everydata.io request. Errors come back as data, so the assistant can explain them."""
    try:
        resp = requests.get(f"{API}{path}", params=params, headers={"x-api-key": KEY}, timeout=60)
    except requests.RequestException as exc:
        return {"error": "network", "detail": str(exc)[:300]}
    if resp.status_code >= 400:  # e.g. 429 = too many requests at once, 5xx = page could not be loaded
        return {"error": resp.status_code, "detail": resp.text[:300]}
    return resp.json()


def _pick(data: dict, keys: tuple) -> dict:
    return data if "error" in data else {k: data.get(k) for k in keys}


@mcp.tool()
def amazon_product(asin: str, domainCode: str = "com") -> dict:
    """Live title, price, list price, availability and rating of an Amazon product.
    asin is the 10-character product ID; domainCode is the marketplace (com, de, co.uk …).
    A price of 0 means the page shows no price right now."""
    data = _get("/amz/amazon-lookup-product-by-asin", {"asin": asin, "domainCode": domainCode})
    return _pick(data, ("productTitle", "asin", "price", "retailPrice", "currency",
                        "productRating", "countReview", "warehouseAvailability"))


@mcp.tool()
def zalando_search(keyword: str, page: int = 1) -> dict:
    """Search the Zalando shop (zalando.de by default) and return up to 10 products with price and link."""
    data = _get("/zal/zalando-search-by-keyword", {"keyword": keyword, "page": page})
    if "error" in data:
        return data
    keep = ("productDescription", "manufacturer", "price", "retailPrice", "currency", "dpUrl")
    return {"results": [{k: p.get(k) for k in keep} for p in data.get("searchProductDetails", [])[:10]]}


@mcp.tool()
def youtube_video(video: str) -> dict:
    """Current view, like and comment counts of a YouTube video. video is the video ID or its URL."""
    data = _get("/ytb/youtube-video-details", {"id": video})
    return _pick(data, ("videoId", "title", "channelName", "viewCount", "likeCount", "commentCount", "publishedAt"))


if __name__ == "__main__":
    mcp.run()  # the assistant app starts this script and talks to it directly

Claude Desktop avvia lo script da solo. Usa percorsi completi (which uv mostra dove si trova uv), perché Claude Desktop non parte dal tuo terminale:

{
  "mcpServers": {
    "everydata-local": {
      "command": "/Users/you/.local/bin/uv",
      "args": ["run", "--with", "mcp[cli]>=2", "--with", "requests",
               "python", "/Users/you/everydata-mcp/server.py"],
      "env": { "EVERYDATA_API_KEY": "ds_your_key" }
    }
  }
}

In Claude Code:

claude mcp add everydata-local --env EVERYDATA_API_KEY=ds_your_key -- uv run --with "mcp[cli]>=2" --with requests python /absolute/path/to/server.py