같은 연산, 네 가지 클라이언트: 브라우저, curl, MCP, pdfx
같은 PDF123 병합을 네 가지 클라이언트로: 브라우저 폼, /api/v1/general/merge-pdfs로 가는 curl, /mcp의 MCP, 그리고 API base를 향하는 pdfx CLI입니다.

네 가지 클라이언트는 네 개의 제품처럼 보입니다. 하지만 하나의 카탈로그를 공유합니다. 구체적인 작업으로 PDF 병합을 보면, 페이지를 이미지로 래스터화하지 않고 업로드 순서대로 PDF를 합칩니다. 다른 카탈로그 도구(압축, OCR, 변환 등)도 같은 패턴입니다. 하나의 op id, 네 가지 호출 방식입니다.
브라우저
/merge를 열고, 원하는 순서로 파일을 추가하고, Process를 누르고, 내려받습니다. 카탈로그 도구에는 계정이 필요 없습니다. 페이지의 “Call this from code” 블록은 폼이 보내는 것과 같은 필드로 curl을 만들므로 UI와 HTTP 계약이 계속 맞춰집니다.
그 블록은 마케팅 문구가 아닙니다. 포털이 폼에 이미 쓰는 도구 정의에서 생성되므로, 매개변수 이름을 바꾸면 두 곳에 함께 나타납니다. 폼이 선택 사항인 sortType=byFileName을 받으면 curl 예제도 같은 필드를 담을 수 있습니다.
curl / REST
curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
-F "[email protected]" \
-F "[email protected]" \
-o merged.pdf
익명 카탈로그 호출에는 키가 필요 없습니다. 개발자에서 발급하는 키는 자동화에 안정적인 신원을 주고, 자체 호스팅 서버에는 문지기를 둡니다. OpenAPI는 /v1/openapi.json에 있습니다.
여러 단계 작업은 POST /api/v1/pipeline이 steps 필드에 순서 있는 op를 받습니다(예: 병합, 그다음 워터마크, 그다음 압축). 재시도가 같은 작업을 두 번 돌리면 안 될 때 Idempotency-Key를 보내세요. 성공한 재생은 Idempotency-Replayed와 함께 돌아올 수 있습니다. 실패는 rate_limited, bad_request 같은 안정적인 코드를 담은 application/problem+json입니다(개발자 오류).
호스팅 응답은 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset도 알립니다. HTTP 429에는 Retry-After가 들어 있습니다. 이 헤더를 블로그 글에서 외운 숫자가 아니라 실시간 예산으로 대하세요(익명 요청 제한).
MCP
Model Context Protocol을 쓰는 에이전트는 /mcp에 연결해 병합을 도구로 발견하고, REST와 같은 API 키 규칙으로 호출합니다. 문서: 개발자 MCP.
MCP는 두 번째 카탈로그가 아닙니다. OpenAPI가 나열하는 같은 연산 위에 얹힌 발견과 호출 프로토콜입니다. 어떤 op가 MCP에 없다면 그것은 서버 버그이지 별도의 제품 로드맵이 아닙니다. 클라이언트가 연결하기 전에 도구의 산문 색인이 필요하면 MCP와 /llms.txt를 함께 쓰세요.
pdfx CLI
pdfx --api-base "$API_BASE" --api-key "$KEY" merge a.pdf b.pdf -o merged.pdf
위 curl과 같은 multipart 형태이며 API base는 기본값이 호스팅 버전입니다. CLI가 더하는 것은 셸 편의성입니다. -o는 디렉터리를 받고 기존 파일을 절대 덮어쓰지 않으며, 여러 입력은 --concurrency로 배치 실행되고, 배치는 파일마다 input -> saved 줄을 하나씩 내며 실패는 stderr로 가고 나머지는 계속 끝까지 처리됩니다. pdfx list와 pdfx describe <tool>은 포털이 렌더링하는 카탈로그를 읽고, /skills/pdf123.md의 공개 skill이 같은 merge와 pipeline 형태를 문서화해, 에이전트가 두 번째 OpenAPI를 만들어 내지 않습니다.
이 클라이언트 중 어느 것으로 OCR을 하든 /api/v1/misc/ocr-pdf에서 Markdown을 반환하며 숨은 텍스트 레이어가 아닙니다. 이 사실은 공유 계약의 일부입니다. 한 클라이언트만 반환 타입을 바꾸면 “같은 op”라는 약속이 깨집니다. 압축은 스트림 재압축을 위해 /api/v1/misc/compress-pdf에 남아 있고, 병합과는 다른 op이면서 같은 네 가지 방식으로 닿습니다.
동일함이 중요한 이유
브라우저 병합과 API 병합이 갈라지면, 데모 페이지는 멀쩡해 보여도 자동화가 조용히 퇴행합니다. 하나의 op, 네 개의 손잡이가 핵심입니다. 포털은 편의 클라이언트이지 병합이나 압축, OCR의 두 번째 구현이 아닙니다.
데스크톱 포크가 없는 이유도 같습니다. 다섯 번째 UI 트리는 다른 바이너리 이름으로 같은 드리프트 문제를 다시 만듭니다. 더 넓은 맥락은 AI 에이전트를 위해 만들어진 API를 보세요. 데스크톱 결정은 데스크톱 앱을 만들지 않은 이유를 보세요. 내 네트워크에 API를 세우려면 자체 호스팅을 보세요.