Installation du serveur MCP et configuration JSON#

@enconvert/mcp est le serveur officiel Model Context Protocol (MCP) pour EnConvert. Il permet à tout assistant IA compatible MCP (Claude Code, Cursor, Windsurf, Claude Desktop, VS Code, Zed, Gemini CLI, Codex, OpenCode) de rendre, rechercher, extraire, ingérer, surveiller, convertir et compresser des pages web et des fichiers directement depuis le chat. Configurez-le avec une seule commande, npx @enconvert/mcp setup, ou copiez le bloc de config JSON exact pour le fichier de config MCP de votre client. Il s'exécute localement via stdio sur Node.js 18+ et enregistre vingt-quatre outils.

Qu'est-ce que MCP ?#

Le Model Context Protocol est un standard ouvert qui expose des outils, des prompts et des ressources aux assistants pilotés par LLM via une petite interface JSON-RPC. Un serveur MCP s'exécute comme un sous-processus local, l'assistant le lance au démarrage de la session, et les outils deviennent des capacités de premier ordre que le modèle peut invoquer pendant une conversation.

@enconvert/mcp est une fine surcouche du SDK Node.js. Il enregistre vingt-quatre outils, chacun avec une description calibrée pour une sélection d'outil fiable par le LLM. Toute la gestion HTTP, de l'authentification, des timeouts et du polling de récupération est héritée du SDK.

Prérequis#

• Node.js 18 ou supérieur sur la machine exécutant l'assistant
• Une clé API privée EnConvert (sk_...), que vous générez dans le tableau de bord

Installation : une seule commande#

npx @enconvert/mcp setup

L'assistant d'installation interactif fait tout :

1. Détecte vos outils IA (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Zed, Gemini CLI, Codex CLI, OpenCode) et vous laisse choisir lesquels recevront EnConvert (les outils détectés sont présélectionnés).
2. Demande votre clé API secrète une seule fois (saisie masquée) et la valide en direct auprès de l'API. Vous avez collé une clé publique par erreur ? Il vous le dit clairement.
3. Écrit chaque configuration correctement, y compris le wrapper cmd /c npx requis par Windows natif.

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

Gérez-le tout aussi facilement#

Pour le scripting, setup --clients claude-code,cursor --api-key sk_... --yes ignore toutes les invites. Exécuter rotate-key sans argument demande une saisie masquée, afin que la clé n'atterrisse jamais dans l'historique de votre shell.

Où vit la clé#

setup stocke votre clé une seule fois dans ~/.enconvert/config.json (mode de fichier 600) au lieu de la dupliquer dans la config en clair de chaque client. Le serveur la lit au démarrage ; la variable d'environnement ENCONVERT_API_KEY la remplace toujours (pour Docker, CI, ou les installations manuelles). La rotation d'une clé est donc un changement dans un seul fichier, et chaque client la récupère à son prochain lancement.

Avancé : configuration manuelle#

Vous préférez tout configurer vous-même ? Ajoutez ceci au fichier de config MCP de votre client (~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, claude_desktop_config.json de Claude Desktop, ...) :

{
  "mcpServers": {
    "enconvert": {
      "command": "npx",
      "args": ["-y", "@enconvert/mcp@latest"],
      "env": {
        "ENCONVERT_API_KEY": "sk_your_key"
      }
    }
  }
}

Sur Windows natif, remplacez command par cmd et ajoutez "/c", "npx" au début de args, car npx seul se bloque. Pour Claude Code :

claude mcp add enconvert -s user \
  -e ENCONVERT_API_KEY=sk_your_key \
  -- npx -y @enconvert/mcp@latest

Le bloc env inline est optionnel si vous avez déjà exécuté setup, car le serveur se rabat automatiquement sur la clé enregistrée.

Outils disponibles#

Vingt-quatre outils. Tout le travail sur URL/navigateur passe par les outils V2 (perceive_url et ses homologues) ; les outils de fichiers couvrent le travail sur documents, sur images et sur la compression, en local comme à distance.

Les descriptions d'outils suivent une structure cohérente Utiliser quand / Ne pas utiliser quand / Retourne afin que l'assistant oriente les prompts vers le bon outil. Les outils V2 nécessitent la clé API privée et sont soumis au plan tarifaire : une fonctionnalité désactivée ou un quota épuisé renvoie donc un message de quota clair, pas une erreur cryptique.

Deux comportements méritent d'être connus avant de les solliciter dans un prompt. compress_image ne change jamais le format (un PNG revient en PNG, un JPEG revient en JPEG) et ne renvoie jamais un fichier plus lourd que l'entrée, il est donc sans risque sur un fichier déjà optimisé ; target_size_kb est traité au mieux, et un budget hors d'atteinte renvoie le plus petit fichier obtenu plutôt qu'une erreur, vérifiez donc la taille du fichier renvoyé. Sur convert_image, width et height ne s'appliquent qu'aux entrées SVG et acceptent chacun une valeur de 1 à 10000 : n'en passer qu'un seul met la sortie à l'échelle proportionnellement d'après les proportions propres du SVG, tandis que passer les deux fixe exactement les dimensions de sortie.

Configuration#

La clé API est résolue dans cet ordre :

1. Variable d'environnement ENCONVERT_API_KEY (depuis la config MCP de l'assistant), qui prend toujours le dessus
2. ~/.enconvert/config.json, écrit par npx @enconvert/mcp setup

Exemples de prompts#

Une fois installé, essayez ceci dans une nouvelle session de l'assistant :

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'assistant choisit automatiquement le bon outil : le travail sur URL atterrit sur perceive_url, la recherche sur web_search, le scraping structuré sur extract_structured, les budgets de taille sur compress_image, le Markdown prêt pour le RAG sur convert_anything_to_markdown, et le reste du travail sur fichiers sur les outils de conversion.

