Account
IT
Inizia gratis

Aggiungere la ricerca web a Claude Code, Cursor e Codex con un solo server MCP

Un unico server MCP remoto dà a un agente di coding 15 tool: ricerca web, scraping di pagine in markdown, mappe, Amazon, trascrizioni YouTube. Configurazione per tre client, provata.

Un agente di coding che non può leggere il web tira a indovinare le versioni delle librerie e si inventa i flag delle API. La soluzione non è un tool su misura per ogni progetto: è un solo server MCP remoto, aggiunto una volta per client, che l’agente può chiamare per cercare e per leggere pagine.

FastAF ne fa girare uno su https://api.fastaf.co/mcp (Streamable HTTP, stateless, spec 2026-07-28), autenticato con la stessa chiave Bearer dell’API REST. Qui sotto trovi la configurazione per tre client, il protocollo grezzo e quanto costa una sessione. Tutte le chiamate sono state fatte il 19 ottobre 2026.

Cosa riceve l’agente dal server?

tools/list restituisce 15 tool: scrape_page, search_web, search_places, search_amazon, search_news, search_shopping, get_trends, search_scholar, search_jobs, ask_google_ai, search_walmart, search_x, search_youtube, youtube_transcript, get_linkedin_profile. Ognuno è marcato readOnlyHint: true e ha uno schema di input rigoroso con una descrizione su ogni parametro, così il modello sa cosa può passare.

I costi sono quelli del REST: search_web costa 5 crediti, scrape_page 1 (5 con render_js: true), search_amazon e youtube_transcript 1, get_linkedin_profile 60. La lista completa è nelle pagine delle API e nella documentazione MCP.

Prima di tutto metti la chiave in una variabile d’ambiente, così non finisce mai in un file di configurazione che potresti committare:

export FASTAF_API_KEY="..."   # in ~/.zshrc o ~/.bashrc

Come lo aggiungi a Claude Code?

Secondo la documentazione MCP di Claude Code (code.claude.com/docs/en/mcp, verificata il 19 ottobre 2026), i server remoti usano --transport http e un header:

claude mcp add --transport http fastaf https://api.fastaf.co/mcp \
  --header "Authorization: Bearer $FASTAF_API_KEY"

È la tua shell a espandere la variabile, quindi la chiave finisce salvata in ~/.claude.json. Per condividere il server con un team usa un .mcp.json di progetto: Claude Code espande ${VAR} dentro headers, quindi il file non contiene nessun segreto.

{
  "mcpServers": {
    "fastaf": {
      "type": "http",
      "url": "https://api.fastaf.co/mcp",
      "headers": { "Authorization": "Bearer ${FASTAF_API_KEY}" }
    }
  }
}

claude mcp list mostra se si è connesso. Abbiamo usato esattamente questo file con Claude Code 2.1.197 in modalità headless; il modello ha ricevuto il JSON del tool (text, truncated, total_chars, credits_used, credits_remaining).

Come lo aggiungi a Cursor?

La documentazione di Cursor (cursor.com/docs/context/mcp, verificata il 19 ottobre 2026) legge ~/.cursor/mcp.json a livello globale o .cursor/mcp.json per progetto, e risolve ${env:NAME} in url e headers:

{
  "mcpServers": {
    "fastaf": {
      "url": "https://api.fastaf.co/mcp",
      "headers": { "Authorization": "Bearer ${env:FASTAF_API_KEY}" }
    }
  }
}

Per questo articolo non abbiamo provato Cursor: la configurazione segue la sua documentazione.

Come lo aggiungi a Codex CLI?

La documentazione MCP di Codex (developers.openai.com/codex/mcp, verificata il 19 ottobre 2026) usa bearer_token_env_var, che contiene il nome della variabile e non il token. In ~/.codex/config.toml:

[mcp_servers.fastaf]
url = "https://api.fastaf.co/mcp"
bearer_token_env_var = "FASTAF_API_KEY"

Oppure codex mcp add fastaf --url https://api.fastaf.co/mcp --bearer-token-env-var FASTAF_API_KEY (flag presente in codex-cli 0.159.2). Lo vedi con codex mcp list o con /mcp nella TUI. Un’esecuzione di codex exec con questa configurazione ha chiamato search_web e ha restituito tre risultati per 5 crediti.

