--- seo_title: REST, MCP, CLI o SDK: quale usare | EnConvert meta_desc: EnConvert espone la stessa API tramite REST, un server MCP, una CLI, un node n8n e dieci SDK. Come si relazionano le superfici e quando scegliere ciascuna. keywords: rest o mcp server, superfici di accesso api, mcp server vs api rest, cli o sdk, una sola api key ovunque, superfici di integrazione enconvert, node n8n o api, quando usare un sdk --- # Un'unica API, cinque modi per chiamarla EnConvert è un'unica API HTTP su `https://api.enconvert.com`. Il server MCP, la CLI, il node n8n e i dieci SDK sono client di quell'API, non prodotti separati. Raggiungono gli stessi endpoint con la stessa chiave. ## REST è il substrato Ogni chiamata finisce nella stessa forma: una richiesta HTTPS verso `https://api.enconvert.com` con un header `X-API-Key`. Il gateway non sa quale client l'ha inviata, a parte la stringa `User-Agent`, e l'unico motivo per cui quella stringa esiste è l'attribuzione: ogni SDK invia `enconvert-sdk/ ()` così il traffico può essere conteggiato per linguaggio. Nessun client ha un endpoint tutto suo. Non esiste alcuna operazione API raggiungibile tramite la CLI o il server MCP che tu non possa eseguire con `curl` e le pagine di questo sito. Il contrario va detto chiaramente, perché è qui che le persone restano sorprese: i client incapsulano REST a profondità diverse. - La **CLI** è la più ampia. Ha verbi per le route di conversione e per perceive, discover, lookup, distill e ingest, più `enconvert api` come passthrough in stile gh che raggiunge tutto ciò per cui non ha ancora un verbo. - Il **server MCP** registra 24 strumenti. Lascia deliberatamente fuori gli endpoint del signing secret dei webhook (`GET /v2/ingest/webhook-secret` e il suo corrispettivo di rotazione), perché un signing secret non dovrebbe essere leggibile da un modello. - Il **node n8n** espone 6 risorse e 16 operazioni, modellate sui passaggi di un workflow anziché sulla copertura completa dell'API. - Gli **SDK** coprono gli endpoint di conversione e gli endpoint web V2 in tutti e dieci i linguaggi. Quando un client è più ristretto dell'API, scendi a REST per quella singola chiamata. Mescolare va bene. Chiamate SDK e chiamate HTTP scritte a mano possono condividere un progetto e una chiave senza alcuna gestione particolare. --- ## Una sola chiave, ogni superficie Ogni superficie si autentica con la stessa chiave API privata (`sk_...`), inviata nell'header `X-API-Key`. Generane una nella [dashboard](/it/dashboard) e funziona in `curl`, in `enconvert auth login`, in una configurazione MCP, in una credenziale n8n e nel costruttore di un SDK. Ruotarla le ruota tutte. L'unica cosa che cambia è dove viene conservata la chiave. | Superficie | Dove risiede la chiave | Override da ambiente | |---------|---------------------|----------------------| | REST | Ovunque il tuo codice conservi i segreti | -- | | SDK | Passata al costruttore del client | -- | | CLI | `credentials.toml`, permessi file `0600` | `ENCONVERT_API_KEY` | | server MCP | `~/.enconvert/config.json`, permessi file `600` | `ENCONVERT_API_KEY` | | node n8n | La credenziale `enconvertApi` dentro n8n | -- |
Queste superfici richiedono una chiave privata. La CLI, il server MCP, il node n8n e gli SDK si aspettano tutti sk_.... Una chiave pubblica pk_ serve al codice del browser che genera un JWT a breve scadenza, e la credenziale n8n rifiuta senza appello le chiavi pk_. Consulta Autenticazione.
Anche l'utilizzo è condiviso. Un'unica quota mensile di ops copre ogni superficie, e un'operazione costa lo stesso sia che arrivi da un programma Go sia che arrivi da un terminale. Consulta [Rate limit e quote](/it/docs/reference/rate-limits.md). --- ## Quando scegliere ciascuna | Superficie | Cos'è | Scegliila quando | |---------|-----------|-------------------| | REST | L'API stessa: corpi JSON e multipart su HTTPS | Stai scrivendo codice applicativo, non vuoi dipendenze, oppure il tuo linguaggio non ha un SDK | | SDK | Client tipizzati per dieci linguaggi | Vuoi l'autocompletamento su ogni parametro e un recupero dai timeout che non hai dovuto scrivere tu | | CLI | Il binario `enconvert`, da Homebrew, Scoop, uno script shell di installazione o npm | Stai scrivendo uno script shell, esegui un lavoro una tantum o lavori in CI | | server MCP | `@enconvert/mcp`, un server stdio locale per assistenti AI | Un agente di coding deve decidere da solo quando chiamare l'API | | node n8n | `@enconvert/n8n-nodes-enconvert`, un community node | Il workflow vive già in n8n e vuoi il risultato come dati binary n8n | Due di queste scelte sono di solito ovvie. Se a digitare è una persona, è la CLI; se a decidere è un modello, è MCP. La domanda REST o SDK è l'unica su cui valga la pena ragionare, e dipende da quanto codice di retry e di polling vuoi mantenere tu. --- ## La stessa lettura, in tre modi Leggere `https://example.com/pricing` in Markdown è una sola richiesta `POST /v2/perceive`. Eccola come HTTP grezzo: ```bash curl -X POST https://api.enconvert.com/v2/perceive \ -H "X-API-Key: sk_your_private_key" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/pricing", "outputs": ["markdown"] }' ``` La CLI emette lo stesso `POST /v2/perceive`. Il comando da solo non invia `outputs`, quindi ottiene il valore predefinito del server: Markdown più il blocco strutturato inline: ```bash enconvert perceive https://example.com/pricing ``` Con MCP la chiamata non la scrivi affatto. Chiedi all'assistente di leggere la pagina, lui sceglie lo strumento `perceive_url`, e gli argomenti che contano vengono fuori così: ```json { "name": "perceive_url", "arguments": { "url": "https://example.com/pricing", "outputs": ["markdown"] } } ```
Stessa richiesta, stesso addebito. Ognuna delle tre renderizza la pagina una volta e costa un'operazione. Il server MCP fa una cosa in più: recupera l'artefatto Markdown finito e inserisce il testo inline nel risultato dello strumento (fino a circa 256 KB), così l'assistente può leggere la pagina senza un secondo fetch.
--- ## Dove andare adesso La configurazione si trova nelle guide alle integrazioni, una pagina per superficie: - **[Integrazioni](/it/docs/guides/integrations.md)** è l'hub, e copre anche i widget web incorporabili. - **[Impostazione MCP](/it/docs/guides/integrations/mcp-setup.md)** installa `@enconvert/mcp` in Claude Code, Cursor, Windsurf e altri sei client con `npx @enconvert/mcp setup`. - **[n8n](/it/docs/guides/integrations/n8n.md)** installa il community node e ti accompagna tra le sei risorse. - **[CLI](/it/docs/guides/integrations/cli.md)** copre l'installazione, `enconvert auth login`, i flag per lo scripting e i codici di uscita. - **[SDK](/it/docs/guides/integrations/sdks.md)** elenca tutti e dieci i pacchetti, con una pagina ciascuno. Per l'API in sé, [Endpoint](/it/docs/endpoints.md) è il riferimento e [Autenticazione](/it/docs/authentication.md) spiega i due tipi di chiave. --- ## Domande frequenti ### Il server MCP è un'API diversa dall'API REST? No. `@enconvert/mcp` è un processo stdio locale che chiama gli stessi endpoint REST pubblici documentati su questo sito, usando la tua chiave API privata. Ogni strumento corrisponde a una richiesta `/v1/convert/*` o `/v2/*`, quindi attinge dalla stessa quota e restituisce gli stessi errori. ### Mi servono API key separate per la CLI, per MCP e per la mia applicazione? No. Un'unica chiave privata (`sk_...`) le autentica tutte, e puoi riusare la stessa chiave su tutte le superfici. Chiavi separate restano comunque utili se vuoi revocare una superficie senza toccare le altre, per esempio una chiave di CI che puoi ruotare indipendentemente da quella del tuo portatile. ### Posso usare una chiave pubblica pk_ con la CLI o con un SDK? No. Le chiavi pubbliche esistono per il codice del browser, dove generano un JWT a breve scadenza invece di essere inviate direttamente. La CLI, il server MCP, il node n8n e gli SDK si aspettano tutti una chiave privata `sk_...`, e la credenziale n8n rifiuta una chiave `pk_` già in fase di validazione. ### C'è qualcosa disponibile solo tramite gli SDK o solo tramite la CLI? Nessuna operazione API. Quello che gli SDK aggiungono è lato client: opzioni type-safe, download in streaming su disco e fallback automatico al polling di `GET /v1/convert/status/{job_id}` quando una conversione lunga supera il timeout del proxy. Tutto questo puoi scriverlo tu direttamente su REST grezzo. ### Quale superficie dovrei usare dentro una pipeline di CI? La CLI, con `ENCONVERT_API_KEY` impostata dal secret store della tua CI e `--no-input` così nessun prompt può bloccare l'esecuzione. I suoi codici di uscita sono un contratto pubblicato e stabile, quindi una conversione fallita fa fallire lo step senza dover analizzare l'output.