--- seo_title: Configurar servidor MCP en JSON: Claude Code y Cursor | EnConvert meta_desc: Configura el servidor @enconvert/mcp en Claude Code, Cursor, Windsurf y Claude Desktop con la configuración JSON exacta o un solo comando: npx @enconvert/mcp setup. keywords: cómo configurar un servidor mcp en json, servidor mcp para conversión de archivos, configurar servidor mcp en claude code, configuración json de mcp para cursor, instalar servidor mcp en claude desktop, configurar mcp en windsurf, configurar servidor mcp con npx, model context protocol conversor de archivos, servidor mcp de enconvert, herramienta mcp para comprimir imágenes, mcp de pdf a markdown para rag --- # 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.
npm: @enconvert/mcp · Fuente: enconvert/mcp · Node: 18+ · Transporte: stdio
--- ## ¿Qué es MCP? El [Model Context Protocol](https://modelcontextprotocol.io) 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](/es/docs/guides/integrations/sdks/nodejs.md). 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](/es/dashboard) --- ## Instalación: un solo comando ```bash 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. ```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. ```
Es necesario reiniciar. Los servidores MCP solo se cargan cuando se inicia una sesión del asistente. Después de la configuración, cierra completamente el asistente y vuelve a abrirlo antes de probar.
### Adminístralo con la misma facilidad | Comando | Qué hace | |---------|-------------| | `npx @enconvert/mcp status` | Muestra dónde está instalado el servidor y valida tu clave en tiempo real | | `npx @enconvert/mcp rotate-key` | Reemplaza la clave de API almacenada con un solo comando, aplicado a todos los clientes | | `npx @enconvert/mcp remove` | Desinstala de las herramientas seleccionadas (opcionalmente elimina la clave guardada) | | `npx @enconvert/mcp setup --yes` | No interactivo: configura todas las herramientas detectadas con la clave guardada | | `npx @enconvert/mcp upgrade` | Comprueba en npm si hay una versión más reciente y la actualiza. Añade `--dry-run` para previsualizar | 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, ...): ```json { "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: ```bash 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. | Herramienta | Propósito | |------|---------| | `perceive_url` | Renderiza una página en vivo en múltiples artefactos a la vez: markdown (insertado), HTML, capturas de pantalla, PDF, enlaces, imágenes, más extracción estructurada, con caché de ~1h | | `get_perceive_operation` / `perceive_batch` / `get_perceive_batch` | Vuelve a firmar las URL de artefactos; renderiza hasta 1000 URL en un solo lote; consulta el estado de lotes | | `discover_urls` | Enumera las URL de un sitio mediante sitemap/crawl/hybrid, sin renderizar | | `web_search` | Búsqueda basada en Google en seis categorías, con renderizado automático opcional de los mejores resultados | | `extract_structured` | Extracción de datos basada en esquema (pase CSS gratuito + escalado a LLM) de hasta 50 URL | | `start_ingest` + herramientas de trabajos | Convierte un sitio o una lista de URL en JSONL fragmentado listo para RAG (asíncrono), con list/get/cancel/webhook-retry | | `create_watcher` + herramientas de monitoreo | Monitorea páginas en busca de cambios con una cadencia de una hora o más, con historial de diferencias, list/get/update/delete | | `convert_document` | Convierte entre DOCX, XLSX, PPTX, ODT, Pages, Numbers, HTML, Markdown, CSV, JSON, XML, YAML, TOML (PDF por defecto) | | `convert_image` | Convierte entre JPEG, PNG, SVG, HEIC, WebP, además de rasterización de PDF → JPEG, con `width` y `height` opcionales para dimensionar el lienzo al rasterizar un SVG | | `compress_image` | Reduce el peso de un PNG, JPEG o WebP sin cambiar el formato, opcionalmente hasta un tamaño objetivo en KB | | `convert_anything_to_markdown` | Convierte archivos PDF, de Office, ODF, EPUB, HTML, CSV o de texto en Markdown limpio con reconocimiento de encabezados para pipelines de RAG | | `convert_anything_to_pdf` | Convierte casi cualquier archivo a PDF: Office, ODF, iWork, imágenes, SVG, HTML, Markdown, EPUB, RTF, CSV, además de PDF que se devuelve tal cual | | `get_job_status` | Consulta el estado de un trabajo de conversión de archivos mediante su ID de trabajo | 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` | Configuración | Obligatorio | Predeterminado | Propósito | |----------|----------|---------|---------| | `ENCONVERT_API_KEY` (env) o `api_key` (archivo de configuración) | Sí | -- | Clave de API privada (`sk_...`) | | `ENCONVERT_BASE_URL` (env) o `base_url` (archivo de configuración) | No | `https://api.enconvert.com` | Anulación para entornos de staging o gateways autoalojados |
Nunca pegues una clave en el chat del asistente. Usa npx @enconvert/mcp setup (entrada oculta), o configúrala mediante el bloque env en el archivo de configuración MCP. Las claves incluidas en el historial del chat terminan en las transcripciones.
--- ## Prompts de ejemplo Una vez instalado, prueba esto en una sesión nueva del asistente: ```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. ``` 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](/es/docs/guides/integrations/sdks/nodejs.md). 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](https://www.npmjs.com/package/@enconvert/mcp) - **GitHub**: [enconvert/mcp](https://github.com/enconvert/mcp) - **Licencia**: MIT - **SDK subyacente**: [SDK de Node.js](/es/docs/guides/integrations/sdks/nodejs.md) - **Especificación de MCP**: [modelcontextprotocol.io](https://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.