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

# Collegare l'MCP di Data Hub al tuo agente

> Collega l'MCP di Data Hub senza scegliere prima un'app e lascia che l'agente cerchi ed esegua la capacità giusta per ogni attività.

Usa questo tutorial se non sai ancora quale Data App usare, o se vuoi che l'agente trovi da solo una capacità per ogni attività. La connessione generale aggiunge al tuo agente gli strumenti di scoperta ed esecuzione di Data Hub. Una volta connesso, descrivi i dati di cui hai bisogno e l'agente cerca una Data App adatta, ne verifica i parametri, poi conferma e la esegue.

<Note>
  **La connessione generale non richiede di scegliere prima un'app.** Questo tutorial e i tutorial «Codex: collegare un'app specifica» e «Claude Code: collegare un'app specifica» sono due modalità d'uso diverse. Una connessione ad app specifica si adatta a una capacità chiara, fissa e di lungo periodo. La connessione generale si adatta a esigenze che cambiano o ai casi in cui l'app non è ancora stata scelta.
</Note>

## Comprendere i due metodi di connessione

| Metodo                           | Ordine delle operazioni                                                                                                      | Ideale per                                                                                                              |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Connessione generale**         | Collegare l'MCP di Data Hub → cercare le app dentro l'agente → verificare i dettagli → scegliere ed eseguire                 | Non sai quale app scegliere; ogni attività può richiedere una capacità diversa; vuoi che l'agente aiuti nella scoperta. |
| **Connessione ad app specifica** | Scegliere un'app nel catalogo → copiare il prompt di installazione di quell'app → collegare l'agente → eseguire direttamente | Hai un'app fissa; vuoi un ambito di strumenti più ristretto; gestisci un processo aziendale stabile e ripetuto.         |

Entrambi i metodi richiamano le stesse Data App su Data Hub. L'unica differenza è dove scegli l'app. Puoi mantenere entrambi i tipi di connessione, ma assegna loro nomi riconoscibili così l'agente non sceglie lo strumento sbagliato.

## Cosa potrai fare dopo

Dopo questo tutorial, potrai fare quanto segue dentro il tuo agente, in ordine:

1. Cercare Data App per parola chiave, piattaforma o scenario.
2. Verificare scopo, parametri di input, campi di output e fatturazione di un'app.
3. Confermare app e parametri, poi avviare un'esecuzione.
4. Controllare lo stato di un'attività asincrona e ottenere il risultato finale.

<Note>
  Per i parametri completi e le regole di gestione di `search_data_apps`, `run_data_app`, dei controlli di stato asincroni e dell'`handoff` per risultati grandi, consulta <a href="/docs/it/datahub/mcp-capabilities" target="_blank" rel="noopener noreferrer">Capacità MCP di Data Hub</a>. Questa pagina si concentra su connessione e primo utilizzo.
</Note>

## Prima di iniziare

Prepara quanto segue:

* Un account Octoparse con cui puoi accedere.
* Un client agente che supporti Streamable HTTP MCP, come Claude Code, Codex o Cursor.
* Se scegli il metodo con chiave API: crea in anticipo una chiave API Octoparse.
* Un semplice obiettivo di dati per il test, come «trova una Data App che possa arricchire le informazioni aziendali».

<Warning>
  Una chiave API è una credenziale dell'account. Non inserire mai una chiave reale in un repository di codice, una configurazione condivisa, uno screenshot pubblico o una chat di gruppo. In modalità OAuth, non copiare mai un token di accesso temporaneo da una sessione del browser in una configurazione locale.
</Warning>

## Passo 1: aprire la connessione MCP generale

<Steps>
  <Step title="Andare alla Data Hub Open Platform">
    Accedi al sito Octoparse, apri il menu Data Hub in alto e fai clic su **Data Hub Open Platform**.
  </Step>

  <Step title="Aprire MCP connection">
    Nella navigazione a sinistra dell'Open Platform, fai clic su **MCP connection** per aprire la pagina Data Hub MCP Server. Il set di strumenti predefinito mostrato nella pagina può cercare ed eseguire qualsiasi Data App su Data Hub. Non devi scegliere prima un'app nel catalogo.
  </Step>
</Steps>

<Tip>
  Anche la sezione **Integration** di ogni Data App ha in fondo un link alla connessione MCP che porta qui. Quel link è una scorciatoia. Non significa che devi scegliere prima quell'app.
</Tip>

## Passo 2: scegliere un metodo di autenticazione

La connessione generale supporta sia chiave API sia OAuth. La scelta riguarda solo l'autenticazione. Non cambia il modo in cui le Data App vengono cercate o eseguite.

### Opzione 1: chiave API (consigliata)

Ideale per un uso stabile nel lungo periodo, client da riga di comando e automazione. La configurazione generata dalla pagina contiene:

```text theme={null} theme={null}
Authorization: Bearer <YOUR_API_KEY>
```

