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.

Cos'è MCP?#

Il Model Context Protocol è 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. 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

Installazione: un solo comando#

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.

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

Gestiscilo con la stessa facilità#

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, ...):

{
  "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:

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.

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

Esempi di prompt#

Una volta installato, prova questi in una nuova sessione dell'assistente:

Give me https://en.wikipedia.org/wiki/Model_Context_Protocol as markdown and summarize it.

Screenshot https://news.ycombinator.com and save the page as a PDF too.

Search for the three best static site generators and read their homepages.

Get every plan name and price from https://example.com/pricing.

Convert /Users/me/Desktop/report.docx to PDF.

Squeeze /Users/me/Desktop/screenshot.png under 200 KB without changing the format.

Turn /Users/me/Downloads/whitepaper.pdf into Markdown for my RAG index.

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. 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
• GitHub: enconvert/mcp
• Licenza: MIT
• SDK sottostante: Node.js SDK
• Specifica MCP: 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.