同じ操作、四つのクライアント：ブラウザ、curl、MCP、pdfx
同じ PDF123 の結合を四つのクライアントから。ブラウザのフォーム、/api/v1/general/merge-pdfs への curl、/mcp の MCP、そして pdfx のローカルまたは --cloud だ。
四つのクライアントは四つの製品のように見える。だが共有しているのは一つのカタログだ。具体例として PDF の結合 を取る。ページを画像にラスタライズせず、アップロード順で PDF を結合する。他のカタログツール（圧縮、OCR、変換など）も同じパターンで、op id は一つ、呼び方が四つある。
ブラウザ
/ja/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 に接続し、merge をツールとして発見し、REST と同じ API Key の話で呼び出す。ドキュメント：開発者向け MCP。
MCP は第二のカタログではない。OpenAPI が列挙するのと同じ操作の上に載る、発見と呼び出しのプロトコルだ。ある op が MCP から見つからないなら、それはサーバーのバグであり、別製品のロードマップではない。クライアントが接続する前にツールの散文索引が欲しいときは、MCP と /llms.txt を組み合わせる。
pdfx CLI
ローカルの pdf-core：
pdfx merge a.pdf b.pdf -o merged.pdf
または、ポータルが使っているのと同じサーバー：
pdfx --cloud --api-base "$API_BASE" --api-key "$KEY" merge a.pdf b.pdf -o merged.pdf
ローカルモードはアップロードしない。クラウドモードは curl と同じ multipart の形で自分の base URL を叩く。dist/skills/pdf-toolbox/SKILL.md のコーディングエージェント向け skill は、同じ merge と pipeline の形を記録しており、エージェントが第二の OpenAPI を発明しないようにしている。
どのクライアント経由の OCR も、/api/v1/misc/ocr-pdf から Markdown を返す。隠しテキスト層ではない。この事実は共有された契約の一部だ。一つのクライアントだけ戻り値の型を変えれば、「同じ op」という約束が壊れる。圧縮は /api/v1/misc/compress-pdf のストリーム再圧縮のままで、merge とは別の op でありながら、同じ四つの方法で到達できる。
「同じ」であることが重要な理由
ブラウザの結合と API の結合がいつか分岐すれば、デモページは問題なく見えても自動化が静かに退行する。一つの op、四つの取っ手が要点だ。ポータルは便利なクライアントであって、merge、compress、OCR の第二の実装ではない。
デスクトップ版が無いのも同じ理由だ。第五の UI ツリーは、別のバイナリ名の下でずれの問題を再現する。より広い枠組みは ブラウザだけでなく AI エージェントのために作る。デスクトップ版の判断は デスクトップアプリを作らない理由。API を自分のネットワークに立てる話は セルフホスト にある。