--- seo_title: REST, MCP, CLI o SDK: Cuál Elegir | EnConvert meta_desc: EnConvert expone la misma API mediante REST, un servidor MCP, una CLI, un nodo de n8n y diez SDK. Cómo se relacionan estas superficies y cuándo elegir cada una. keywords: rest vs servidor mcp, superficies de acceso a la api, servidor mcp o api rest, cli o sdk, una sola clave de api para todo, integraciones de enconvert, nodo de n8n vs api, cuándo usar un sdk --- # Una API, Cinco Formas de Llamarla EnConvert es una única API HTTP en `https://api.enconvert.com`. El servidor MCP, la CLI, el nodo de n8n y los diez SDK son clientes de esa API, no productos aparte. Llaman a los mismos endpoints con la misma clave. ## REST es el sustrato Toda llamada acaba con la misma forma: una solicitud HTTPS a `https://api.enconvert.com` con una cabecera `X-API-Key`. El gateway no puede saber qué cliente la envió más allá de la cadena `User-Agent`, y esa cadena existe solo por atribución: cada SDK envía `enconvert-sdk/ ()` para poder contar el tráfico por lenguaje. Ningún cliente tiene un endpoint propio. No hay ninguna operación de la API accesible desde la CLI o el servidor MCP que no puedas lanzar con `curl` y las páginas de este sitio. Lo contrario conviene decirlo con claridad, porque es donde la gente se lleva sorpresas: los clientes envuelven REST con distinta profundidad. - La **CLI** es la más amplia. Tiene verbos para las rutas de conversión y para perceive, discover, lookup, distill e ingest, además de `enconvert api` como passthrough al estilo de gh que alcanza cualquier cosa para la que todavía no tenga un verbo. - El **servidor MCP** registra 24 herramientas. Deja fuera deliberadamente los endpoints del secreto de firma de webhooks (`GET /v2/ingest/webhook-secret` y su equivalente de rotación), porque un modelo no debería poder leer un secreto de firma. - El **nodo de n8n** expone 6 recursos y 16 operaciones, pensados para pasos de un flujo de trabajo más que para cubrir la API entera. - Los **SDK** cubren los endpoints de conversión y los endpoints web de V2 en los diez lenguajes. Cuando un cliente es más estrecho que la API, baja a REST para esa llamada concreta. Mezclar no es problema. Las llamadas del SDK y las llamadas HTTP hechas a mano pueden compartir proyecto y clave sin ningún tratamiento especial. --- ## Una clave, todas las superficies Todas las superficies se autentican con la misma clave de API privada (`sk_...`), enviada en la cabecera `X-API-Key`. Genera una en el [panel](/es/dashboard) y funciona en `curl`, en `enconvert auth login`, en una configuración de MCP, en una credencial de n8n y en el constructor de un SDK. Rotarla las rota todas. Lo único que cambia es dónde se guarda la clave. | Superficie | Dónde vive la clave | Variable de entorno que la sobrescribe | |---------|---------------------|----------------------| | REST | Donde tu propio código guarde los secretos | -- | | SDK | Se pasa al constructor del cliente | -- | | CLI | `credentials.toml`, modo de archivo `0600` | `ENCONVERT_API_KEY` | | Servidor MCP | `~/.enconvert/config.json`, modo de archivo `600` | `ENCONVERT_API_KEY` | | Nodo de n8n | La credencial `enconvertApi` dentro de n8n | -- |
Estas superficies necesitan una clave privada. La CLI, el servidor MCP, el nodo de n8n y los SDK esperan todos sk_.... Una clave pública pk_ es para código de navegador que acuña un JWT de corta duración, y la credencial de n8n rechaza de plano las claves pk_. Consulta Autenticación.
El consumo también es compartido. Una sola cuota mensual de operaciones cubre todas las superficies, y una operación cuesta lo mismo llegue desde un programa en Go o desde un terminal. Consulta [Límites de frecuencia y cuotas](/es/docs/reference/rate-limits.md). --- ## Cuándo elegir cada una | Superficie | Qué es | Recurre a ella cuando | |---------|-----------|-------------------| | REST | La API en sí: cuerpos JSON y multipart sobre HTTPS | Escribes código de aplicación, no quieres ninguna dependencia, o tu lenguaje no tiene SDK | | SDK | Clientes tipados para diez lenguajes | Quieres autocompletado en cada parámetro y recuperación ante timeouts que no has tenido que escribir | | CLI | El binario `enconvert`, desde Homebrew, Scoop, un instalador de shell o npm | Escribes un script de shell, ejecutas un trabajo puntual, o trabajas en CI | | Servidor MCP | `@enconvert/mcp`, un servidor stdio local para asistentes de IA | Un agente de programación debe decidir por sí mismo cuándo llamar a la API | | Nodo de n8n | `@enconvert/n8n-nodes-enconvert`, un nodo de la comunidad | El flujo de trabajo ya vive en n8n y quieres el resultado como datos binarios de n8n | Dos de estas elecciones suelen ser obvias. Si quien escribe es una persona, es la CLI; si quien decide es un modelo, es MCP. La pregunta REST o SDK es la única que merece reflexión, y depende de cuánto código de reintentos y sondeo quieras mantener tú. --- ## La misma lectura, de tres formas Leer `https://example.com/pricing` y convertirlo en Markdown es una sola solicitud `POST /v2/perceive`. Así queda en HTTP en bruto: ```bash curl -X POST https://api.enconvert.com/v2/perceive \ -H "X-API-Key: sk_your_private_key" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/pricing", "outputs": ["markdown"] }' ``` La CLI lanza ese mismo `POST /v2/perceive`. El comando sin opciones no envía `outputs`, así que recibe el valor por defecto del servidor: Markdown más el bloque estructurado inline: ```bash enconvert perceive https://example.com/pricing ``` Con MCP no escribes la llamada en absoluto. Le pides al asistente que lea la página, él elige la herramienta `perceive_url`, y los argumentos que importan salen así: ```json { "name": "perceive_url", "arguments": { "url": "https://example.com/pricing", "outputs": ["markdown"] } } ```
Misma solicitud, mismo coste. Cada una de las tres renderiza la página una vez y cuesta una operación. El servidor MCP hace además una cosa más: descarga el artefacto Markdown terminado e incrusta el texto en el resultado de la herramienta (hasta unos 256 KB), para que el asistente pueda leer la página sin un segundo fetch.
--- ## Qué sigue La configuración está en las guías de integración, una página por superficie: - **[Integraciones](/es/docs/guides/integrations.md)** es el hub, y cubre también los widgets web incrustables. - **[Configuración de MCP](/es/docs/guides/integrations/mcp-setup.md)** instala `@enconvert/mcp` en Claude Code, Cursor, Windsurf y otros seis clientes con `npx @enconvert/mcp setup`. - **[n8n](/es/docs/guides/integrations/n8n.md)** instala el nodo de la comunidad y recorre los seis recursos. - **[CLI](/es/docs/guides/integrations/cli.md)** cubre la instalación, `enconvert auth login`, los flags para scripting y los códigos de salida. - **[SDK](/es/docs/guides/integrations/sdks.md)** lista los diez paquetes, con una página cada uno. Para la API en sí, [Endpoints](/es/docs/endpoints.md) es la referencia y [Autenticación](/es/docs/authentication.md) explica los dos tipos de clave. --- ## Preguntas frecuentes ### ¿Es el servidor MCP una API distinta de la API REST? No. `@enconvert/mcp` es un proceso stdio local que llama a los mismos endpoints REST públicos documentados en este sitio, usando tu clave de API privada. Cada herramienta se corresponde con una solicitud `/v1/convert/*` o `/v2/*`, así que consume la misma cuota y devuelve los mismos errores. ### ¿Necesito claves de API separadas para la CLI, MCP y mi aplicación? No. Una sola clave privada (`sk_...`) autentica todas, y puedes reutilizar la misma clave en todas las superficies. Aun así, tener claves separadas sirve si quieres revocar una superficie sin tocar las demás; por ejemplo, una clave de CI que puedas rotar de forma independiente a la de tu portátil. ### ¿Puedo usar una clave pública pk_ con la CLI o un SDK? No. Las claves públicas existen para el código de navegador, donde acuñan un JWT de corta duración en lugar de enviarse directamente. La CLI, el servidor MCP, el nodo de n8n y los SDK esperan todos una clave privada `sk_...`, y la credencial de n8n rechaza una clave `pk_` en el momento de la validación. ### ¿Hay algo disponible solo a través de los SDK o solo a través de la CLI? Ninguna operación de la API lo está. Lo que añaden los SDK es del lado del cliente: opciones con tipos seguros, descargas en streaming a disco, y paso automático al sondeo de `GET /v1/convert/status/{job_id}` cuando una conversión larga supera el timeout del proxy. Todo eso puedes escribirlo tú mismo contra REST en bruto. ### ¿Qué superficie debería usar dentro de un pipeline de CI? La CLI, con `ENCONVERT_API_KEY` tomada del almacén de secretos de tu CI y `--no-input` para que ningún prompt pueda bloquear la ejecución. Sus códigos de salida son un contrato publicado y estable, así que una conversión fallida hace fallar el paso sin tener que analizar la salida.