Forme de la sortie#

Chaque outil retourne une réponse cohérente :

• Un résumé textuel avec les URLs de téléchargement et les métadonnées
• Un bloc structuredContent avec le résultat typé complet
• Un resource_link vers le fichier local lorsque save_to est fourni (outils de fichiers)
• Pour perceive_url, l'artefact markdown est aussi inliné dans la réponse (jusqu'à ~256 Ko), afin que l'assistant puisse lire et résumer sans requête séparée

Fonctionnement#

@enconvert/mcp appelle les mêmes endpoints REST publics documentés dans le reste de ce site, via le SDK Node.js. Cela signifie :

• Même format de transport : chaque outil correspond 1:1 à un endpoint /v1/convert/* ou /v2/*
• Même récupération de timeout : les conversions longues basculent automatiquement et de manière transparente sur le polling par job_id
• Même authentification : votre clé API privée autorise chaque appel, et votre quota et vos limites de débit du tableau de bord s'appliquent

L'assistant ne voit jamais la clé API. Il ne voit que la liste des outils et leurs entrées.

Dépannage#

L'assistant essaie d'utiliser un navigateur local au lieu de l'outil MCP. Le serveur MCP n'est pas enregistré ou n'a pas démarré. Exécutez npx @enconvert/mcp status dans un terminal classique, puis redémarrez l'assistant.

Authentication failed: Invalid or missing API key. Exécutez npx @enconvert/mcp status, qui indique d'où vient la clé et la valide en direct. Corrigez-la avec npx @enconvert/mcp rotate-key.

npx se bloque sur Windows natif. Utilisez cmd /c npx .... npx @enconvert/mcp setup écrit ce wrapper automatiquement sous Windows.

L'appel d'outil expire avant la fin de la conversion. Les rendus de navigateur lourds peuvent prendre 30 secondes ou plus. Le SDK attend jusqu'à 5 minutes par défaut ; augmentez le timeout par outil de l'assistant s'il coupe plus tôt.

Chemin relatif rejeté sur convert_document / convert_image. Passez un chemin absolu (par ex. /Users/me/file.docx ou C:\Users\me\file.docx), ou passez une URL http(s)://. Les serveurs MCP n'ont pas de répertoire de travail fiable.

Source et liens#

• npm : @enconvert/mcp
• GitHub : enconvert/mcp
• Licence : MIT
• SDK sous-jacent : SDK Node.js
• Spécification MCP : modelcontextprotocol.io

Questions fréquentes#

Comment configurer un serveur MCP en JSON ?#

Ajoutez une entrée sous mcpServers dans le fichier de config MCP de votre client (~/.cursor/mcp.json pour Cursor, ~/.codeium/windsurf/mcp_config.json pour Windsurf, claude_desktop_config.json pour Claude Desktop) avec "command": "npx", "args": ["-y", "@enconvert/mcp@latest"], et votre ENCONVERT_API_KEY dans le bloc env. Ou évitez complètement le JSON manuel : npx @enconvert/mcp setup détecte vos outils IA installés et écrit chaque config correctement.

Comment configurer un serveur MCP dans Claude Code ?#

Exécutez claude mcp add enconvert -s user -e ENCONVERT_API_KEY=sk_your_key -- npx -y @enconvert/mcp@latest, ou utilisez l'assistant interactif npx @enconvert/mcp setup, qui détecte Claude Code et le configure automatiquement. Redémarrez complètement l'assistant ensuite, car les serveurs MCP ne se chargent qu'au démarrage d'une session.

Pourquoi npx se bloque-t-il au démarrage d'un serveur MCP sous Windows ?#

npx seul se bloque sur Windows natif. Remplacez command par cmd et ajoutez "/c", "npx" au début de args ; npx @enconvert/mcp setup écrit ce wrapper automatiquement sous Windows.

Où le serveur MCP stocke-t-il ma clé API ?#

npx @enconvert/mcp setup stocke la clé une seule fois dans ~/.enconvert/config.json (mode de fichier 600) au lieu de la dupliquer dans la config en clair de chaque client. La variable d'environnement ENCONVERT_API_KEY la remplace toujours, et npx @enconvert/mcp rotate-key remplace la clé stockée pour tous les clients en une seule commande.

Un assistant IA peut-il convertir des fichiers via un serveur MCP ?#

Oui. L'outil convert_document convertit DOCX, XLSX, PPTX, ODT, Pages, Numbers, HTML, Markdown, CSV, JSON, XML, YAML et TOML entre formats (PDF par défaut). L'EPUB n'a pas de paire convert_document ; passez les fichiers .epub par convert_anything_to_pdf ou convert_anything_to_markdown. Par ailleurs, convert_image convertit entre JPEG, PNG, SVG, HEIC et WebP, plus la rastérisation PDF vers JPEG. Passez des chemins de fichiers absolus ou des URLs http(s)://, car les serveurs MCP n'ont pas de répertoire de travail fiable.

Comment réduire le poids d'une image sans changer son format ?#

Demandez à l'assistant de compresser le fichier et il s'oriente vers compress_image, qui laisse un PNG en PNG, un JPEG en JPEG et un WebP en WebP. Il supprime les métadonnées tout en conservant le profil ICC et l'orientation EXIF, et ne renvoie jamais un fichier plus lourd que l'entrée. Ajoutez un budget target_size_kb et il réduit les dimensions en verrouillant les proportions jusqu'à respecter le budget ; un budget hors d'atteinte renvoie le plus petit fichier obtenu plutôt qu'une erreur, vérifiez donc la taille renvoyée.