`Bearer` è semplicemente il formato dell'header usato per passare la chiave API. Usa una chiave API Octoparse, non un token di accesso temporaneo di una sessione del browser con accesso effettuato.

Se non hai ancora una chiave, creane una nel <a href="https://www.octoparse.it/console/open-platform/api-keys" target="_blank" rel="noopener noreferrer">centro account Octoparse</a>. Una chiave API viene di solito mostrata per intero una sola volta, al momento della creazione. Conservala in un gestore di password affidabile.

### Opzione 2: accesso OAuth

Ideale per client interattivi che supportano MCP OAuth. Quando scegli OAuth, la configurazione non contiene alcuna chiave API. La prima volta che il client si connette, apre un browser in cui accedi a Octoparse e confermi l'autorizzazione. La sessione può scadere, nel qual caso autorizzi di nuovo.

## Passo 3: copiare il prompt di installazione generale

Nella pagina **MCP connection**, scegli il tuo client agente e il metodo di autenticazione, poi fai clic su **Copy install prompt**. **Copy MCP URL** fornisce solo l'indirizzo del server. Copia il contenuto completo che la pagina genera in questo momento. Non digitare a memoria l'indirizzo del server, l'ambito degli strumenti o gli header.

<Tip>
  L'indirizzo generale del server mostrato nella pagina si basa su `https://mcp-v2.octoparse.com`. La configurazione esatta e i parametri degli strumenti possono cambiare, quindi usa sempre ciò che l'Open Platform genera attualmente.
</Tip>

## Passo 4: lasciare che l'agente completi la configurazione

L'esempio seguente usa Claude Code. Codex e Cursor posizionano i pulsanti in modo diverso, ma i passaggi principali sono gli stessi: incollare il prompt di installazione, scegliere il metodo di autenticazione, consentire le modifiche alla configurazione MCP dell'utente corrente e poi ricaricare il client.

<Steps>
  <Step title="Inviare il prompt di installazione all'agente">
    Avvia una nuova conversazione e incolla il prompt completo che hai copiato. L'agente dovrebbe chiedere il metodo di autenticazione prima di scrivere la configurazione. Se prova a scrivere credenziali in un file di progetto, fermalo e chiedi invece la configurazione MCP locale dell'utente corrente.
  </Step>

  <Step title="Confermare il metodo di autenticazione">
    Se hai scelto la chiave API, forniscila in modo sicuro quando l'agente la chiede. Se hai scelto OAuth, non fornire alcuna chiave e lascia che l'agente scriva una configurazione senza credenziali.
  </Step>

  <Step title="Ricaricare il client">
    Dopo la configurazione, ricarica i server MCP o riavvia il client. Con OAuth, la prima connessione può mostrare «Autenticazione richiesta». È normale.
  </Step>
</Steps>

## Passo 5: completare l'autorizzazione OAuth (solo OAuth)

Se hai scelto la chiave API, passa al passo successivo.

<Steps>
  <Step title="Avviare la connessione nel client">
    In Claude Code, esegui `/mcp` e seleziona il server Data Hub appena aggiunto, chiamato `octoparse_datahub` per impostazione predefinita. Quando indica che è necessaria l'autenticazione, scegli di autenticarti. Altri client mostrano un pulsante **Connect** o simile nelle impostazioni MCP.
  </Step>

  <Step title="Accedere e autorizzare nel browser">
    Il browser apre la pagina di identità Octoparse. Controlla il dominio e l'account corrente, leggi l'ambito richiesto e conferma. Segui l'indicazione della pagina per tornare al client. Alcuni client tornano automaticamente.
  </Step>

  <Step title="Confermare che il server è abilitato">
    Tornato nel client, conferma che lo stato «Autenticazione richiesta» è scomparso e che il server è abilitato. Se risulta ancora non autenticato, ricarica il client e riprova.
  </Step>
</Steps>

## Passo 6: cercare prima, non eseguire subito

La chiave della connessione generale è lasciare che l'agente scopra prima le Data App. Al primo utilizzo, chiedigli esplicitamente di cercare e confrontare soltanto, senza creare ancora un'attività a pagamento. Ad esempio:

```text theme={null} theme={null}
Usa Data Hub per cercare Data App relative ad «arricchimento aziendale».
Elenca i 3 risultati più pertinenti. Per ciascuno, descrivi lo scopo, gli input richiesti, i principali campi di output e il modello di fatturazione.
Non eseguire nulla per ora. Attendi la mia conferma.
```

L'agente di solito richiama `search_data_apps` per cercare nel catalogo, poi `get_data_app_details` per leggere il contratto completo di ogni candidata.

<Note>
  Il numero, i nomi e la copertura di piattaforme delle app trovate da un agente cambiano in tempo reale con il catalogo di Data Hub. Questa documentazione non fornisce un elenco fisso. Affidati a ciò che `search_data_apps` restituisce effettivamente.
</Note>

## Passo 7: confermare l'app, poi eseguire

Scegli un'app tra le candidate. Fai ripetere all'agente i parametri e le azioni previste, poi esegui un piccolo test:

