Spicrawl werkt nu met OpenAI Agents SDK, LangChain, Codex, Claude Code en meer.Bekijk integraties
Naar inhoud springen

Web scraping in Codex

Voeg de Spicrawl MCP-server toe aan Codex. Het kan dan webpagina's als schone Markdown lezen.

Stel het in

Drie stappen geven Codex de tools, de kennis om Spicrawl-code te schrijven en regels om beide te gebruiken. Of doe alle drie met spicrawl init --client codex.

  1. Stel je API-sleutel in:

    bash
    export SPICRAWL_API_KEY=spicrawl_live_...   # add to your shell profile
  2. Voeg de MCP-server toe. Codex leest de sleutel elke keer dat het verbindt uit SPICRAWL_API_KEY, dus de sleutel komt nooit in een bestand terecht:

    bash
    codex mcp add spicrawl --url https://mcp.spicrawl.com/mcp --bearer-token-env-var SPICRAWL_API_KEY

    Dit schrijft hetzelfde als deze config:

    ~/.codex/config.toml
    [mcp_servers.spicrawl]
    url = "https://mcp.spicrawl.com/mcp"
    bearer_token_env_var = "SPICRAWL_API_KEY"

    Zet de tabel voor één project alleen in .codex/config.toml. Codex leest die alleen in vertrouwde projecten.

  3. Installeer de skill:

    bash
    mkdir -p .agents/skills/spicrawl
    curl -fsSL https://app.spicrawl.com/skill.md -o .agents/skills/spicrawl/SKILL.md
  4. Plak dit gedeelte in AGENTS.md in de projectroot:

    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.
  5. Controleer het met codex mcp list, of /mcp in een sessie. Je zou 25 spicrawl_*-tools moeten zien.

Of gebruik de CLI

Codex werkt in een shell, dus de CLI spicrawl werkt zonder enige configuratie. Hij geeft JSON uit wanneer je hem pipet en eindigt met een stabiele exitcode:

bash
spicrawl scrape https://example.com/pricing --format markdown --max-cost 3 | jq -r .content

Reken in Codex cloud niet op de MCP-server. Gebruik de CLI of gewone HTTP. Stel SPICRAWL_API_KEY in als omgevingsvariabele, niet als secret, en sta api.spicrawl.com toe in de internettoegang van de agent.

Een eerste taak om te proberen

Start codex in het project en vraag:

prompt
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.

Wat het kan

De server geeft de agent 25 spicrawl_*-tools. Elke aanroep draait onder je API-sleutel, met dezelfde limieten en credits als een directe API-aanroep.

  • Lees één pagina: spicrawl_scrape geeft Markdown (de standaard), tekst, HTML, JSON of PDF terug.
  • Lees veel pagina's: spicrawl_batch_submit zet tot 10.000 URL's in de wachtrij. Volg het met spicrawl_batch_status en spicrawl_batch_results.
  • Pagina's achter een login: spicrawl_session_create bewaart cookies en opslag tussen aanroepen.
  • Een fout debuggen: spicrawl_requests_list en spicrawl_request_get.
  • Controleer het gebruik: spicrawl_usage_summary en de andere usage-tools. Die hebben een sleutel met de scope read nodig.
  • Dingen opzoeken: spicrawl_docs_search en spicrawl_docs_read doorzoeken en lezen de Spicrawl-docs.

Eén tool, spicrawl_browser_connect_url, staat in de lijst maar komt binnenkort. Bij spicrawl_scrape is het renderargument render, niet de js_render van de API.

Goed om te weten

  • Geen crawling. Spicrawl volgt geen links en zoekt geen pagina's. Geef de agent de URL's.
  • Credits per verzoek. Een gewone fetch is 1 credit. JavaScript-rendering is 3. Full-browser-rendering is 8.
  • Mislukkingen zijn gratis. Een mislukt verzoek kost 0 credits.
  • De cache bespaart tijd, geen credits. De cache bespaart tijd, geen credits.
  • Begrens elke aanroep. Stel max_cost in, en een verzoek dat meer zou kunnen kosten wordt geweigerd voordat het wordt uitgevoerd.
  • Binnenkort: beheerde proxy's, stealth-modus, een remote browser en AI-extractie op basis van een prompt in gewone taal. Nu kun je je eigen proxy meenemen.

Veelgestelde vragen

Waar slaat Codex de server op?

In ~/.codex/config.toml. Om het in slechts één project te gebruiken, zet je dezelfde tabel in .codex/config.toml. Codex leest projectconfig alleen in vertrouwde projecten.

Kan Codex de CLI gebruiken in plaats van MCP?

Ja. Codex werkt in een shell, dus het kan spicrawl scrape URL --format markdown --max-cost 3 uitvoeren. De CLI print JSON als er wordt gepiped en sluit af met een stabiele code.

Werkt het in Codex cloud?

Reken daar niet op de MCP-server. Gebruik de CLI of gewoon HTTP. Stel SPICRAWL_API_KEY in als omgevingsvariabele (geen secret) en sta api.spicrawl.com toe in de internettoegang van de agent.

Waarom geeft de server 401?

SPICRAWL_API_KEY was niet ingesteld in de shell die codex startte. Exporteer hem en start een nieuwe sessie.

Wat kost elke pagina?

Een gewone fetch kost 1 credit, JavaScript-rendering 3 en volledige browserrendering 8. Mislukte verzoeken kosten 0. Een cachehit kost evenveel als de fetch die hem heeft opgeslagen. Vraag de agent om max_cost bij elk verzoek in te stellen zodat hij nooit meer uitgeeft dan je verwacht.