ConverterHQDevelopers
API v1

Servidor MCP

Use o ConverterHQ em agentes compatíveis com MCP com OAuth delegado e Jobs duráveis.

O endpoint MCP hospedado https://mcp.converterhq.io/mcp é um servidor Streamable HTTP stateless sobre os mesmos recursos do ConverterHQ usados pela API REST. OAuth do HQTools mantém chaves API permanentes fora de clientes de IA.

Fluxo de execução MCP
MCP client
HQTools OAuth
ConverterHQ MCP
JobTasks + attempts
MCP opera sobre os mesmos recursos File, Job, Task, Workflow e Usage do REST.

Conectar

Adicione https://mcp.converterhq.io/mcp como servidor Streamable HTTP. A matriz de lançamento aceita somente MCP 2026-07-28: cada requisição deve enviar a mesma versão no cabeçalho MCP-Protocol-Version e em params._meta["io.modelcontextprotocol/protocolVersion"]. Clientes antigos baseados apenas em initialize não fazem parte da matriz suportada. Inclua também params._meta["io.modelcontextprotocol/clientCapabilities"] como objeto ({} sem extensões opcionais).

OAuth e scopes

O endpoint MCP aceita tokens OAuth delegados, não chaves permanentes da API ConverterHQ. Ler uma Task exige converterhq.tasks.read e cancelá-la exige converterhq.jobs.write; portanto, um grant somente de leitura não pode alterar a execução.

Catálogo de ferramentas

Treze ferramentas cobrem conversão, estimativa, formatos e capabilities, criação/validação/cancelamento de Jobs, inspeção de Tasks, Workflows e uso. convert_file aceita uma URL HTTPS; para arquivo local ou anexo, faça primeiro o upload pela API Files e fluxo direto assinado, ou use uma URL HTTPS fornecida pelo cliente.

Tasks duráveis

Clientes que negociam a extensão MCP Tasks podem receber uma task durável mapeada para um Job e consultá-la ou cancelá-la depois. Outros recebem o Job ID e usam get_job; a execução não exige manter a chamada inicial aberta.

Variáveis de Workflow

run_workflow aceita o mesmo mapa de variáveis validado, client_reference_id e metadata que POST /v1/workflows/{id}/run. O schema limita o que um agente pode substituir antes de criar o Job.

Operação segura

Use scopes mínimos, aprovação humana antes de efeitos externos sensíveis quando necessário, persista Job IDs e revogue o grant OAuth quando o cliente deixar de ser confiável.