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/<version> (<language>) 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 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.

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:

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:

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í:

{
  "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 el hub, y cubre también los widgets web incrustables.
Configuración de MCP instala @enconvert/mcp en Claude Code, Cursor, Windsurf y otros seis clientes con npx @enconvert/mcp setup.
n8n instala el nodo de la comunidad y recorre los seis recursos.
CLI cubre la instalación, enconvert auth login, los flags para scripting y los códigos de salida.
SDK lista los diez paquetes, con una página cada uno.

Para la API en sí, Endpoints es la referencia y Autenticación 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.

← Concepts Sync and Async Jobs →

API Documentation