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.
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.