Web scraping dans Codex
Ajoutez le serveur MCP Spicrawl à Codex. Il peut alors lire des pages web en Markdown propre.
Configurez-le
Trois étapes donnent à Codex les outils, le savoir-faire pour écrire du code Spicrawl et des règles pour utiliser les deux. Ou faites les trois d’un coup avec spicrawl init --client codex.
Définissez votre clé API :
bashexport SPICRAWL_API_KEY=spicrawl_live_... # add to your shell profileAjoutez le serveur MCP. Codex lit la clé dans
SPICRAWL_API_KEYà chaque connexion, donc la clé n’atterrit jamais dans un fichier :bashcodex mcp add spicrawl --url https://mcp.spicrawl.com/mcp --bearer-token-env-var SPICRAWL_API_KEYCela écrit la même chose que cette config :
~/.codex/config.toml[mcp_servers.spicrawl] url = "https://mcp.spicrawl.com/mcp" bearer_token_env_var = "SPICRAWL_API_KEY"Pour un seul projet, placez la table dans
.codex/config.toml. Codex ne la lit que dans les projets de confiance.Installez la skill :
bashmkdir -p .agents/skills/spicrawl curl -fsSL https://app.spicrawl.com/skill.md -o .agents/skills/spicrawl/SKILL.mdCollez cette section dans
AGENTS.mdà la racine du projet :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.Vérifiez avec
codex mcp list, ou/mcpdans une session. Vous devriez voir 25 outilsspicrawl_*.
Ou utilisez la CLI
Codex fonctionne dans un shell, donc la CLI spicrawl fonctionne sans aucune configuration. Elle affiche du JSON lorsqu’elle est redirigée dans un pipe et se termine avec un code stable :
spicrawl scrape https://example.com/pricing --format markdown --max-cost 3 | jq -r .contentDans Codex cloud, ne comptez pas sur le serveur MCP. Utilisez la CLI ou du HTTP simple. Définissez SPICRAWL_API_KEY comme variable d’environnement, et non comme secret, et autorisez api.spicrawl.com dans l’accès internet de l’agent.
Une première tâche à essayer
Lancez codex dans le projet et demandez :
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.Ce qu’il peut faire
Le serveur donne à l’agent 25 outils spicrawl_*. Chaque appel s’exécute sous votre clé API, avec les mêmes limites et les mêmes crédits qu’un appel direct à l’API.
- Lire une page :
spicrawl_scraperenvoie du Markdown (par défaut), du texte, du HTML, du JSON ou un PDF. - Lire plusieurs pages :
spicrawl_batch_submitmet en file jusqu’à 10 000 URL. Suivez-le avecspicrawl_batch_statusetspicrawl_batch_results. - Pages derrière une connexion :
spicrawl_session_createconserve les cookies et le stockage d’un appel à l’autre. - Déboguer un échec :
spicrawl_requests_listetspicrawl_request_get. - Vérifier l’usage :
spicrawl_usage_summaryet les autres outils d’utilisation. Ils nécessitent une clé avec le scoperead. - Rechercher des informations :
spicrawl_docs_searchetspicrawl_docs_readcherchent et lisent la documentation de Spicrawl.
Un outil, spicrawl_browser_connect_url, est listé mais arrive bientôt. Sur spicrawl_scrape, l’argument de rendu est render, et non le js_render de l’API.
Bon à savoir
- Pas de crawl. Spicrawl ne suit pas les liens et ne trouve pas de pages. Donnez les URL à l’agent.
- Crédits par requête. Une récupération simple coûte 1 crédit. Le rendu JavaScript coûte 3. Le rendu navigateur complet coûte 8.
- Les échecs sont gratuits. Une requête échouée coûte 0 crédit.
- Le cache fait gagner du temps, pas des crédits. Un résultat en cache coûte autant que la récupération qui l’a stocké.
- Plafonnez chaque appel. Définissez
max_cost, et une requête qui pourrait coûter plus cher est refusée avant d’être exécutée. - Bientôt disponible : proxys gérés, mode furtif, navigateur distant et extraction par IA à partir d’un prompt en langage naturel. Aujourd’hui, vous pouvez apporter votre propre proxy.
Questions fréquentes
Où Codex stocke-t-il le serveur ?
Dans ~/.codex/config.toml. Pour l’utiliser dans un seul projet, placez le même tableau dans .codex/config.toml. Codex ne lit la config de projet que dans les projets de confiance.
Codex peut-il utiliser la CLI au lieu de MCP ?
Oui. Codex fonctionne dans un shell, donc il peut exécuter spicrawl scrape URL --format markdown --max-cost 3. La CLI affiche du JSON lorsqu’elle est redirigée et se termine avec un code stable.
Cela fonctionne-t-il dans Codex cloud ?
Ne comptez pas sur le serveur MCP là-bas. Utilisez la CLI ou du HTTP simple. Définissez SPICRAWL_API_KEY comme variable d’environnement (et non comme secret) et autorisez api.spicrawl.com dans l’accès internet de l’agent.
Pourquoi le serveur renvoie-t-il 401 ?
SPICRAWL_API_KEY n’était pas défini dans le shell qui a lancé codex. Exportez-le et démarrez une nouvelle session.
Combien coûte chaque page ?
Une récupération simple coûte 1 crédit, le rendu JavaScript 3 et le rendu navigateur complet 8. Les requêtes échouées coûtent 0. Un résultat en cache coûte autant que la récupération qui l’a stocké. Demandez à l’agent de définir max_cost sur chaque requête pour qu’il ne dépense jamais plus que prévu.