ConverterHQDevelopers
API v1

Server MCP

Gunakan ConverterHQ dari agent kompatibel MCP melalui delegated OAuth dan Job durable.

Endpoint MCP hosted https://mcp.converterhq.io/mcp adalah server Streamable HTTP stateless di atas resource ConverterHQ yang sama dengan REST API. OAuth HQTools menjaga API key permanen tetap di luar klien AI.

Alur eksekusi MCP
MCP client
HQTools OAuth
ConverterHQ MCP
JobTasks + attempts
MCP memakai resource File, Job, Task, Workflow, dan Usage yang sama dengan REST.

Menghubungkan

Tambahkan https://mcp.converterhq.io/mcp sebagai server Streamable HTTP. Matriks peluncuran hanya mendukung MCP 2026-07-28: setiap permintaan harus mengirim versi yang sama pada header MCP-Protocol-Version dan params._meta["io.modelcontextprotocol/protocolVersion"]. Klien lama yang hanya memakai initialize tidak termasuk matriks yang didukung. Sertakan juga params._meta["io.modelcontextprotocol/clientCapabilities"] sebagai objek ({} tanpa ekstensi opsional).

OAuth dan scope

Endpoint MCP menerima token OAuth terdelegasi, bukan kunci API ConverterHQ permanen. Membaca Task memerlukan converterhq.tasks.read dan membatalkannya memerlukan converterhq.jobs.write; grant hanya-baca tidak dapat mengubah eksekusi.

Katalog tool

Tiga belas alat mencakup konversi, estimasi, format dan capability, pembuatan/validasi/pembatalan Job, inspeksi Task, Workflow dan penggunaan. convert_file menerima URL HTTPS; untuk file lokal atau lampiran, unggah dahulu lewat Files API dan alur unggah langsung bertanda tangan, atau gunakan URL HTTPS dari klien.

Tasks durable

Klien yang menegosiasikan ekstensi MCP Tasks dapat menerima task durable yang dipetakan ke Job lalu memeriksa atau membatalkannya. Klien lain menerima Job ID dan memakai get_job; eksekusi tidak memerlukan panggilan awal tetap terbuka.

Variabel Workflow

run_workflow menerima map variabel tervalidasi, client_reference_id, dan metadata yang sama seperti POST /v1/workflows/{id}/run. Schema membatasi apa yang dapat disubstitusi agent sebelum Job dibuat.

Operasi aman

Gunakan scope minimum, persetujuan manusia sebelum side effect eksternal sensitif bila perlu, simpan Job ID, dan cabut OAuth grant ketika klien tidak lagi dipercaya.