ConverterHQDevelopers
Documentation

MCP server

Use ConverterHQ from MCP-compatible agents through delegated OAuth and durable Jobs.

The hosted MCP endpoint is https://mcp.converterhq.io/mcp. It is a stateless Streamable HTTP endpoint backed by the same ConverterHQ resources as the REST API. Delegated HQTools OAuth keeps permanent API keys out of AI clients.

MCP execution path
MCP clientAgent or desktop client
HQTools OAuthConsent + scoped token
ConverterHQ MCPDiscovery + tool calls
Durable JobTasks + attempts
MCP is an integration surface over the same File, Job, Task, Workflow and Usage resources—not a separate conversion engine.

Connect

Add https://mcp.converterhq.io/mcp as a Streamable HTTP server. ConverterHQ exposes OAuth protected-resource metadata, supports server/discover, and currently supports the2026-07-28 MCP protocol. Every request must send that same version in the MCP-Protocol-Version header and inparams._meta["io.modelcontextprotocol/protocolVersion"], together with a client-capabilities object. Older initialize-style clients are not part of the supported launch matrix.

MCP discovery
POST /mcp HTTP/1.1
Host: mcp.converterhq.io
MCP-Protocol-Version: 2026-07-28
Mcp-Method: server/discover

OAuth and scopes

The MCP endpoint accepts delegated OAuth access tokens, not permanent ConverterHQ API keys. Request only the scopes the agent needs: capability discovery, Job/Task operations, Workflows and Usage are independently authorized.

Tool catalog

ConverterHQ exposes 13 tools: convert_file, estimate_conversion, list_formats, get_conversion_capability, list_conversion_capabilities, create_job, validate_job, get_job, cancel_job, get_task, list_workflows, run_workflow and get_usage. Capability tools are safe for planning; execution tools create the same durable resources visible in REST and the developer workspace.

Durable Tasks

Clients negotiating the MCP Tasks extension can receive a durable MCP task mapped to a ConverterHQ Job and later call the Tasks methods to inspect or cancel it. Clients without the extension receive the Job handle and can continue with get_job. The original tool call does not need to remain connected for conversion execution to finish.

Workflow variables

run_workflow accepts the same validated variable map, client_reference_id and metadata as POST /v1/workflows/{id}/run. Variable schemas constrain what an agent can substitute before the Job is created.

Operating safely

Use least-privilege OAuth scopes, keep human approval in front of sensitive external side effects where your agent requires it, persist returned Job IDs, and use authoritative REST/Job state for support and recovery. Revoke the OAuth grant when the client is no longer trusted.