ConverterHQDevelopers
API v1

Server MCP

Usa ConverterHQ da agent compatibili MCP con OAuth delegato e Job durevoli.

L’endpoint MCP ospitato https://mcp.converterhq.io/mcp è un server Streamable HTTP stateless sopra le stesse risorse ConverterHQ dell’API REST. OAuth HQTools evita di copiare API key permanenti nei client AI.

Percorso di esecuzione MCP
MCP client
HQTools OAuth
ConverterHQ MCP
JobTasks + attempts
MCP opera sulle stesse risorse File, Job, Task, Workflow e Usage di REST.

Connessione

Aggiungi https://mcp.converterhq.io/mcp come server Streamable HTTP. La matrice di lancio supporta solo MCP 2026-07-28: ogni richiesta deve inviare la stessa versione nell’header MCP-Protocol-Version e in params._meta["io.modelcontextprotocol/protocolVersion"]. I client legacy basati solo su initialize non fanno parte della matrice supportata. Invia anche params._meta["io.modelcontextprotocol/clientCapabilities"] come oggetto ({} senza estensioni opzionali).

OAuth e scope

L’endpoint MCP accetta token OAuth delegati, non chiavi API ConverterHQ permanenti. Leggere una Task richiede converterhq.tasks.read e annullarla richiede converterhq.jobs.write; un grant di sola lettura non può quindi modificare l’esecuzione.

Catalogo strumenti

Tredici strumenti coprono conversione, stima, formati e capabilities, creazione/validazione/annullamento dei Job, ispezione delle Task, Workflows e usage. convert_file accetta un URL HTTPS; per un file locale o allegato, caricalo prima tramite Files API e upload diretto firmato, oppure usa un URL HTTPS fornito dal client.

Tasks durevoli

I client che negoziano l’estensione MCP Tasks possono ricevere una task durevole mappata su un Job e poi ispezionarla o cancellarla. Gli altri ricevono il Job ID e usano get_job; l’esecuzione non richiede che la chiamata iniziale resti aperta.

Variabili Workflow

run_workflow accetta la stessa mappa di variabili validata, client_reference_id e metadata di POST /v1/workflows/{id}/run. Lo schema limita ciò che un agent può sostituire prima della creazione del Job.

Operare in sicurezza

Usa scope OAuth minimi, approvazione umana prima di effetti esterni sensibili quando serve, conserva i Job ID e revoca il grant OAuth quando il client non è più affidabile.