Instalación del servidor MCP y configuración en JSON#

@enconvert/mcp es el servidor oficial de Model Context Protocol (MCP) para EnConvert. Permite que cualquier asistente de IA compatible con MCP (Claude Code, Cursor, Windsurf, Claude Desktop, VS Code, Zed, Gemini CLI, Codex, OpenCode) renderice, busque, extraiga, ingiera, monitoree, convierta y comprima páginas web y archivos directamente desde el chat. Configúralo con un solo comando, npx @enconvert/mcp setup, o copia el bloque de configuración JSON exacto para el archivo de configuración MCP de tu cliente. Se ejecuta localmente sobre stdio en Node.js 18+ y registra veinticuatro herramientas.

¿Qué es MCP?#

El Model Context Protocol es un estándar abierto para exponer herramientas, prompts y recursos a asistentes basados en LLM a través de una interfaz JSON-RPC ligera. Un servidor MCP se ejecuta como un subproceso local, el asistente lo inicia al comenzar la sesión, y las herramientas se convierten en capacidades de primera clase que el modelo puede invocar durante una conversación.

@enconvert/mcp es un envoltorio ligero alrededor del SDK de Node.js. Registra veinticuatro herramientas, cada una con una descripción ajustada para una selección de herramientas fiable por parte del LLM. Todo el manejo de HTTP, autenticación, tiempo de espera y sondeo de recuperación se hereda del SDK.

Requisitos#

• Node.js 18 o posterior en la máquina que ejecuta el asistente
• Una clave de API privada de EnConvert (sk_...), que generas en el panel

Instalación: un solo comando#

npx @enconvert/mcp setup

El asistente interactivo lo hace todo:

1. Detecta tus herramientas de IA (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Zed, Gemini CLI, Codex CLI, OpenCode) y te deja elegir cuáles reciben EnConvert (las herramientas detectadas aparecen preseleccionadas).
2. Te pide tu clave de API secreta una sola vez (entrada oculta) y la valida en tiempo real contra la API. ¿Pegaste por error una clave pública? Te lo dice exactamente.
3. Escribe cada configuración correctamente, incluido el wrapper cmd /c npx que requiere 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.

Adminístralo con la misma facilidad#

Para scripting, setup --clients claude-code,cursor --api-key sk_... --yes omite todas las indicaciones. Ejecutar rotate-key sin ningún argumento solicita una entrada oculta, de modo que la clave nunca queda registrada en el historial de tu shell.

Dónde se almacena la clave#

setup almacena tu clave una sola vez en ~/.enconvert/config.json (modo de archivo 600) en lugar de duplicarla en la configuración en texto plano de cada cliente. El servidor la lee al iniciar; la variable de entorno ENCONVERT_API_KEY siempre tiene prioridad sobre ella (para Docker, CI o configuraciones manuales). Por lo tanto, rotar una clave es un cambio en un solo archivo, y cada cliente la recoge en su próximo inicio.

Avanzado: configuración manual#

¿Prefieres configurarlo tú mismo? Agrega esto a la configuración MCP de tu cliente (~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, el claude_desktop_config.json de Claude Desktop, ...):

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

En Windows nativo, reemplaza command por cmd y antepón "/c", "npx" a args, porque npx a secas se cuelga. Para Claude Code:

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

El bloque env en línea es opcional si ya ejecutaste setup, puesto que el servidor recurre automáticamente a la clave guardada.

Herramientas disponibles#

Veinticuatro herramientas. Todo el trabajo de URL/navegador pasa por las herramientas V2 (perceive_url y afines); las herramientas de archivos cubren el trabajo de conversión y compresión de documentos e imágenes, tanto locales como remotos.

Las descripciones de las herramientas siguen una estructura consistente de Use when / Do NOT use when / Returns para que el asistente dirija los prompts a la herramienta correcta. Las herramientas V2 requieren la clave de API privada y están limitadas por plan, de modo que una función desactivada o una cuota agotada devuelve un mensaje de cuota claro, no un error críptico.

Conviene conocer dos comportamientos antes de pedirlos desde el chat. compress_image nunca cambia el formato (un PNG vuelve como PNG y un JPEG vuelve como JPEG) y nunca devuelve un archivo más grande que la entrada, así que puedes ejecutarlo sin riesgo sobre un archivo ya optimizado; target_size_kb se aplica con el mejor esfuerzo, y un presupuesto inalcanzable devuelve el archivo más pequeño que se logró en lugar de un error, así que comprueba el tamaño del archivo que recibes. En convert_image, width y height se aplican solo a entradas SVG y aceptan de 1 a 10000 cada uno: pasar uno solo escala la salida proporcionalmente según la relación de aspecto del propio SVG, mientras que pasar ambos fija el lienzo exacto.

Configuración#

La clave de API se resuelve en este orden:

1. La variable de entorno ENCONVERT_API_KEY (desde la configuración MCP del asistente), que siempre tiene prioridad
2. ~/.enconvert/config.json, escrito por npx @enconvert/mcp setup

Prompts de ejemplo#

Una vez instalado, prueba esto en una sesión nueva del asistente:

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.

El asistente elige la herramienta correcta automáticamente: el trabajo de URL recae en perceive_url, la búsqueda en web_search, el scraping estructurado en extract_structured, los presupuestos de tamaño en compress_image, el Markdown listo para RAG en convert_anything_to_markdown, y el resto del trabajo con archivos en las herramientas de conversión.

Formato de la salida#

