Web scraping in Codex
Aggiungi il server MCP di Spicrawl a Codex. Potrà così leggere le pagine web come Markdown pulito.
Configuralo
Tre passaggi danno a Codex gli strumenti, il know-how per scrivere codice Spicrawl e le regole per usarli entrambi. Oppure fai tutti e tre con spicrawl init --client codex.
Imposta la tua chiave API:
bashexport SPICRAWL_API_KEY=spicrawl_live_... # add to your shell profileAggiungi il server MCP. Codex legge la chiave da
SPICRAWL_API_KEYa ogni connessione, quindi la chiave non finisce mai in un file:bashcodex mcp add spicrawl --url https://mcp.spicrawl.com/mcp --bearer-token-env-var SPICRAWL_API_KEYQuesto scrive la stessa cosa di questa configurazione:
~/.codex/config.toml[mcp_servers.spicrawl] url = "https://mcp.spicrawl.com/mcp" bearer_token_env_var = "SPICRAWL_API_KEY"Per un solo progetto, metti la tabella in
.codex/config.toml. Codex la legge solo nei progetti attendibili.Installa la skill:
bashmkdir -p .agents/skills/spicrawl curl -fsSL https://app.spicrawl.com/skill.md -o .agents/skills/spicrawl/SKILL.mdIncolla questa sezione in
AGENTS.mdnella radice del progetto:AGENTS.md## Web data (Spicrawl) Use Spicrawl to read web pages: the spicrawl_* MCP tools, the `spicrawl` CLI, or POST https://api.spicrawl.com/v1/scrape with `Authorization: Bearer $SPICRAWL_API_KEY` in code. Docs: https://docs.spicrawl.com/llms.txt (append .md to any page URL for Markdown). - Ask for markdown: `response_format: "markdown"` (API default is html); on spicrawl_scrape, `format: "markdown"`. - Check the site's status, not only the HTTP status: `X-Target-Status` header, or `status` in the JSON envelope (spicrawl_scrape with `format: "json"`). 200 is the page; 404/410 mean it does not exist; 403/429/503 mean the site refused, so escalate. - On an error, switch on `code`. Retry only when `retryable` is true, after `retry_after_seconds`. Read `diagnostics.hint` and change what it names first. Never retry ERR::REQUEST::*, ERR::AUTH::* or ERR::LIMIT::QUOTA_EXCEEDED. - Escalate one step at a time and stop at the first that works: plain fetch (1 credit) -> `js_render: true` (3) -> add the user's own `proxy` if they have one. Empty or skeleton content means render; ERR::UPSTREAM::CHALLENGE or a 403 target status means retry once, then the user's own proxy. - Set `max_cost` on every request to the price of the step you intend. - Keep the cache on (default). Set `cache: false` only for prices, stock or other live data. - Trim tokens with `main_content_only` (on by default for markdown), `include_tags`, `exclude_tags`. - For more than 20 URLs, use a batch job (spicrawl_batch_submit / POST /v1/batch). Batch items return html, markdown or text (spicrawl_batch_submit defaults to markdown, POST /v1/batch to html). Extraction, screenshots, actions and sessions are refused with a 400 before anything is charged: scrape those URLs one by one. - With the CLI, read stdout as JSON and branch on the exit code: 3 auth, 4 bad request, 5 limit, 6 site refused or failed, 7 proxy, 8 engine or extraction, 10 network. - Never print or commit SPICRAWL_API_KEY. Log `X-Request-Id` for failures.Verificalo con
codex mcp list, oppure/mcpin una sessione. Dovresti vedere 25 strumentispicrawl_*.
Oppure usa la CLI
Codex lavora in una shell, quindi la CLI spicrawl funziona senza alcuna configurazione. Stampa JSON quando viene collegata in pipe e termina con un codice stabile:
spicrawl scrape https://example.com/pricing --format markdown --max-cost 3 | jq -r .contentIn Codex cloud non contare sul server MCP. Usa la CLI o semplice HTTP. Imposta SPICRAWL_API_KEY come variabile d’ambiente, non come secret, e consenti api.spicrawl.com nell’accesso a internet dell’agente.
Un primo task da provare
Avvia codex nel progetto e chiedi:
Use Spicrawl to read https://example.com/pricing as markdown. List each plan with its monthly price.
If the page comes back empty, retry with rendering.Cosa può fare
Il server offre all’agente 25 strumenti spicrawl_*. Ogni chiamata viene eseguita con la tua chiave API, con gli stessi limiti e crediti di una chiamata diretta all’API.
- Leggi una pagina:
spicrawl_scraperestituisce Markdown (predefinito), testo, HTML, JSON o PDF. - Leggi molte pagine:
spicrawl_batch_submitmette in coda fino a 10.000 URL. Poi usaspicrawl_batch_statusespicrawl_batch_results. - Pagine dietro un login:
spicrawl_session_createmantiene cookie e storage tra una chiamata e l’altra. - Fai il debug di un errore:
spicrawl_requests_listespicrawl_request_get. - Controlla l’utilizzo:
spicrawl_usage_summarye gli altri strumenti di utilizzo. Richiedono una chiave con lo scoperead. - Cerca informazioni:
spicrawl_docs_searchespicrawl_docs_readcercano e leggono nella documentazione di Spicrawl.
Uno strumento, spicrawl_browser_connect_url, è elencato ma in arrivo. Su spicrawl_scrape, l’argomento di rendering è render, non js_render come nell’API.
Da sapere
- Nessun crawling. Spicrawl non segue link né trova pagine. Dai all’agente gli URL.
- Crediti per richiesta. Un fetch semplice costa 1 credito. Il rendering JavaScript 3. Il rendering con browser completo 8.
- I fallimenti sono gratuiti. Una richiesta fallita costa 0 crediti.
- La cache fa risparmiare tempo, non crediti. La cache fa risparmiare tempo, non crediti.
- Limita ogni chiamata. Imposta
max_cost, e una richiesta che potrebbe costare di più viene rifiutata prima di essere eseguita. - In arrivo: proxy gestiti, modalità stealth, un browser remoto ed estrazione con AI da un prompt in linguaggio naturale. Oggi puoi usare il tuo proxy.
Domande frequenti
Dove salva il server Codex?
In ~/.codex/config.toml. Per usarlo in un solo progetto, metti la stessa tabella in .codex/config.toml. Codex legge la configurazione di progetto solo nei progetti attendibili.
Codex può usare la CLI al posto di MCP?
Sì. Codex lavora in una shell, quindi può eseguire spicrawl scrape URL --format markdown --max-cost 3. La CLI stampa JSON quando è in pipe e termina con un codice stabile.
Funziona nel cloud di Codex?
Non contare sul server MCP lì. Usa la CLI o semplice HTTP. Imposta SPICRAWL_API_KEY come variabile d’ambiente (non come segreto) e consenti api.spicrawl.com nell’accesso a internet dell’agente.
Perché il server restituisce 401?
SPICRAWL_API_KEY non era impostata nella shell che ha avviato codex. Esportala e avvia una nuova sessione.
Quanto costa ogni pagina?
Un fetch semplice costa 1 credito, il rendering JavaScript 3 e il rendering con browser completo 8. Le richieste fallite costano 0. Un cache hit costa quanto il fetch che l’ha salvato. Chiedi all’agente di impostare max_cost su ogni richiesta così non spende mai più del previsto.