Com’è fatta una chiamata MCP grezza?

La spec 2026-07-28 è stateless: non c’è handshake, e initialize restituisce -32601 Method not found. Ogni richiesta porta la versione in un header e in _meta, più un header Mcp-Method (senza, il server risponde -32020, header e body non coincidono):

curl -s https://api.fastaf.co/mcp \
  -H "Authorization: Bearer $FASTAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/call" -H "Mcp-Name: search_web" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
       "name":"search_web","arguments":{"query":"python 3.14 free-threaded","results":3},
       "_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28",
                "io.modelcontextprotocol/clientCapabilities":{}}}}'

Output reale, accorciato:

{"results":[
  {"title":"Python support for free threading ...",
   "url":"https://docs.python.org/3/howto/free-threading-python.html","position":1},
  {"title":"Python Free-Threading Guide","url":"https://py-free-threading.github.io/","position":3}],
 "credits_used":5,"credits_remaining":937}

La stessa chiamata con scrape_page su quell’URL e max_chars: 4000 ha restituito "truncated":true,"total_chars":20229,"credits_used":1.

Perché markdown con un tetto e non HTML grezzo?

Il vero budget è il contesto. La pagina “What’s new” di Python 3.14 sono 554.786 byte di HTML scaricati con curl. scrape_page l’ha trasformata in 266.828 caratteri di markdown e ha restituito i primi 12.000 (il max_chars predefinito, regolabile da 1.000 a 30.000), in 1,3 secondi per 1 credito. La guida al free-threading, più piccola, è passata da 41.838 byte di HTML a 20.229 caratteri.

A circa quattro caratteri per token, 12.000 caratteri sono più o meno 3.000 token. La documentazione di Claude Code dice che avvisa sopra i 10.000 token di output di un tool e che per default taglia a 25.000, quindi l’HTML grezzo verrebbe troncato o salvato su file prima che il modello veda qualcosa di utile. truncated e total_chars dicono all’agente che c’è dell’altro, così può richiedere la pagina con un tetto più alto.

Anche i risultati di ricerca sono compatti allo stesso modo: titolo, url, snippet e posizione, nient’altro.

Quanto costa una sessione di coding?

Una sessione di ricerca intensa con 10 ricerche e 10 letture di pagina costa 10 x 5 + 10 x 1 = 60 crediti. I 500 crediti gratuiti ne coprono otto; il pacchetto Starter da $10 (20.000 crediti) ne copre 333, circa 3 centesimi l’una. Vedi i prezzi.

Il tetto rigido è il saldo dell’account. Ogni risultato riporta credits_remaining, e a zero i tool smettono di addebitare e restituiscono un errore. Usa una chiave per macchina, così se perdi un portatile puoi revocare solo la sua chiave, ma ricorda che il saldo è condiviso da tutte le chiavi dell’account: non esistono budget per chiave. L’articolo sul tetto di spesa tratta i limiti per singola esecuzione.

Cosa va storto e come si risolve?

  • HTTP 401, -32001 Authentication required: manca l’header, oppure la variabile è vuota nell’ambiente del client. Le app con interfaccia grafica spesso non leggono il profilo della tua shell.
  • Crediti esauriti (402 sul REST): il tool restituisce INSUFFICIENT_CREDITS con credits_used: 0. Ricarica; non ti è stato addebitato nulla.
  • Troppe chiamate insieme (429 sul REST): i risultati dei tool tornano RATE_LIMITED quando l’agente lancia più chiamate in parallelo della concorrenza del tuo pacchetto (1 su Free, 5 su Starter). La nostra esecuzione con Codex l’ha preso due volte prima di riuscire. Una raffica sull’endpoint stesso restituisce HTTP 429 con Retry-After: 10.

La versione breve

Esporta FASTAF_API_KEY, aggiungi https://api.fastaf.co/mcp con un header Bearer in Claude Code, Cursor o Codex, e l’agente ottiene la ricerca, la lettura delle pagine come markdown con un tetto, e altri 13 tool, con il saldo come soffitto. Prendi una chiave con 500 crediti gratis.