Cada herramienta devuelve una respuesta consistente:

• Un resumen de texto con URL de descarga y metadatos
• Un bloque structuredContent con el resultado tipado completo
• Un resource_link al archivo local cuando se proporciona save_to (herramientas de archivos)
• Para perceive_url, el artefacto markdown también se inserta en la respuesta (hasta ~256 KB), de modo que el asistente puede leerlo y resumirlo sin una solicitud aparte

Cómo funciona#

@enconvert/mcp llama a los mismos endpoints REST públicos documentados en el resto de este sitio, a través del SDK de Node.js. Esto significa:

• El mismo formato de transmisión: cada herramienta corresponde 1:1 a un endpoint /v1/convert/* o /v2/*
• La misma recuperación de tiempo de espera: las conversiones largas recurren automáticamente al sondeo de job_id, de forma transparente
• La misma autenticación: tu clave de API privada autoriza cada llamada, y se aplican la cuota y los límites de frecuencia de tu panel

El asistente nunca ve la clave de API. Solo ve la lista de herramientas y las entradas de las herramientas.

Solución de problemas#

El asistente intenta usar un navegador local en lugar de la herramienta MCP. El servidor MCP no está registrado o no se inició. Ejecuta npx @enconvert/mcp status en una terminal normal y luego reinicia el asistente.

Authentication failed: Invalid or missing API key. Ejecuta npx @enconvert/mcp status, que muestra de dónde viene la clave y la valida en tiempo real. Corrígelo con npx @enconvert/mcp rotate-key.

npx se cuelga en Windows nativo. Usa cmd /c npx .... npx @enconvert/mcp setup escribe este wrapper automáticamente en Windows.

La llamada a la herramienta expira antes de que termine la conversión. Los renderizados de navegador pesados pueden tardar más de 30 segundos. El SDK espera hasta 5 minutos por defecto; aumenta el tiempo de espera por herramienta del asistente si se corta antes.

Ruta relativa rechazada en convert_document / convert_image. Pasa una ruta absoluta (por ejemplo, /Users/me/file.docx o C:\Users\me\file.docx), o pasa una URL http(s)://. Los servidores MCP no tienen un directorio de trabajo confiable.

Fuente y enlaces#

• npm: @enconvert/mcp
• GitHub: enconvert/mcp
• Licencia: MIT
• SDK subyacente: SDK de Node.js
• Especificación de MCP: modelcontextprotocol.io

Preguntas frecuentes#

¿Cómo configuro un servidor MCP en JSON?#

Agrega una entrada bajo mcpServers en el archivo de configuración MCP de tu cliente (~/.cursor/mcp.json para Cursor, ~/.codeium/windsurf/mcp_config.json para Windsurf, claude_desktop_config.json para Claude Desktop) con "command": "npx", "args": ["-y", "@enconvert/mcp@latest"], y tu ENCONVERT_API_KEY en el bloque env. O evita el JSON manual por completo: npx @enconvert/mcp setup detecta tus herramientas de IA instaladas y escribe cada configuración correctamente.

¿Cómo configuro un servidor MCP en Claude Code?#

Ejecuta claude mcp add enconvert -s user -e ENCONVERT_API_KEY=sk_your_key -- npx -y @enconvert/mcp@latest, o usa el asistente interactivo npx @enconvert/mcp setup, que detecta Claude Code y lo configura automáticamente. Reinicia completamente el asistente después, porque los servidores MCP solo se cargan cuando se inicia una sesión.

¿Por qué se cuelga npx al iniciar un servidor MCP en Windows?#

npx a secas se cuelga en Windows nativo. Reemplaza command por cmd y antepón "/c", "npx" a args; npx @enconvert/mcp setup escribe este wrapper automáticamente en Windows.

¿Dónde almacena el servidor MCP mi clave de API?#

npx @enconvert/mcp setup almacena la clave una sola vez en ~/.enconvert/config.json (modo de archivo 600) en lugar de duplicarla en la configuración en texto plano de cada cliente. La variable de entorno ENCONVERT_API_KEY siempre tiene prioridad sobre ella, y npx @enconvert/mcp rotate-key reemplaza la clave almacenada para todos los clientes en un solo comando.

¿Puede un asistente de IA convertir archivos a través de un servidor MCP?#

Sí. La herramienta convert_document convierte entre DOCX, XLSX, PPTX, ODT, Pages, Numbers, HTML, Markdown, CSV, JSON, XML, YAML y TOML (PDF por defecto). EPUB no tiene un par en convert_document; envía los archivos .epub a convert_anything_to_pdf o convert_anything_to_markdown. Además, convert_image convierte entre JPEG, PNG, SVG, HEIC y WebP, además de rasterización de PDF a JPEG. Pasa rutas de archivo absolutas o URL http(s)://, ya que los servidores MCP no tienen un directorio de trabajo confiable.

¿Cómo reduzco el peso de una imagen sin cambiar su formato?#

Pídele al asistente que comprima el archivo y enrutará a compress_image, que mantiene un PNG como PNG, un JPEG como JPEG y un WebP como WebP. Elimina los metadatos conservando el perfil ICC y la orientación EXIF, y nunca devuelve un archivo más grande que la entrada. Añade un presupuesto target_size_kb y la imagen se reduce de escala con la relación de aspecto bloqueada hasta cumplirlo; un presupuesto inalcanzable devuelve el archivo más pequeño que se logró en lugar de un error, así que comprueba el tamaño que recibes.