> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olostep.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Olostep MCP Server

> Fornisci a qualsiasi client AI compatibile con MCP strumenti per web scraping, ricerca, crawling e risposte AI in meno di un minuto

Il server Olostep MCP offre a qualsiasi client AI compatibile con MCP (Claude, Cursor, Windsurf, VS Code, Claude Code, ecc.) 10 strumenti pronti all'uso per il web live — scraping, ricerca, risposte AI con citazioni, lavori batch, crawling del sito e scoperta di URL.

<CardGroup cols={2}>
  <Card title="Scrape & extract" icon="file-lines">
    Estrai markdown, HTML, JSON o testo da qualsiasi URL con rendering JS opzionale
  </Card>

  <Card title="AI answers" icon="sparkles">
    Risposte basate sul web con fonti e output strutturato
  </Card>

  <Card title="Batch & crawl" icon="layer-group">
    Fino a 10k URL in parallelo, o scopri autonomamente un intero sito
  </Card>

  <Card title="Map & search" icon="map">
    Trova ogni URL su un sito, o esegui una ricerca web basata su parser
  </Card>
</CardGroup>

## Prima di iniziare

Hai bisogno di una chiave API Olostep. Ottienila dal [dashboard di Olostep](https://www.olostep.com/dashboard/api-keys) — il livello gratuito copre l'uso personale.

## Scegli un percorso di configurazione

Il percorso più veloce per ogni client è l'**endpoint ospitato** su `https://mcp.olostep.com/mcp`. Nessuna installazione, nessun Node, nessun Docker — basta incollare un URL e la tua chiave API.

Se hai bisogno che funzioni completamente in locale (uso offline, proxy aziendale, air-gapped), ogni client supporta anche un'installazione **local stdio** tramite `npx`. Ogni sezione sottostante mostra entrambi.

<Note>
  **Hosted endpoint** utilizza `Authorization: Bearer YOUR_API_KEY`. **Local stdio** utilizza `OLOSTEP_API_KEY` come variabile d'ambiente. Non confonderli — il modo di autenticazione sbagliato è l'errore numero 1 durante l'onboarding.
</Note>

## Configurazione del client

<Tabs>
  <Tab title="Cursor">
    **Installazione con un clic (consigliata):**

    <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=olostep&config=eyJ1cmwiOiJodHRwczovL21jcC5vbG9zdGVwLmNvbS9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIgWU9VUl9BUElfS0VZIn19">
      <img src="https://cursor.com/deeplink/mcp-install-dark.png" alt="Aggiungi il server Olostep MCP a Cursor" style={{ maxHeight: 32 }} />
    </a>

    Sostituisci `YOUR_API_KEY` nella configurazione risultante con la tua chiave reale.

    **Configurazione manuale:**

    Crea o modifica `.cursor/mcp.json` nella radice del tuo progetto (o `~/.cursor/mcp.json` per globale):

    ```json theme={null}
    {
      "mcpServers": {
        "olostep": {
          "url": "https://mcp.olostep.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Accordion title="Installazione local stdio (opzionale)">
      ```json theme={null}
      {
        "mcpServers": {
          "olostep": {
            "command": "npx",
            "args": ["-y", "olostep-mcp"],
            "env": {
              "OLOSTEP_API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
      ```

      Richiede Node.js 18+ sulla tua macchina.
    </Accordion>

    **Verifica:** Apri Cursor → Impostazioni → MCP. Dovresti vedere `olostep` elencato con **10 strumenti** inclusi `scrape_website`. Se vedi "Connesso, 0 strumenti", la tua chiave API è sbagliata.
  </Tab>

  <Tab title="Claude Code">
    **Installazione CLI (consigliata):**

    ```bash theme={null}
    claude mcp add --transport http olostep https://mcp.olostep.com/mcp \
      --header "Authorization: Bearer YOUR_API_KEY"
    ```

    **Configurazione manuale:**

    Aggiungi alla tua configurazione MCP di Claude Code (`.mcp.json` nella radice del progetto, o `~/.claude.json` globalmente):

    ```json theme={null}
    {
      "mcpServers": {
        "olostep": {
          "url": "https://mcp.olostep.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Accordion title="Installazione local stdio (opzionale)">
      ```bash theme={null}
      claude mcp add --transport stdio --env OLOSTEP_API_KEY=YOUR_API_KEY olostep \
        -- npx -y olostep-mcp
      ```

      Oppure come JSON:

      ```json theme={null}
      {
        "mcpServers": {
          "olostep": {
            "command": "npx",
            "args": ["-y", "olostep-mcp"],
            "env": {
              "OLOSTEP_API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
      ```
    </Accordion>

    **Verifica:** Esegui `/mcp` in Claude Code. Dovresti vedere `olostep` connesso con 10 strumenti.
  </Tab>

  <Tab title="Claude Desktop">
    **Posizione del file di configurazione:**

    | OS      | Percorso                                                          |
    | ------- | ----------------------------------------------------------------- |
    | macOS   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
    | Windows | `%APPDATA%\Claude\claude_desktop_config.json`                     |
    | Linux   | `~/.config/Claude/claude_desktop_config.json`                     |

    **Ospitato (consigliato):**

    ```json theme={null}
    {
      "mcpServers": {
        "olostep": {
          "url": "https://mcp.olostep.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Accordion title="Installazione local stdio (opzionale)">
      ```json theme={null}
      {
        "mcpServers": {
          "olostep": {
            "command": "npx",
            "args": ["-y", "olostep-mcp"],
            "env": {
              "OLOSTEP_API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
      ```

      Oppure installa tramite Smithery:

      ```bash theme={null}
      npx -y @smithery/cli install @olostep/olostep-mcp-server --client claude
      ```
    </Accordion>

    <Warning>
      Claude Desktop deve essere **completamente chiuso e riavviato** affinché le modifiche alla configurazione abbiano effetto — chiudere la finestra non è sufficiente (rimane in esecuzione nella barra dei menu / system tray).
    </Warning>

    **Verifica:** Apri Claude Desktop → cerca l'icona 🔨 (martello) nell'input della chat. Cliccala — dovresti vedere elencati 10 strumenti Olostep.
  </Tab>

  <Tab title="VS Code">
    Il supporto MCP di VS Code è integrato in GitHub Copilot (modalità Agente). Aggiungi questo a `.vscode/mcp.json` nel tuo progetto, o nel tuo `settings.json` utente:

    ```json theme={null}
    {
      "servers": {
        "olostep": {
          "type": "http",
          "url": "https://mcp.olostep.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Accordion title="Installazione local stdio (opzionale)">
      ```json theme={null}
      {
        "servers": {
          "olostep": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "olostep-mcp"],
            "env": {
              "OLOSTEP_API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
      ```
    </Accordion>

    **Verifica:** Apri il pannello chat di Copilot → passa alla modalità Agente → il popover degli strumenti dovrebbe elencare gli strumenti Olostep.
  </Tab>

  <Tab title="Windsurf">
    Aggiungi a `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "olostep": {
          "serverUrl": "https://mcp.olostep.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Accordion title="Installazione local stdio (opzionale)">
      ```json theme={null}
      {
        "mcpServers": {
          "olostep": {
            "command": "npx",
            "args": ["-y", "olostep-mcp"],
            "env": {
              "OLOSTEP_API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
      ```
    </Accordion>

    **Verifica:** Cascade → Impostazioni → MCP. `olostep` dovrebbe apparire con 10 strumenti.
  </Tab>

  <Tab title="Docker">
    Se preferisci eseguire il server in un container (CI, ambiente isolato, nessun Node sull'host):

    ```bash theme={null}
    docker pull olostep/mcp-server

    docker run -i --rm \
      -e OLOSTEP_API_KEY="YOUR_API_KEY" \
      olostep/mcp-server
    ```

    In una configurazione client MCP (stdio):

    ```json theme={null}
    {
      "mcpServers": {
        "olostep": {
          "command": "docker",
          "args": [
            "run", "-i", "--rm",
            "-e", "OLOSTEP_API_KEY=YOUR_API_KEY",
            "olostep/mcp-server"
          ]
        }
      }
    }
    ```

    Supporta `linux/amd64` e `linux/arm64`. Fonte su [GitHub](https://github.com/olostep/olostep-mcp-server).
  </Tab>

  <Tab title="Metorial">
    1. Apri il [dashboard di Metorial](https://metorial.com)
    2. Naviga a **MCP Servers**
    3. Cerca **Olostep**
    4. Clicca **Install** e incolla la tua chiave API

    Per la configurazione manuale:

    ```json theme={null}
    {
      "olostep": {
        "command": "npx",
        "args": ["-y", "olostep-mcp"],
        "env": {
          "OLOSTEP_API_KEY": "YOUR_API_KEY"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Scegliere lo strumento giusto

Il server MCP espone 10 strumenti. Usa questo albero decisionale per scegliere quello giusto — l'agente utilizza lo stesso ragionamento:

| Vuoi...                                           | Usa                                       | Note                                                |
| ------------------------------------------------- | ----------------------------------------- | --------------------------------------------------- |
| Il contenuto di una pagina specifica              | `scrape_website` o `get_webpage_content`  | Imposta `wait_before_scraping=2000–5000` per le SPA |
| Una risposta web in linguaggio naturale con fonti | `answers`                                 | Restituisce sintesi AI + citazioni                  |
| Risultati di ricerca per una query                | `search_web`                              | Basato su parser, non AI, strutturato               |
| Un elenco di URL su un sito                       | `create_map`                              | Solo scoperta URL — NON esegue scraping             |
| URL filtrati per query                            | `get_website_urls`                        | Classificati per rilevanza alla tua `search_query`  |
| Molti URL noti contemporaneamente                 | `batch_scrape_urls` + `get_batch_results` | Asincrono — avvia, poi interroga                    |
| Un intero sito o sezione                          | `create_crawl` + `get_crawl_results`      | Asincrono — segue i link da un URL iniziale         |

<Tip>
  **Scraping di un intero sito?** Usa `create_crawl`, non `batch_scrape_urls`. Crawl scopre E esegue scraping. Batch è per un elenco noto di URL che hai già.
</Tip>

### Dettagli dello strumento

<Accordion title="scrape_website">
  Estrai contenuto da un singolo URL. Supporta `markdown`, `html`, `json`, `text`. Opzionale `country` per richieste geo-mirate, `wait_before_scraping` (0–10000 ms) per siti pesanti in JS, e `parser` (es. `@olostep/amazon-product`) per estrazione strutturata.
</Accordion>

<Accordion title="get_webpage_content">
  Versione leggera solo markdown di `scrape_website`. Usa quando vuoi solo markdown pulito e non hai bisogno di opzioni di formato.
</Accordion>

<Accordion title="search_web">
  Risultati di ricerca web strutturati (basati su parser) per una query. Opzionale `country` per risultati localizzati. Restituisce JSON, non prosa AI.
</Accordion>

<Accordion title="answers">
  Risposta potenziata da AI a un `task` con fonti e citazioni. Passa un argomento `json` per ottenere la risposta in una forma specifica — sia uno schema JSON che una breve descrizione in linguaggio naturale.
</Accordion>

<Accordion title="batch_scrape_urls">
  Scraping asincrono di 2–10k URL che hai già. Restituisce un `batch_id` — poi chiama `get_batch_results` per recuperare il contenuto. Imposta `wait_for_completion_seconds` (fino a 900) se vuoi una singola chiamata bloccante invece di interrogare. Consigliato: 60 per batch sotto i 50 URL, 300–600 per 50–1k, 0 (interroga separatamente) per batch più grandi.
</Accordion>

<Accordion title="get_batch_results">
  Recupera lo stato e il contenuto estratto per un `batch_id`. Restituisce `processing` fino al completamento, poi `completed` con l'array degli elementi.
</Accordion>

<Accordion title="create_crawl">
  Crawl asincrono che segue i link da un `start_url`. Usa `include_url_patterns` / `exclude_url_patterns` (sintassi glob come `/blog/**`) per delimitare. Restituisce un `crawl_id` — poi chiama `get_crawl_results`.
</Accordion>

<Accordion title="get_crawl_results">
  Recupera lo stato e le pagine per un `crawl_id`. Supporta la paginazione tramite `cursor` e `items_limit` (max 100 per chiamata). Restituisce `in_progress` fino al completamento.
</Accordion>

<Accordion title="create_map">
  Ottieni un elenco di URL su un sito. Solo scoperta URL — non esegue scraping. Usa quando vuoi far emergere URL candidati (es. lasciare che l'utente scelga un sottoinsieme). Supporta `include_url_patterns` / `exclude_url_patterns` e `search_query`.
</Accordion>

<Accordion title="get_website_urls">
  Come `create_map`, ma gli URL sono classificati per rilevanza a una `search_query` richiesta. Usa quando vuoi i primi N link corrispondenti su un sito.
</Accordion>

## Risoluzione dei problemi

<Accordion title="Il server appare ma mostra 0 strumenti">
  La tua chiave API è invalida o limitata. Apri il [dashboard delle chiavi API](https://www.olostep.com/dashboard/api-keys) e verifica la chiave. Se usi l'endpoint ospitato, l'intestazione deve essere **esattamente** `Authorization: Bearer sk_...` — senza virgolette intorno al valore, senza spazi extra.
</Accordion>

<Accordion title="`npx: command not found` o `command not found: olostep-mcp`">
  Node.js non è installato (o non è nel tuo PATH). Installa Node 18+ da [nodejs.org](https://nodejs.org/), poi riavvia il tuo terminale **e** il tuo client MCP. Su Windows, passa a un CMD/PowerShell che ha Node nel PATH.
</Accordion>

<Accordion title="Connessione rifiutata o errori DNS su `mcp.olostep.com`">
  Probabilmente sei dietro un proxy aziendale o un firewall che blocca l'host. Passa all'installazione local stdio (`npx -y olostep-mcp`) — effettua richieste in uscita a `api.olostep.com` invece, che di solito è consentito.
</Accordion>

<Accordion title="Configurazione modificata ma l'elenco degli strumenti è obsoleto">
  Il client ha memorizzato nella cache la vecchia configurazione. Chiudi completamente e riavvia — non solo chiudere la finestra. Claude Desktop in particolare continua a funzionare nella barra dei menu / system tray.
</Accordion>

<Accordion title="Errori specifici di Windows con `npx`">
  Se `npx` genera errori avviando il server su Windows, usa la forma avvolta da CMD:

  ```json theme={null}
  {
    "command": "cmd",
    "args": ["/c", "npx", "-y", "olostep-mcp"],
    "env": { "OLOSTEP_API_KEY": "YOUR_API_KEY" }
  }
  ```
</Accordion>

<Accordion title="`401 Missing Authorization: Bearer <OLOSTEP_API_KEY>`">
  Hai colpito l'endpoint ospitato senza un'intestazione di autenticazione (o con il formato sbagliato). Aggiungi l'intestazione alla configurazione del tuo client esattamente come mostrato nella scheda di configurazione.
</Accordion>

## Ricette

Prompt da copiare e incollare che funzionano bene con gli strumenti:

* **Scrape di un elenco di URL di prodotti:** *"Ho un CSV di 200 URL di prodotti Amazon. Esegui uno scraping batch con `parser=@olostep/amazon-product` e restituisci come JSON."*
* **Crawl di un sito di documentazione:** *"Crawl [https://stripe.com/docs](https://stripe.com/docs) con `max_pages=50` e `include_url_patterns=['/docs/**']`. Riassumi ogni sezione come markdown."*
* **Trova concorrenti:** *"Usa `answers` per trovare i primi 5 concorrenti di Notion per siti di documentazione tecnica. Restituisci nome, homepage e posizionamento in una riga."*
* **Mappa poi esegui scraping:** *"Esegui `create_map` su [https://example.com](https://example.com) filtrato su `/blog/**`, poi `batch_scrape_urls` sui primi 20 risultati."*

## Fonte & versioni

* [Repository GitHub](https://github.com/olostep/olostep-mcp-server)
* [Pacchetto npm](https://www.npmjs.com/package/olostep-mcp)
* [Docker Hub](https://hub.docker.com/r/olostep/mcp-server)
* [Registro MCP](https://registry.modelcontextprotocol.io/)