ConverterHQDevelopers
API v1

Serwer MCP

Używaj ConverterHQ z agentów zgodnych z MCP przez delegated OAuth i trwałe Jobs.

Hostowany endpoint MCP https://mcp.converterhq.io/mcp to stateless Streamable HTTP server oparty na tych samych zasobach ConverterHQ co REST API. OAuth HQTools utrzymuje trwałe API keys poza klientami AI.

Ścieżka wykonania MCP
MCP client
HQTools OAuth
ConverterHQ MCP
JobTasks + attempts
MCP działa na tych samych zasobach File, Job, Task, Workflow i Usage co REST.

Połączenie

Dodaj https://mcp.converterhq.io/mcp jako serwer Streamable HTTP. Macierz uruchomieniowa obsługuje wyłącznie MCP 2026-07-28: każde żądanie musi wysłać tę samą wersję w nagłówku MCP-Protocol-Version oraz w params._meta["io.modelcontextprotocol/protocolVersion"]. Starsze klienty korzystające wyłącznie z initialize nie należą do obsługiwanej macierzy. Przekaż także params._meta["io.modelcontextprotocol/clientCapabilities"] jako obiekt ({} bez opcjonalnych rozszerzeń).

OAuth i scope’y

Endpoint MCP przyjmuje delegowane tokeny OAuth, a nie stałe klucze API ConverterHQ. Odczyt Task wymaga converterhq.tasks.read, a anulowanie converterhq.jobs.write; grant tylko do odczytu nie może więc zmienić wykonania.

Katalog narzędzi

Trzynaście narzędzi obejmuje konwersję, estymację, formaty i capabilities, tworzenie/walidację/anulowanie Jobs, inspekcję Tasks, Workflows i użycie. convert_file przyjmuje URL HTTPS; lokalny plik lub załącznik najpierw wyślij przez Files API i podpisany bezpośredni upload albo użyj URL HTTPS dostarczonego przez klienta.

Trwałe Tasks

Klienci negocjujący rozszerzenie MCP Tasks mogą dostać trwałą task mapowaną na Job i później ją sprawdzić lub anulować. Pozostali dostają Job ID i używają get_job; wykonanie nie wymaga otwartej pierwotnej tool call.

Zmienne Workflow

run_workflow akceptuje tę samą zwalidowaną mapę variables, client_reference_id i metadata co POST /v1/workflows/{id}/run. Schema ogranicza to, co agent może podstawić przed utworzeniem Job.

Bezpieczna eksploatacja

Używaj minimalnych OAuth scopes, wymagaj ludzkiej akceptacji przed wrażliwymi efektami zewnętrznymi gdy trzeba, zapisuj Job ID i unieważnij OAuth grant, gdy klient nie jest już zaufany.