--- seo_title: Configurazione JSON server MCP: Claude Code, Cursor | EnConvert meta_desc: Configura il server @enconvert/mcp in Claude Code, Cursor, Windsurf e Claude Desktop con la configurazione JSON esatta o un comando: npx @enconvert/mcp setup. keywords: come configurare un server mcp json, server mcp per conversione file, configurare mcp in claude code, cursor mcp json config, installare server mcp su claude desktop, configurazione windsurf mcp, npx per impostare un server mcp, model context protocol per convertire file, server mcp enconvert, strumento mcp compressione immagini, mcp da pdf a markdown per rag --- # Impostazione del server MCP e configurazione JSON `@enconvert/mcp` è il server ufficiale Model Context Protocol (MCP) per EnConvert. Consente a qualsiasi assistente AI compatibile con MCP (Claude Code, Cursor, Windsurf, Claude Desktop, VS Code, Zed, Gemini CLI, Codex, OpenCode) di renderizzare, cercare, estrarre, ingerire, monitorare, convertire e comprimere pagine web e file direttamente dalla chat. Configuralo con un singolo comando, `npx @enconvert/mcp setup`, oppure copia il blocco di configurazione JSON esatto per il file di configurazione MCP del tuo client. Viene eseguito localmente su stdio con Node.js 18+ e registra ventiquattro strumenti.
npm: @enconvert/mcp · Sorgente: enconvert/mcp · Node: 18+ · Trasporto: stdio
--- ## Cos'è MCP? Il [Model Context Protocol](https://modelcontextprotocol.io) è uno standard aperto per esporre strumenti, prompt e risorse ad assistenti basati su LLM tramite una piccola interfaccia JSON-RPC. Un server MCP viene eseguito come sottoprocesso locale, l'assistente lo avvia all'inizio della sessione e gli strumenti diventano funzionalità di prim'ordine che il modello può invocare durante una conversazione. `@enconvert/mcp` è un sottile wrapper attorno al [Node.js SDK](/it/docs/guides/integrations/sdks/nodejs.md). Registra ventiquattro strumenti, ciascuno con una descrizione ottimizzata per una selezione affidabile degli strumenti da parte dell'LLM. Tutta la gestione di HTTP, autenticazione, timeout e polling di recupero è ereditata dall'SDK. --- ## Requisiti - **Node.js 18 o versioni successive** sulla macchina che esegue l'assistente - Una **chiave API privata EnConvert** (`sk_...`), che puoi generare nella [dashboard](/it/dashboard) --- ## Installazione: un solo comando ```bash npx @enconvert/mcp setup ``` Il wizard interattivo fa tutto: 1. **Rileva i tuoi strumenti AI** (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Zed, Gemini CLI, Codex CLI, OpenCode) e ti permette di scegliere quali ricevono EnConvert (gli strumenti rilevati sono preselezionati). 2. **Chiede la tua chiave API segreta una sola volta** (input nascosto) e la valida in tempo reale contro l'API. Hai incollato per errore una chiave *pubblica*? Te lo dice esattamente. 3. **Scrive ogni configurazione correttamente**, incluso il wrapper `cmd /c npx` richiesto da Windows nativo. ```text $ npx @enconvert/mcp setup EnConvert MCP - setup ? Which AI tools should get EnConvert? [x] Claude Code (detected) [x] Cursor (detected) [ ] Claude Desktop [ ] Windsurf ... ? Paste your SECRET API key (sk_..., input hidden): ******** ✔ API key is valid. + Claude Code - claude CLI (user scope) + Cursor - ~/.cursor/mcp.json Done. Restart your AI tools to pick up the server. ```
Riavvio necessario. I server MCP si caricano solo all'avvio di una sessione dell'assistente. Dopo il setup, chiudi completamente l'assistente e riaprilo prima di testare.
### Gestiscilo con la stessa facilità | Comando | Cosa fa | |---------|-------------| | `npx @enconvert/mcp status` | Mostra dove è installato il server e valida la tua chiave in tempo reale | | `npx @enconvert/mcp rotate-key` | Sostituisce la chiave API salvata con un solo comando, applicato a ogni client | | `npx @enconvert/mcp remove` | Disinstalla dagli strumenti selezionati (opzionalmente elimina la chiave salvata) | | `npx @enconvert/mcp setup --yes` | Non interattivo: configura tutti gli strumenti rilevati con la chiave salvata | | `npx @enconvert/mcp upgrade` | Verifica su npm se esiste una versione più recente e la aggiorna. Aggiungi `--dry-run` per un'anteprima | Per lo scripting, `setup --clients claude-code,cursor --api-key sk_... --yes` salta ogni prompt. Eseguire `rotate-key` senza argomenti richiede un input nascosto, così la chiave non finisce mai nella cronologia della shell. ### Dove vive la chiave `setup` salva la tua chiave **una sola volta** in `~/.enconvert/config.json` (modalità file `600`) invece di duplicarla nella configurazione in chiaro di ogni client. Il server la legge all'avvio; la variabile d'ambiente `ENCONVERT_API_KEY` la sovrascrive sempre (per Docker, CI o setup manuali). Ruotare una chiave è quindi una modifica a un singolo file, e ogni client la recepisce al lancio successivo. ### Avanzato: configurazione manuale Preferisci collegarlo manualmente? Aggiungi questo alla configurazione MCP del tuo client (`~/.cursor/mcp.json`, `~/.codeium/windsurf/mcp_config.json`, il `claude_desktop_config.json` di Claude Desktop, ...): ```json { "mcpServers": { "enconvert": { "command": "npx", "args": ["-y", "@enconvert/mcp@latest"], "env": { "ENCONVERT_API_KEY": "sk_your_key" } } } } ``` Su Windows nativo, sostituisci `command` con `cmd` e anteponi `"/c", "npx"` a `args`, perché `npx` da solo si blocca. Per Claude Code: ```bash claude mcp add enconvert -s user \ -e ENCONVERT_API_KEY=sk_your_key \ -- npx -y @enconvert/mcp@latest ``` Il blocco `env` inline è opzionale se hai già eseguito `setup`, dato che il server ricade automaticamente sulla chiave salvata. --- ## Strumenti disponibili Ventiquattro strumenti. Tutto il lavoro su URL/browser passa attraverso gli strumenti V2 (`perceive_url` e affini); gli strumenti per i file coprono la conversione e la compressione di documenti e immagini, sia locali sia remoti. | Strumento | Scopo | |------|---------| | `perceive_url` | Renderizza una pagina live in più artefatti contemporaneamente: markdown (inline), HTML, screenshot, PDF, link, immagini, più estrazione strutturata, con caching di ~1h | | `get_perceive_operation` / `perceive_batch` / `get_perceive_batch` | Rifirma gli URL degli artefatti; renderizza fino a 1000 URL in un solo batch; effettua il polling dei batch | | `discover_urls` | Enumera gli URL di un sito via sitemap/crawl/hybrid, senza rendering | | `web_search` | Ricerca basata su Google in sei categorie, con rendering automatico opzionale dei risultati principali | | `extract_structured` | Estrazione dati basata su schema (passaggio CSS gratuito + escalation LLM) da fino a 50 URL | | `start_ingest` + gli strumenti per i job | Trasforma un sito o una lista di URL in JSONL suddiviso in chunk pronto per RAG (asincrono), con list/get/cancel/webhook-retry | | `create_watcher` + gli strumenti watcher | Monitora pagine per rilevare modifiche con una cadenza oraria o superiore, con cronologia dei diff, list/get/update/delete | | `convert_document` | Converte DOCX, XLSX, PPTX, ODT, Pages, Numbers, HTML, Markdown, CSV, JSON, XML, YAML, TOML tra formati (PDF di default) | | `convert_image` | Converte tra JPEG, PNG, SVG, HEIC, WebP, più la rasterizzazione da PDF a JPEG, con `width` e `height` opzionali per dimensionare il canvas quando si rasterizza un SVG | | `compress_image` | Riduce un PNG, un JPEG o un WebP mantenendo invariato il formato, con downscaling opzionale fino a una dimensione target in KB | | `convert_anything_to_markdown` | Trasforma file PDF, Office, ODF, EPUB, HTML, CSV o di testo in Markdown pulito e strutturato per intestazioni, pensato per le pipeline RAG | | `convert_anything_to_pdf` | Trasforma quasi ogni file in un PDF: Office, ODF, iWork, immagini, SVG, HTML, Markdown, EPUB, RTF, CSV, più il passthrough dei PDF | | `get_job_status` | Verifica lo stato di un job di conversione file tramite il suo job ID | Le descrizioni degli strumenti seguono una struttura coerente **Use when / Do NOT use when / Returns** in modo che l'assistente indirizzi i prompt allo strumento giusto. Gli strumenti V2 richiedono la chiave API privata e sono soggetti al piano, quindi una funzionalità disabilitata o una quota esaurita restituisce un messaggio di quota chiaro, non un errore criptico. Vale la pena conoscere due comportamenti prima di richiederli in un prompt. `compress_image` non cambia mai il formato (un PNG torna PNG, un JPEG torna JPEG) e non restituisce mai un file più grande dell'input, quindi puoi eseguirlo in sicurezza anche su un file già ottimizzato; `target_size_kb` è best effort, e un budget irraggiungibile restituisce il file più piccolo ottenuto invece di un errore, quindi controlla la dimensione del file che ricevi. Su `convert_image`, `width` e `height` si applicano solo agli input SVG e accettano ciascuna un valore da 1 a 10000: passarne una sola scala l'output in modo proporzionale a partire dalle proporzioni dell'SVG, mentre passarle entrambe imposta il canvas esatto. --- ## Configurazione La chiave API viene risolta in quest'ordine: 1. Variabile d'ambiente `ENCONVERT_API_KEY` (dalla configurazione MCP dell'assistente), che ha sempre la precedenza 2. `~/.enconvert/config.json`, scritto da `npx @enconvert/mcp setup` | Impostazione | Obbligatoria | Predefinito | Scopo | |----------|----------|---------|---------| | `ENCONVERT_API_KEY` (env) o `api_key` (file di configurazione) | Sì | -- | Chiave API privata (`sk_...`) | | `ENCONVERT_BASE_URL` (env) o `base_url` (file di configurazione) | No | `https://api.enconvert.com` | Override per staging o gateway self-hosted |
Non incollare mai una chiave nella chat dell'assistente. Usa npx @enconvert/mcp setup (input nascosto), oppure impostala tramite il blocco env nel file di configurazione MCP. Le chiavi incollate nella cronologia della chat finiscono nei transcript.
--- ## Esempi di prompt Una volta installato, prova questi in una nuova sessione dell'assistente: ```text Give me https://en.wikipedia.org/wiki/Model_Context_Protocol as markdown and summarize it. ``` ```text Screenshot https://news.ycombinator.com and save the page as a PDF too. ``` ```text Search for the three best static site generators and read their homepages. ``` ```text Get every plan name and price from https://example.com/pricing. ``` ```text Convert /Users/me/Desktop/report.docx to PDF. ``` ```text Squeeze /Users/me/Desktop/screenshot.png under 200 KB without changing the format. ``` ```text Turn /Users/me/Downloads/whitepaper.pdf into Markdown for my RAG index. ``` ```text Watch https://example.com/changelog and tell me when it changes. ``` L'assistente sceglie automaticamente lo strumento giusto: il lavoro su URL finisce su `perceive_url`, la ricerca su `web_search`, lo scraping strutturato su `extract_structured`, i budget di dimensione su `compress_image`, il Markdown pronto per RAG su `convert_anything_to_markdown` e il resto del lavoro sui file sugli strumenti di conversione. --- ## Formato dell'output Ogni strumento restituisce una risposta coerente: - Un **riepilogo testuale** con URL di download e metadati - Un blocco **`structuredContent`** con il risultato tipizzato completo - Un **`resource_link`** al file locale quando viene fornito `save_to` (strumenti per i file) - Per `perceive_url`, **l'artefatto markdown viene anche incorporato inline** nella risposta (fino a ~256 KB), così l'assistente può leggerlo e riassumerlo senza una richiesta separata --- ## Come funziona `@enconvert/mcp` chiama gli stessi endpoint REST pubblici documentati nel resto di questo sito, tramite il [Node.js SDK](/it/docs/guides/integrations/sdks/nodejs.md). Questo significa: - **Stesso formato di trasmissione**: ogni strumento corrisponde 1:1 a un endpoint `/v1/convert/*` o `/v2/*` - **Stesso recupero da timeout**: le conversioni lunghe ricadono automaticamente sul polling di `job_id`, in modo trasparente - **Stessa autenticazione**: la tua chiave API privata autorizza ogni chiamata, e si applicano la quota e i rate limit della tua dashboard L'assistente non vede mai la chiave API. Vede solo l'elenco degli strumenti e i relativi input. --- ## Risoluzione dei problemi **L'assistente prova a usare un browser locale invece dello strumento MCP.** Il server MCP non è registrato o non è partito. Esegui `npx @enconvert/mcp status` in un terminale normale, poi riavvia l'assistente. **`Authentication failed: Invalid or missing API key`.** Esegui `npx @enconvert/mcp status`, che mostra da dove proviene la chiave e la valida in tempo reale. Risolvilo con `npx @enconvert/mcp rotate-key`. **`npx` si blocca su Windows nativo.** Usa `cmd /c npx ...`. `npx @enconvert/mcp setup` scrive questo wrapper automaticamente su Windows. **La chiamata allo strumento va in timeout prima che la conversione finisca.** I render del browser più pesanti possono richiedere 30+ secondi. L'SDK attende fino a 5 minuti per impostazione predefinita; aumenta il timeout per strumento dell'assistente se interrompe prima. **Percorso relativo rifiutato su `convert_document` / `convert_image`.** Passa un percorso assoluto (ad es. `/Users/me/file.docx` o `C:\Users\me\file.docx`), oppure passa un URL `http(s)://`. I server MCP non hanno una working directory affidabile. --- ## Sorgente e link - **npm**: [@enconvert/mcp](https://www.npmjs.com/package/@enconvert/mcp) - **GitHub**: [enconvert/mcp](https://github.com/enconvert/mcp) - **Licenza**: MIT - **SDK sottostante**: [Node.js SDK](/it/docs/guides/integrations/sdks/nodejs.md) - **Specifica MCP**: [modelcontextprotocol.io](https://modelcontextprotocol.io) --- ## Domande frequenti ### Come configuro un server MCP in JSON? Aggiungi una voce sotto `mcpServers` nel file di configurazione MCP del tuo client (`~/.cursor/mcp.json` per Cursor, `~/.codeium/windsurf/mcp_config.json` per Windsurf, `claude_desktop_config.json` per Claude Desktop) con `"command": "npx"`, `"args": ["-y", "@enconvert/mcp@latest"]`, e la tua `ENCONVERT_API_KEY` nel blocco `env`. Oppure salta del tutto il JSON manuale: `npx @enconvert/mcp setup` rileva i tuoi strumenti AI installati e scrive ogni configurazione correttamente. ### Come imposto un server MCP in Claude Code? Esegui `claude mcp add enconvert -s user -e ENCONVERT_API_KEY=sk_your_key -- npx -y @enconvert/mcp@latest`, oppure usa il wizard interattivo `npx @enconvert/mcp setup`, che rileva Claude Code e lo configura automaticamente. Riavvia poi completamente l'assistente, perché i server MCP si caricano solo all'avvio di una sessione. ### Perché npx si blocca all'avvio di un server MCP su Windows? `npx` da solo si blocca su Windows nativo. Sostituisci `command` con `cmd` e anteponi `"/c", "npx"` a `args`; `npx @enconvert/mcp setup` scrive questo wrapper automaticamente su Windows. ### Dove salva il server MCP la mia chiave API? `npx @enconvert/mcp setup` salva la chiave una sola volta in `~/.enconvert/config.json` (modalità file `600`) invece di duplicarla nella configurazione in chiaro di ogni client. La variabile d'ambiente `ENCONVERT_API_KEY` la sovrascrive sempre, e `npx @enconvert/mcp rotate-key` sostituisce la chiave salvata per ogni client con un solo comando. ### Un assistente AI può convertire file tramite un server MCP? Sì. Lo strumento `convert_document` converte DOCX, XLSX, PPTX, ODT, Pages, Numbers, HTML, Markdown, CSV, JSON, XML, YAML e TOML tra formati (PDF di default). L'EPUB non ha una coppia `convert_document`; invia i file `.epub` a `convert_anything_to_pdf` o `convert_anything_to_markdown`. Inoltre, `convert_image` converte tra JPEG, PNG, SVG, HEIC e WebP, più la rasterizzazione da PDF a JPEG. Passa percorsi di file assoluti o URL `http(s)://`, dato che i server MCP non hanno una working directory affidabile. ### Come riduco la dimensione di un'immagine senza cambiarne il formato? Chiedi all'assistente di comprimere il file e la richiesta viene instradata su `compress_image`, che mantiene un PNG come PNG, un JPEG come JPEG e un WebP come WebP. Rimuove i metadati preservando il profilo colore ICC e l'orientamento EXIF, e non restituisce mai un file più grande dell'input. Aggiungi un budget `target_size_kb` e l'immagine viene ridimensionata verso il basso con le proporzioni bloccate finché non rientra nel budget; un budget irraggiungibile restituisce il file più piccolo ottenuto invece di un errore, quindi controlla la dimensione che ricevi.