Risposta rapida
Come aggiungo un web search MCP server a Claude Code o Claude Desktop?
Salva il breve server Python di questa pagina, che espone i tool search_web e read_urls che chiamano LLMWebSearch, poi registralo con claude mcp add o in claude_desktop_config.json, con la tua chiave in env. Il modello può così cercare nel web live e leggere le pagine principali come Markdown. Una ricerca costa 1 credito, a partire da 1,20 USD/1K ricerche a ottobre 2026. Senza KYC; paghi in criptovalute.
Il MCP server in sintesi
| Linguaggio | Python 3.10+, con i package mcp e httpx |
|---|---|
| Trasporto | stdio: il client avvia il server come processo locale |
| Tool 1 | search_web(query, max_results=5, read=3) → fonti numerate con URL e testo della pagina |
| Tool 2 | read_urls(urls) → il contenuto principale da 1 a 20 pagine note |
| Nomi | Non web_search o web_fetch: Claude Code e OpenClaw includono già tool con quei nomi |
| Chiave | Legge da LLMWEBSEARCH_API_KEY nell'environment del server |
| Fatturazione | Un credito paga una ricerca: fino a 20 risultati classificati, con le pagine dei primi 3 lette e restituite come Markdown. Leggere da 4 a 10 pagine costa 2 crediti. Una chiamata che termina in errore non costa nulla. Leggere pagine di cui hai già gli URL costa 1 credito per ogni gruppo iniziato di 3 pagine restituite con contenuto, fino a 20 URL per chiamata; gli URL rifiutati o falliti non vengono contati |
Perché i tool si chiamano search_web e read_urls?
Perché due tool con lo stesso nome confondono il client e il modello. Claude Code e OpenClaw includono ciascuno tool integrati chiamati web_search e web_fetch. Nomi distinti, con descrizioni chiare, permettono al modello di scegliere i nostri di proposito e a te di distinguere le chiamate nei log.
Entrambi i tool restituiscono testo, non JSON grezzo. Ogni fonte inizia con un numero, un titolo e il suo URL, così il modello può citare [1] o [2] e il lettore può verificare la pagina.
import os
import httpx
from mcp.server.fastmcp import FastMCP
BASE = "https://llmwebsearch.com/api/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["LLMWEBSEARCH_API_KEY"]}
mcp = FastMCP("llmwebsearch")
def _call(path: str, body: dict) -> dict:
resp = httpx.post(BASE + path, json=body, headers=HEADERS, timeout=90)
data = resp.json()
if resp.status_code != 200:
err = data.get("error", {})
raise RuntimeError(err.get("code", str(resp.status_code)) + ": " + err.get("message", ""))
return data
def _page(n: int, item: dict) -> str:
head = f"[{n}] {item.get('title') or item['url']}\n{item['url']}\n"
if item.get("content_status") == "ok":
return head + item["content"]
return head + "(not read: " + item.get("content_status", "unknown") + ") " + item.get("snippet", "")
@mcp.tool()
def search_web(query: str, max_results: int = 5, read: int = 3) -> str:
"""Search the live web and return numbered sources; the first `read` pages include their text.
Use it for current facts, documentation and news. Cite sources by their number.
"""
body = {"q": query, "max_results": max(1, min(max_results, 20)), "read": max(0, min(read, 10)), "max_chars": 5000}
data = _call("/search", body)
return "\n\n".join(_page(i, r) for i, r in enumerate(data["results"], start=1))
@mcp.tool()
def read_urls(urls: list[str]) -> str:
"""Read 1 to 20 public web pages whose URLs you already have and return their main text."""
data = _call("/extract", {"urls": urls[:20], "max_chars": 12000})
return "\n\n".join(_page(i, r) for i, r in enumerate(data["results"], start=1))
if __name__ == "__main__":
mcp.run()
Come installo e testo il server?
Crea un virtual environment, installa mcp e httpx e salva il file qui sopra. mcp è l'SDK Python ufficiale del Model Context Protocol; la sua classe FastMCP trasforma funzioni Python tipizzate in tool e usa ogni docstring come descrizione del tool.
Avvia il file una volta da un terminale con la tua chiave impostata. Poi resta in attesa silenziosamente di un client su standard input, il che significa che funziona; fermalo con Ctrl+C. Gli errori dell'API vengono sollevati come errori del tool con il loro codice, così il modello vede rate_limited o insufficient_credits in parole semplici.
python -m venv .venv
. .venv/bin/activate
pip install "mcp[cli]" httpx
LLMWEBSEARCH_API_KEY="your-key" python llmwebsearch_mcp.pyCome lo aggiungo a Claude Code?
Usa claude mcp add. La documentazione di Claude Code indica la forma claude mcp add [options] <name> -- <command> [args...]: prima le sue opzioni, poi un doppio trattino, poi il comando che avvia il server. Le variabili d'ambiente vanno in --env KEY=value, e almeno un'altra opzione, come --transport stdio, deve stare tra --env e il nome del server.
Aggiungi --scope user per rendere il server disponibile in tutti i tuoi progetti; lo scope predefinito, local, copre solo il progetto corrente. Usa percorsi assoluti per il Python del tuo virtual environment e per il file del server.
claude mcp add --env LLMWEBSEARCH_API_KEY=your-key --transport stdio --scope user llmwebsearch \
-- /home/you/llmwebsearch/.venv/bin/python /home/you/llmwebsearch/llmwebsearch_mcp.pyCome lo aggiungo a Claude Desktop e ad altri client?
Claude Desktop legge i server da claude_desktop_config.json, sotto mcpServers. Dai un nome al server, indica il comando, i suoi argomenti e un oggetto env che contiene la chiave, poi riavvia l'app; search_web e read_urls compaiono nell'elenco degli strumenti.
Gli altri client MCP, come Cursor, chiedono le stesse tre cose nelle loro impostazioni MCP: un comando, i suoi argomenti e le variabili d'ambiente. La chiave non compare mai in un argomento di uno strumento né nella conversazione.
{
"mcpServers": {
"llmwebsearch": {
"command": "/home/you/llmwebsearch/.venv/bin/python",
"args": ["/home/you/llmwebsearch/llmwebsearch_mcp.py"],
"env": { "LLMWEBSEARCH_API_KEY": "your-key" }
}
}
}Come mantengo le ricerche economiche e brevi?
Spiega al modello come cercare nelle tue istruzioni: una o due ricerche per domanda, poi leggi di più solo se le fonti sono in disaccordo. Il server limita già ogni pagina a 5.000 caratteri in search_web e a 12.000 in read_urls; abbassa quei numeri per i modelli piccoli.
Ogni chiamata search_web con read fino a 3 costa un credito. Un assistente che esegue 40 ricerche al giorno usa circa 1.200 crediti al mese, quindi 5.000 ricerche (9,25 USD) dura circa quattro mesi. I crediti di ricerca non hanno data di scadenza: quello che non usi questo mese è ancora lì l'anno prossimo.
Cosa vede il modello quando una pagina non può essere letta?
La fonte compare comunque, con il suo numero, titolo e URL, seguiti dal motivo tra parentesi e dallo snippet della ricerca. Il nostro reader rispetta robots.txt: si presenta come LLMWebSearch, segue le regole che un sito scrive per lui o per tutti i robot, e lascia fuori il contenuto di qualsiasi pagina che non gli è permesso leggere. Quando un sito respinge il nostro reader, il risultato torna senza contenuto e con lo status del sito: non risolviamo mai CAPTCHA, non accediamo agli account e non aggiriamo un blocco o un paywall. Il modello può quindi affidarsi alle altre fonti o dire che una pagina non era disponibile.
Server MCP: domande frequenti
Esiste un pacchetto MCP ufficiale di LLMWebSearch o un endpoint ospitato?
No. Il file in questa pagina è l'integrazione: circa 50 righe che puoi leggere e modificare. Gira sulla tua macchina e la tua chiave viaggia solo verso la nostra API.
Devo disattivare la ricerca web integrata di Claude Code?
Non serve. Possono restare entrambe; le descrizioni dicono al modello cosa fa ciascuna. Tieni la nostra quando vuoi il testo della pagina nei risultati, un prezzo fisso per ricerca o un unico posto per i log delle tue ricerche.
Posso usarlo con OpenClaw?
Sì, come server MCP registrato con openclaw mcp add. La pagina di OpenClaw fornisce il comando e spiega come si affianca ai provider di ricerca integrati di OpenClaw.
Il server conserva le mie ricerche?
No. Non trattiene nulla tra una chiamata e l'altra. Dal nostro lato, Non addestriamo alcun modello sulle tue query né su ciò che l'API restituisce, e non aggiungiamo regole nostre contro la conservazione dei risultati; restano validi i diritti dei siti di cui leggi le pagine.
Fonti (1)
- Collegare Claude Code agli strumenti tramite MCP — Claude Code docs (read 2026-10-22)