ConverterHQDevelopers
API v1

Servidor MCP

Usa ConverterHQ desde agentes compatibles con MCP mediante OAuth delegado y Jobs duraderos.

El endpoint MCP alojado https://mcp.converterhq.io/mcp es un servidor Streamable HTTP sin estado sobre los mismos recursos de ConverterHQ que la API REST. OAuth de HQTools evita copiar claves API permanentes en clientes de IA.

Ruta de ejecución MCP
MCP client
HQTools OAuth
ConverterHQ MCP
JobTasks + attempts
MCP opera sobre los mismos recursos File, Job, Task, Workflow y Usage que REST.

Conectar

Añade https://mcp.converterhq.io/mcp como servidor Streamable HTTP. La matriz de lanzamiento solo admite MCP 2026-07-28: cada solicitud debe enviar la misma versión en la cabecera MCP-Protocol-Version y en params._meta["io.modelcontextprotocol/protocolVersion"]. Los clientes antiguos basados solo en initialize no forman parte de la matriz admitida. Incluye también params._meta["io.modelcontextprotocol/clientCapabilities"] como objeto ({} si no hay extensiones opcionales).

OAuth y scopes

El endpoint MCP acepta tokens OAuth delegados, no claves API permanentes de ConverterHQ. Leer una Task requiere converterhq.tasks.read y cancelarla requiere converterhq.jobs.write; por tanto, un grant de solo lectura no puede modificar la ejecución.

Catálogo de herramientas

Trece herramientas cubren conversión, estimación, formatos y capacidades, creación/validación/cancelación de Jobs, inspección de Tasks, Workflows y uso. convert_file acepta una URL HTTPS; para un archivo local o adjunto, súbelo primero mediante Files y la carga directa firmada, o usa una URL HTTPS proporcionada por el cliente.

Tasks duraderas

Los clientes que negocian la extensión MCP Tasks pueden recibir una task duradera asociada a un Job ConverterHQ y consultarla o cancelarla después. Los demás reciben el Job ID y usan get_job; la ejecución no necesita mantener abierta la llamada original.

Variables de Workflow

run_workflow acepta el mismo mapa de variables validado, client_reference_id y metadata que POST /v1/workflows/{id}/run. El esquema limita lo que un agente puede sustituir antes de crear el Job.

Operación segura

Usa scopes mínimos, aprobación humana antes de efectos externos sensibles cuando corresponda, conserva los Job IDs y revoca el grant OAuth cuando el cliente deje de ser confiable.