```text theme={null} theme={null}
Scegli la prima Data App. Dimmi prima i suoi parametri obbligatori, i valori predefiniti e il modello di fatturazione.
Dopo la mia conferma, esegui solo con il volume di dati più piccolo e restituisci lo stato dell'attività, il numero di record e i primi 5 record.
```

<Steps>
  <Step title="Verificare input e costo">
    Conferma parametri obbligatori, ambito dei dati, campi restituiti e unità di fatturazione. Se qualcosa non è chiaro, fai richiamare di nuovo all'agente lo strumento dei dettagli invece di indovinare i parametri.
  </Step>

  <Step title="Eseguire un piccolo test">
    Solo dopo la conferma, lascia che l'agente richiami `run_data_app`. Un'app sincrona restituisce i risultati direttamente. Un'app asincrona richiede controlli di stato successivi.
  </Step>

  <Step title="Ottenere i risultati asincroni">
    Per le attività asincrone, fai usare all'agente gli strumenti di stato e risultato per attendere il completamento, poi restituire i dati finali. Non considerare «attività inviata» come un'estrazione riuscita.
  </Step>

  <Step title="Controllare i risultati">
    Controlla lo stato dell'attività, il numero effettivo di record e i campi chiave. Un campo mancante in un singolo record può riflettere una differenza nei dati di origine. Se la maggior parte dei record non corrisponde alle aspettative, cambia app o regola i parametri.
  </Step>
</Steps>

## Domande frequenti

<AccordionGroup>
  <Accordion title="La connessione generale richiede di scegliere prima una Data App?">
    No. La connessione generale fornisce prima gli strumenti di ricerca ed esecuzione. Dopo la connessione, l'agente usa `search_data_apps` per trovare le capacità. Solo la connessione ad app specifica richiede di scegliere prima un'app nel catalogo.
  </Accordion>

  <Accordion title="Devo scegliere chiave API o OAuth?">
    Preferisci la chiave API per uso a lungo termine, client da riga di comando e automazione. Scegli OAuth quando vuoi accedere tramite browser e il tuo client supporta esplicitamente MCP OAuth. Le sessioni OAuth possono scadere e richiedere una nuova autorizzazione.
  </Accordion>

  <Accordion title="La configurazione è riuscita, ma non c'è lo strumento search_data_apps">
    Conferma di aver usato la configurazione generale dalla pagina **MCP connection** dell'Open Platform, non la configurazione ristretta di un'app specifica. Copia di nuovo il prompt attuale e ricarica il client.
  </Accordion>

  <Accordion title="OAuth continua a indicare che è necessaria l'autenticazione">
    Avvia la connessione nelle impostazioni MCP del client, completa accesso e autorizzazione nel browser, poi torna al client. Verifica se il browser ha bloccato il reindirizzamento e conferma che la pagina di autorizzazione appartenga al servizio di identità ufficiale di Octoparse.
  </Accordion>

  <Accordion title="L'agente ha trovato un'app e l'ha eseguita subito">
    Scrivi esplicitamente «cerca e confronta soltanto, non eseguire per ora» nel prompt. Quando sono coinvolti costi o grandi volumi di dati, chiedi all'agente di attendere la conferma prima di richiamare `run_data_app`.
  </Accordion>

  <Accordion title="L'esecuzione ha restituito solo un ID attività e nessun dato">
    L'app è probabilmente asincrona. Fai continuare all'agente il controllo dello stato dell'attività e fai recuperare i risultati al completamento. Non inviare di nuovo la stessa attività.
  </Accordion>
</AccordionGroup>

## Lista di controllo

* Hai copiato il prompt di installazione generale dalla pagina **MCP connection** della Data Hub Open Platform.
* Hai scelto chiave API oppure OAuth e non hai mescolato le due credenziali.
* L'agente ha caricato gli strumenti generali di Data Hub e può usare `search_data_apps`.
* Hai cercato e verificato i dettagli dell'app prima di confermare un'esecuzione.
* Hai completato una chiamata reale con il volume di dati più piccolo e controllato il risultato finale.

## Sai già quale app usare?

Se la tua attività usa un'app fissa nel lungo periodo, puoi restringere l'ambito della connessione:

<CardGroup cols={2}>
  <Card title="Codex: collegare un'app specifica" href="/docs/it/datahub/quick-start/agent-connection/codex">
    Scegli prima un'app precisa, poi aggiungila a Codex come strumento fisso.
  </Card>

  <Card title="Claude Code: collegare un'app specifica" href="/docs/it/datahub/quick-start/agent-connection/claude-code">
    Scegli prima un'app precisa, poi aggiungila a Claude Code come server MCP fisso.
  </Card>
</CardGroup>

<Note>
  Il numero effettivo di app, i loro nomi, editori e prezzi restituiti da una ricerca cambiano con il catalogo di Data Hub. Affidati a ciò che lo strumento restituisce a ogni chiamata.
</Note>