どのMCPサーバーを使えばよいですか?
どちらのサーバーもPDF123の操作を公開しています。違いは、動作する場所と、ファイルの受け渡し方法です。
| ローカル: @pdf123/mcp | ホスト型: /mcp | |
|---|---|---|
| 動作する場所 | 自分のマシン上。MCPクライアントがstdio経由で起動する | https://pdf123.xyz/mcp にあるPDF123のサーバー上 |
| 入力 | ディスク上のファイルパス。サーバーがアップロードし、結果を入力の隣に保存する | アップロード用ツールで送るファイル |
| 認証情報 | 匿名利用では不要。PDFX_API_KEY は任意 | すべてのリクエストに X-API-KEY ヘッダーが必要。ないと401が返る |
| インストール | npx -y @pdf123/mcp | 不要。クライアントにURLとヘッダーを追加するだけ |
| ツール | 97個すべてのカタログを扱う5つのツール | 7つのツール: describe、convert、pages、misc、security、upload、download |
| 使う場面 | エージェントがローカルフォルダーの文書を扱うとき | エージェントまたはホスト型サービスが、すでにAPI経由でアップロードを処理しているとき |
ノートパソコン上のコーディングアシスタントにはローカルサーバーを使います。エージェントがクラウドで動いていて、手元のディスクを読めない場合は、ホスト型エンドポイントを使います。
ローカルMCPサーバーをインストールするには?
MCPクライアントが npx でサーバーを起動するため、インストールは不要です。Claude Codeでは、1つのコマンドで追加できます。
claude mcp add pdf123 -- npx -y @pdf123/mcpClaude Desktopは claude_desktop_config.json を、Cursorは .cursor/mcp.json を読み込みます。ほかのクライアントにも、MCPの設定ページまたはファイルがあります。どれも同じ mcpServers のエントリを受け付けます。
{
"mcpServers": {
"pdf123": {
"command": "npx",
"args": ["-y", "@pdf123/mcp"]
}
}
}設定を変更したら、クライアントを再起動してください。パスの通った場所にコピーを置くには、npm install -g @pdf123/mcp を実行します。これで pdf123-mcp コマンドが使えるようになります。サーバーにはNode 20.3以降と、接続できるAPIのベースが必要です。オフラインモードはありません。
エージェントに最初に何を頼めばよいですか?
ふつうの言葉で、ファイルを指定して頼みます。たとえば次のように頼みます。
~/Documents/a.pdf と ~/Documents/b.pdf を結合して、その結果を圧縮してください。
エージェントは pdf123_run_pipeline を呼び出すか、pdf123_run_tool を2回呼び出して、ファイルをPDF123にアップロードし、保存したファイルのパスを答えます。結果は最初の入力の隣に保存され、既存のファイルが置き換えられることはありません。同じ操作は、Webサイトでは結合と圧縮として利用できます。
ローカルサーバーにはどのツールがありますか?
サーバーには5つのツールがあります。merge のようなツールIDは通常の文字列の引数なので、ツールの一覧は小さく保たれます。
| ツール | 機能 | 主な引数 |
|---|---|---|
pdf123_list_tools | ツールを1行ずつ一覧する | group、query、format |
pdf123_describe_tool | ツールのフィールド、既定値、許可される値、バッチとして実行されるかどうかを示す | tool |
pdf123_run_tool | ローカルファイルに対して1つのツールを実行し、保存したパスまたはJSONレポートを返す | tool、files、params、output |
pdf123_run_pipeline | 最大8個のツールを1回のリクエストでつなぐ | steps、files、output |
pdf123_call | 任意のツールID、操作ID、/api/... パスに生のリクエストを送る | target、files、fields |
エージェントは通常、pdf123_list_tools でツールを探し、pdf123_describe_tool でそのフィールドを読み、そのあと pdf123_run_tool を呼び出します。IDを打ち間違えると、「もしかして」という候補が返されます。
バッチ、パスワード、パイプラインはどう動作しますか?
- バッチ。 単一ファイル用のツールに複数のファイルを渡すと、ファイルごとに1件の結果を返すバッチとして実行されます。各ファイルは、終わるたびに保存されます。返答はファイルごとのレポートです。1つでも失敗したファイルがあると、返答はレポート付きのエラーになるため、エージェントは失敗したファイルだけを再試行できます。
- パスワード。
input_passwordは、暗号化されたすべての入力を開きます。passwordsは、filesと同じ順序でファイルごとに1つのパスワードを設定し、ロックされていないファイルには空文字列を指定します。結合のように複数のファイルを受け取るツールでも使えます。 - パイプライン。
pdf123_run_pipelineは最大8ステップを受け取り、各ステップが次のステップに渡されます。同じパスワードの引数を受け付けます。 - 生の呼び出し。
pdf123_callを使うと、サーバーより新しい操作にも到達できます。ローカルでの検証は行われません。 - フィルターツール。 IDが
filter-で始まるツールは、条件を満たさないとき{"matched": false}を返します。これはエラーではなく結果です。 - 再試行。
idempotencyKeyは、24時間のあいだ最初の結果を再生します。
エージェントが使えるフォルダーを制限するには?
PDFX_MCP_ROOT にディレクトリを設定します。複数のディレクトリはコロンで区切り、Windowsではセミコロンで区切ります。すると、サーバーはそれらのディレクトリの中でだけ入力を読み、結果を書き込みます。その外側のパス、.. による脱出、外へ通じるシンボリックリンクは、何かをアップロードする前に Code: path_not_allowed で拒否されます。この環境変数がない場合は、サーバーのプロセスが到達できるすべてのパスが許可されます。
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }環境変数は、クライアントの env ブロックに設定するか、claude mcp add -e NAME=value で設定します。PDFX_API_BASE を使うと、代わりに自分の pdfx-server にサーバーを向けられます。詳しくはセルフホストをご覧ください。
結果とエラーはどのような形ですか?
単一の結果は、保存した path、contentType、サイズ bytes を持つ小さなJSONオブジェクトです。バッチの結果は、processed、unmatched、failed、そして files の一覧を持ちます。これらの形は、コマンドラインの pdfx --json と一致します。文書情報のようにレポートを返すツールは、レポートをそのまま返します。
{
"path": "/Users/me/Documents/merged.pdf",
"contentType": "application/pdf",
"bytes": 1096
}失敗した呼び出しは、ツールのエラーとして返ります。サーバーが提供していれば、そのテキストの末尾に Reason:、Code:、Hint: の行が付くため、エージェントはコードで分岐できます。
HTTP 400: This PDF is password-protected. Enter its password.
Reason: password_required
Code: bad_request
Hint: Provide the document password, or unlock the PDF first.ツールIDに打ち間違いがあると、エラーには近いIDが一覧され、末尾に Code: unknown_tool が付きます。表のないPDFに対する pdf-to-csv のように、返すものが見つからないツールは、空のファイルの代わりに Code: no_content を返します。エラーコードをご覧ください。
ホスト型MCPエンドポイントを使うには?
APIには、POST https://pdf123.xyz/mcp にMCPサーバーが組み込まれています。認証には、REST APIと同じ X-API-KEY ヘッダーを使います。キーがないと、エンドポイントは401を返します。キーは開発者向けページで作成できます。
{
"mcpServers": {
"pdf123": {
"url": "https://pdf123.xyz/mcp",
"headers": { "X-API-KEY": "<your-key>" }
}
}
}ホスト型サーバーには7つのツールがあります。pdf_toolbox_describe_operation、pdf_toolbox_convert、pdf_toolbox_pages、pdf_toolbox_misc、pdf_toolbox_security、pdf_toolbox_upload、pdf_toolbox_download です。カテゴリごとの各ツールは、operation 名とそのパラメーターに加えて、ファイルまたはアップロード用ツールが返す fileId を受け取ります。1つの操作のスキーマを取得するには、describeツールを使います。
関連ページ
- エージェント用スキル: Claude Code、Codex、Cursor向け。カタログ用に1つ、ツールごとに1つ
- /llms.txt: ツール、API、MCPエンドポイントのプレーンテキストの索引
- pdfxコマンドラインとTypeScript SDK: カタログを共有しています
- 開発者向け概要、OpenAPIドキュメント、Swagger UI
- ツールページ: 結合、圧縮、OCR、保護、修復
- PDF123ブログの記事「Built for AI Agents, Not Just Browsers」と「Same Operation, Four Clients」
FAQ
MCPとは何ですか?
MCP(Model Context Protocol)は、AIクライアントを外部ツールにつなぐためのオープンな標準です。Claude CodeなどのクライアントがMCPサーバーを起動するか接続し、そのツールを一覧して、ユーザーに代わって呼び出します。
ローカルMCPサーバーはオフラインで動作しますか?
いいえ。ファイルをPDF123 API、または PDFX_API_BASE に指定したサーバーにアップロードし、結果をローカルに保存します。APIのベースに接続できる必要があります。
APIキーは必要ですか?
ローカルサーバーは、匿名での利用ならキーが不要です。サーバーがキーを必要とする場合は PDFX_API_KEY を設定してください。/mcp のホスト型エンドポイントには、常に X-API-KEY ヘッダーが必要です。
エージェントはコンピューター上のどのファイルでも読めますか?
既定では、サーバーのプロセスが到達できるすべてのパスを読めます。読み書きを選んだディレクトリに限定するには、PDFX_MCP_ROOT を設定してください。
ファイルはどうなりますか?
ローカルサーバーは、処理のために各入力をPDF123 API、または自分のサーバーにアップロードします。ツールの説明には、処理後にそのファイルが削除されると記載されています。結果は自分のマシンに保存されます。詳しくはファイル処理とプライバシーをご覧ください。
エージェントはいくつのツールを使えますか?
ローカルサーバーは、5つのMCPツールを通じて、カタログの97個すべてのツールに到達できます。ホスト型エンドポイントは、操作をカテゴリ(convert、pages、misc、security)ごとにまとめ、7つのMCPツールとして公開しています。