ConverterHQDevelopers
API v1

MCP-server

Gebruik ConverterHQ vanuit MCP-compatibele agents met gedelegeerde OAuth en duurzame Jobs.

Het gehoste MCP-endpoint https://mcp.converterhq.io/mcp is een stateless Streamable HTTP-server boven dezelfde ConverterHQ-resources als de REST API. HQTools OAuth houdt permanente API-keys uit AI-clients.

MCP-uitvoeringspad
MCP client
HQTools OAuth
ConverterHQ MCP
JobTasks + attempts
MCP gebruikt dezelfde File-, Job-, Task-, Workflow- en Usage-resources als REST.

Verbinden

Voeg https://mcp.converterhq.io/mcp toe als Streamable HTTP-server. De launchmatrix ondersteunt alleen MCP 2026-07-28: elk verzoek moet dezelfde versie sturen in de header MCP-Protocol-Version en in params._meta["io.modelcontextprotocol/protocolVersion"]. Oudere clients die alleen initialize gebruiken vallen buiten de ondersteunde matrix. Stuur ook params._meta["io.modelcontextprotocol/clientCapabilities"] als object ({} zonder optionele extensies).

OAuth en scopes

Het MCP-endpoint accepteert gedelegeerde OAuth-tokens, geen permanente ConverterHQ API-sleutels. Een Task lezen vereist converterhq.tasks.read en annuleren vereist converterhq.jobs.write; een alleen-lezen grant kan de uitvoering dus niet wijzigen.

Toolcatalogus

Dertien tools dekken conversie, schatting, formaten en capabilities, Job-aanmaak/-validatie/-annulering, Task-inspectie, Workflows en gebruik. convert_file accepteert een HTTPS-URL; upload een lokaal bestand of bijlage eerst via de Files API en de getekende directe upload, of gebruik een HTTPS-URL van de client.

Duurzame Tasks

Clients die de MCP Tasks-extensie onderhandelen kunnen een duurzame task ontvangen die op een ConverterHQ Job is gemapt en die later inspecteren of annuleren. Andere clients gebruiken Job-ID en get_job; uitvoering vereist geen open oorspronkelijke toolcall.

Workflowvariabelen

run_workflow accepteert dezelfde gevalideerde variabelenmap, client_reference_id en metadata als POST /v1/workflows/{id}/run. Het schema beperkt wat een agent mag substitueren voordat de Job wordt gemaakt.

Veilig beheren

Gebruik minimale OAuth-scopes, menselijke goedkeuring voor gevoelige externe effecten wanneer nodig, bewaar Job-ID’s en trek de OAuth-grant in wanneer de client niet langer vertrouwd is.