ConverterHQDevelopers
API v1

Serveur MCP

Utilisez ConverterHQ depuis des agents compatibles MCP avec OAuth délégué et des Jobs durables.

Le endpoint MCP hébergé https://mcp.converterhq.io/mcp est un serveur Streamable HTTP stateless adossé aux mêmes ressources ConverterHQ que l’API REST. OAuth HQTools évite de copier des clés API permanentes dans un client IA.

Chemin d’exécution MCP
MCP client
HQTools OAuth
ConverterHQ MCP
JobTasks + attempts
MCP utilise les mêmes ressources File, Job, Task, Workflow et Usage que REST.

Connexion

Ajoutez https://mcp.converterhq.io/mcp comme serveur Streamable HTTP. La matrice de lancement prend en charge uniquement MCP 2026-07-28 : chaque requête doit fournir cette même version dans l’en-tête MCP-Protocol-Version et dans params._meta["io.modelcontextprotocol/protocolVersion"]. Les anciens clients basés uniquement sur initialize ne font pas partie de la matrice prise en charge. Fournissez aussi params._meta["io.modelcontextprotocol/clientCapabilities"] sous forme d’objet ({} sans extension facultative).

OAuth et scopes

Le endpoint MCP accepte des jetons OAuth délégués, pas des clés API ConverterHQ permanentes. La lecture d’une Task exige converterhq.tasks.read et son annulation exige converterhq.jobs.write ; un grant en lecture seule ne peut donc pas modifier l’exécution.

Catalogue d’outils

Treize outils couvrent conversion, estimation, formats et capabilities, création/validation/annulation de Jobs, inspection de Tasks, liste/exécution de Workflows et consultation de l’usage. convert_file accepte une URL HTTPS : pour un fichier local ou une pièce jointe, utilisez d’abord l’API Files et l’upload direct signé, ou une URL HTTPS fournie par le client.

Tasks durables

Les clients qui négocient l’extension MCP Tasks peuvent recevoir une task durable mappée sur un Job ConverterHQ puis l’inspecter ou l’annuler. Les autres reçoivent le Job ID et utilisent get_job; l’exécution continue sans maintenir l’appel initial ouvert.

Variables de Workflow

run_workflow accepte la même map de variables validées, client_reference_id et metadata que POST /v1/workflows/{id}/run. Le schéma du Workflow limite ce qu’un agent peut substituer avant la création du Job.

Exploitation sûre

Utilisez des scopes OAuth minimaux, conservez une approbation humaine avant les effets externes sensibles si votre agent l’exige, enregistrez les Job IDs et révoquez le grant OAuth lorsque le client n’est plus fiable.