Server MCP mana yang sebaiknya saya pakai?
Kedua server menyediakan operasi PDF123. Bedanya ada pada tempat berjalannya dan cara file sampai ke server.
| Lokal: @pdf123/mcp | Hosted: /mcp | |
|---|---|---|
| Berjalan di | Di komputer Anda, dijalankan oleh klien MCP lewat stdio | Di server PDF123 pada https://pdf123.xyz/mcp |
| Masukan | Jalur file di disk. Server mengunggahnya dan menyimpan hasil di samping file masukan | File yang dikirim lewat alat unggah |
| Kredensial | Tidak ada untuk pemakaian anonim. PDFX_API_KEY bersifat opsional | Header X-API-KEY pada setiap permintaan. Tanpa header itu jawabannya 401 |
| Instalasi | npx -y @pdf123/mcp | Tidak perlu. Tambahkan URL dan header ke klien |
| Alat | Lima alat untuk seluruh katalog 97 alat | Tujuh alat: describe, convert, pages, misc, security, upload, dan download |
| Pakai jika | Agen mengerjakan dokumen di folder lokal | Agen atau layanan hosted sudah menangani unggahan lewat API |
Pakai server lokal untuk asisten pemrograman di laptop. Pakai endpoint hosted jika agen berjalan di cloud dan tidak bisa membaca disk Anda.
Bagaimana cara memasang server MCP lokal?
Tidak ada yang perlu dipasang, karena klien MCP menjalankan server dengan npx. Di Claude Code, tambahkan dengan satu perintah.
claude mcp add pdf123 -- npx -y @pdf123/mcpClaude Desktop membaca claude_desktop_config.json, dan Cursor membaca .cursor/mcp.json. Klien lain punya halaman atau file pengaturan MCP. Semuanya menerima entri mcpServers yang sama.
{
"mcpServers": {
"pdf123": {
"command": "npx",
"args": ["-y", "@pdf123/mcp"]
}
}
}Mulai ulang klien setelah Anda mengubah konfigurasinya. Untuk menyimpan salinan di path Anda, jalankan npm install -g @pdf123/mcp, yang menyediakan perintah pdf123-mcp. Server membutuhkan Node 20.3 atau lebih baru dan basis API yang dapat dijangkau. Tidak ada mode offline.
Apa yang pertama kali saya minta kepada agen?
Minta dengan bahasa sehari-hari dan sebutkan file-nya. Contohnya:
Gabungkan ~/Documents/a.pdf dan ~/Documents/b.pdf, lalu kompres hasilnya.
Agen memanggil pdf123_run_pipeline, atau pdf123_run_tool dua kali, mengunggah file ke PDF123, dan menjawab dengan jalur file yang tersimpan. Hasil disimpan di samping masukan pertama dan tidak pernah menimpa file yang sudah ada. Operasi yang sama tersedia sebagai Gabungkan dan Kompres di situs web.
Alat apa saja yang disediakan server lokal?
Server memiliki lima alat. Id alat seperti merge adalah argumen string biasa, sehingga daftar alatnya tetap ringkas.
| Alat | Fungsinya | Argumen utama |
|---|---|---|
pdf123_list_tools | Mencantumkan alat, satu baris untuk tiap alat | group, query, format |
pdf123_describe_tool | Menampilkan kolom alat, nilai bawaan, nilai yang diizinkan, dan apakah alat berjalan sebagai batch | tool |
pdf123_run_tool | Menjalankan satu alat pada file lokal dan mengembalikan jalur file tersimpan atau laporan JSON | tool, files, params, output |
pdf123_run_pipeline | Merangkai hingga 8 alat dalam satu permintaan | steps, files, output |
pdf123_call | Mengirim permintaan mentah ke id alat, id operasi, atau jalur /api/... apa pun | target, files, fields |
Agen biasanya memanggil pdf123_list_tools untuk menemukan alat, pdf123_describe_tool untuk membaca kolomnya, lalu pdf123_run_tool. Id yang salah ketik mengembalikan saran "maksud Anda".
Bagaimana batch, kata sandi, dan pipeline bekerja?
- Batch. Beberapa file yang diberikan ke alat satu-file dijalankan sebagai batch dengan satu hasil untuk tiap file. Setiap file disimpan begitu selesai. Balasannya berupa laporan per file. Jika ada file yang gagal, balasannya berupa galat dengan laporan terlampir, sehingga agen dapat mengulang hanya file yang gagal.
- Kata sandi.
input_passwordmembuka semua masukan terenkripsi.passwordsmenetapkan satu kata sandi per file, dengan urutan yang sama sepertifiles, memakai string kosong untuk file yang terbuka. Ini juga berlaku untuk alat multi-file seperti Gabungkan. - Pipeline.
pdf123_run_pipelinemenerima hingga 8 langkah, dan setiap langkah memberi masukan ke langkah berikutnya. Argumen kata sandinya sama. - Panggilan mentah.
pdf123_callmenjangkau operasi yang lebih baru daripada server. Tidak ada yang divalidasi secara lokal. - Alat filter. Alat yang id-nya diawali
filter-menjawab{"matched": false}jika kondisinya tidak terpenuhi. Itu adalah hasil, bukan galat. - Pengulangan.
idempotencyKeymemutar ulang hasil pertama selama 24 jam.
Bagaimana cara membatasi folder yang boleh dipakai agen?
Setel PDFX_MCP_ROOT ke sebuah direktori. Pisahkan beberapa direktori dengan titik dua, atau titik koma di Windows. Server kemudian hanya membaca masukan dan menulis hasil di dalam direktori tersebut. Jalur di luarnya, pelarian dengan .., dan symbolic link yang mengarah keluar ditolak sebelum apa pun diunggah, dengan Code: path_not_allowed. Tanpa variabel ini, jalur apa pun yang dapat dijangkau proses server diizinkan.
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }Setel variabel lingkungan di blok env klien, atau dengan claude mcp add -e NAME=value. PDFX_API_BASE mengarahkan server ke pdfx-server Anda sendiri; lihat Self-host.
Seperti apa hasil dan galatnya?
Satu hasil berupa objek JSON kecil dengan path file tersimpan, contentType, dan ukuran dalam bytes. Hasil batch memiliki processed, unmatched, failed, dan daftar files. Bentuk ini sama dengan pdfx --json di baris perintah. Alat yang mengembalikan laporan, seperti Informasi dokumen, mengembalikan laporannya secara langsung.
{
"path": "/Users/me/Documents/merged.pdf",
"contentType": "application/pdf",
"bytes": 1096
}Panggilan yang gagal kembali sebagai galat alat. Teksnya diakhiri baris Reason:, Code:, dan Hint: jika server menyediakannya, sehingga agen dapat bercabang berdasarkan kode.
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.Jika id alat salah ketik, galat mencantumkan id yang mirip dan diakhiri Code: unknown_tool. Alat yang tidak menemukan apa pun untuk dikembalikan, seperti pdf-to-csv pada PDF tanpa tabel, mengembalikan Code: no_content alih-alih file kosong. Lihat Kode galat.
Bagaimana cara memakai endpoint MCP yang di-host?
API menanamkan server MCP di POST https://pdf123.xyz/mcp. Lakukan autentikasi dengan header X-API-KEY yang sama seperti pada REST API. Tanpa kunci, endpoint menjawab 401. Buat kunci di halaman Pengembang.
{
"mcpServers": {
"pdf123": {
"url": "https://pdf123.xyz/mcp",
"headers": { "X-API-KEY": "<your-key>" }
}
}
}Server hosted menyediakan tujuh alat: pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload, dan pdf_toolbox_download. Setiap alat kategori menerima nama operation beserta parameternya, ditambah sebuah file atau fileId yang dikembalikan oleh alat unggah. Gunakan alat describe untuk mendapatkan skema satu operasi.
Halaman terkait
- Skill agen untuk Claude Code, Codex, dan Cursor, satu untuk katalog dan satu untuk setiap alat
- /llms.txt, indeks teks biasa dari alat, API, dan endpoint MCP
- Baris perintah pdfx dan SDK TypeScript, yang berbagi katalog yang sama
- Ikhtisar pengembang, dokumen OpenAPI, dan Swagger UI
- Halaman alat: Gabungkan, Kompres, OCR, Lindungi, Perbaiki
- Artikel "Built for AI Agents, Not Just Browsers" dan "Same Operation, Four Clients" di blog PDF123
FAQ
Apa itu MCP?
MCP, Model Context Protocol, adalah standar terbuka untuk menghubungkan klien AI ke alat eksternal. Klien seperti Claude Code menjalankan atau menghubungi server MCP, mendaftar alatnya, lalu memanggilnya atas nama pengguna.
Apakah server MCP lokal bisa bekerja offline?
Tidak. Server ini mengunggah file ke API PDF123, atau ke server yang disebut di PDFX_API_BASE, lalu menyimpan hasilnya secara lokal. Basis API harus dapat dijangkau.
Apakah perlu kunci API?
Server lokal tidak memerlukan kunci untuk pemakaian anonim. Setel PDFX_API_KEY jika server Anda mewajibkannya. Endpoint hosted di /mcp selalu memerlukan header X-API-KEY.
Bisakah agen membaca file apa pun di komputer saya?
Secara bawaan agen dapat membaca jalur apa pun yang dapat dijangkau proses server. Setel PDFX_MCP_ROOT untuk membatasi pembacaan dan penulisan pada direktori yang Anda pilih.
Apa yang terjadi pada file saya?
Server lokal mengunggah setiap masukan ke API PDF123, atau ke server Anda sendiri, untuk diproses. Deskripsi alat menyatakan bahwa file dihapus di sana setelah pemrosesan. Hasilnya disimpan di komputer Anda. Untuk detailnya, baca halaman privasi file.
Berapa banyak alat yang dapat dipakai agen?
Server lokal menjangkau seluruh 97 alat dalam katalog lewat lima alat MCP. Endpoint hosted mengelompokkan operasinya menurut kategori (convert, pages, misc, dan security) di balik tujuh alat MCP.