Nên dùng máy chủ MCP nào?
Cả hai máy chủ đều cung cấp các thao tác của PDF123. Chúng khác nhau ở nơi chạy và cách tệp đến được máy chủ.
| Cục bộ: @pdf123/mcp | Lưu trữ sẵn: /mcp | |
|---|---|---|
| Chạy ở đâu | Trên máy bạn, do ứng dụng MCP khởi chạy qua stdio | Trên máy chủ của PDF123 tại https://pdf123.xyz/mcp |
| Đầu vào | Đường dẫn tệp trên ổ đĩa. Máy chủ tải chúng lên và lưu kết quả cạnh tệp đầu vào | Tệp gửi qua công cụ tải lên |
| Thông tin xác thực | Không cần khi dùng ẩn danh. PDFX_API_KEY là tùy chọn | Header X-API-KEY trong mọi yêu cầu. Thiếu header thì trả 401 |
| Cài đặt | npx -y @pdf123/mcp | Không cần. Thêm URL và header vào ứng dụng |
| Công cụ | Năm công cụ cho toàn bộ danh mục 97 công cụ | Bảy công cụ: describe, convert, pages, misc, security, upload và download |
| Dùng khi | Agent làm việc với tài liệu trong một thư mục cục bộ | Agent hoặc dịch vụ lưu trữ sẵn đã xử lý việc tải lên qua API |
Hãy dùng máy chủ cục bộ cho trợ lý lập trình trên laptop. Dùng endpoint lưu trữ sẵn khi agent chạy trên đám mây và không đọc được ổ đĩa của bạn.
Làm sao cài máy chủ MCP cục bộ?
Không cần cài gì cả, vì ứng dụng MCP khởi chạy máy chủ bằng npx. Trong Claude Code, thêm nó bằng một lệnh.
claude mcp add pdf123 -- npx -y @pdf123/mcpClaude Desktop đọc claude_desktop_config.json, còn Cursor đọc .cursor/mcp.json. Các ứng dụng khác có trang hoặc tệp cài đặt MCP. Tất cả đều chấp nhận cùng một mục mcpServers.
{
"mcpServers": {
"pdf123": {
"command": "npx",
"args": ["-y", "@pdf123/mcp"]
}
}
}Hãy khởi động lại ứng dụng sau khi thay đổi cấu hình. Để giữ một bản trong đường dẫn của bạn, chạy npm install -g @pdf123/mcp, lệnh này cung cấp lệnh pdf123-mcp. Máy chủ cần Node 20.3 trở lên và một API base truy cập được. Không có chế độ ngoại tuyến.
Nên yêu cầu agent điều gì trước tiên?
Hãy hỏi bằng ngôn ngữ thường ngày và nêu tên các tệp. Ví dụ:
Gộp ~/Documents/a.pdf và ~/Documents/b.pdf, rồi nén kết quả.
Agent gọi pdf123_run_pipeline, hoặc gọi pdf123_run_tool hai lần, tải các tệp lên PDF123 và trả lời bằng đường dẫn của tệp đã lưu. Kết quả được lưu cạnh tệp đầu vào đầu tiên và không bao giờ thay thế tệp đã có. Các thao tác tương tự có trên website với tên Gộp và Nén.
Máy chủ cục bộ cung cấp những công cụ nào?
Máy chủ có năm công cụ. Các id công cụ như merge chỉ là đối số chuỗi thông thường, nên danh sách công cụ luôn gọn.
| Công cụ | Chức năng | Đối số chính |
|---|---|---|
pdf123_list_tools | Liệt kê các công cụ, mỗi công cụ một dòng | group, query, format |
pdf123_describe_tool | Cho thấy các trường, giá trị mặc định, giá trị cho phép của một công cụ và việc nó có chạy theo lô hay không | tool |
pdf123_run_tool | Chạy một công cụ trên tệp cục bộ và trả về đường dẫn đã lưu hoặc báo cáo JSON | tool, files, params, output |
pdf123_run_pipeline | Nối tối đa 8 công cụ trong một yêu cầu | steps, files, output |
pdf123_call | Gửi yêu cầu thô tới bất kỳ id công cụ, id thao tác hoặc đường dẫn /api/... nào | target, files, fields |
Agent thường gọi pdf123_list_tools để tìm công cụ, pdf123_describe_tool để đọc các trường của nó, rồi mới gọi pdf123_run_tool. Id gõ sai sẽ nhận gợi ý "ý bạn là".
Xử lý hàng loạt, mật khẩu và pipeline hoạt động thế nào?
- Lô. Nhiều tệp đưa cho công cụ một tệp sẽ chạy theo lô, mỗi tệp một kết quả. Mỗi tệp được lưu ngay khi xong. Phản hồi là báo cáo theo từng tệp. Nếu có tệp nào lỗi, phản hồi là một lỗi kèm báo cáo, để agent chỉ thử lại các tệp đã lỗi.
- Mật khẩu.
input_passwordmở mọi đầu vào đã mã hóa.passwordsđặt một mật khẩu cho mỗi tệp, theo cùng thứ tự vớifiles, dùng chuỗi rỗng cho tệp không có mật khẩu. Cách này cũng dùng được cho các công cụ nhiều tệp như Gộp. - Pipeline.
pdf123_run_pipelinenhận tối đa 8 bước, và mỗi bước đưa đầu ra cho bước kế tiếp. Nó nhận cùng các đối số mật khẩu. - Gọi thô.
pdf123_calltruy cập các thao tác mới hơn máy chủ. Không có gì được kiểm tra ở phía cục bộ. - Công cụ lọc. Công cụ có id bắt đầu bằng
filter-trả về{"matched": false}khi điều kiện không thỏa. Đó là một kết quả, không phải lỗi. - Thử lại.
idempotencyKeyphát lại kết quả đầu tiên trong 24 giờ.
Làm sao giới hạn thư mục mà agent được dùng?
Đặt PDFX_MCP_ROOT là một thư mục. Ngăn cách nhiều thư mục bằng dấu hai chấm, hoặc dấu chấm phẩy trên Windows. Khi đó máy chủ chỉ đọc đầu vào và ghi kết quả trong các thư mục này. Đường dẫn nằm ngoài, các cách thoát bằng .. và liên kết tượng trưng dẫn ra ngoài đều bị từ chối trước khi có gì được tải lên, với Code: path_not_allowed. Nếu không đặt biến này, mọi đường dẫn mà tiến trình máy chủ truy cập được đều được phép.
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }Hãy đặt biến môi trường trong khối env của ứng dụng, hoặc bằng claude mcp add -e NAME=value. PDFX_API_BASE trỏ máy chủ tới pdfx-server của riêng bạn; xem Tự host.
Kết quả và lỗi trông như thế nào?
Một kết quả đơn là một đối tượng JSON nhỏ gồm path đã lưu, contentType và dung lượng bytes. Kết quả của lô có processed, unmatched, failed và danh sách files. Các dạng này khớp với pdfx --json trên dòng lệnh. Công cụ trả về báo cáo, chẳng hạn Thông tin tài liệu, trả báo cáo ngay trong phản hồi.
{
"path": "/Users/me/Documents/merged.pdf",
"contentType": "application/pdf",
"bytes": 1096
}Lời gọi thất bại được trả về dưới dạng lỗi công cụ. Văn bản của nó kết thúc bằng các dòng Reason:, Code: và Hint: nếu máy chủ cung cấp, để agent rẽ nhánh theo mã.
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.Nếu id công cụ bị gõ sai, lỗi sẽ liệt kê các id gần giống và kết thúc bằng Code: unknown_tool. Công cụ không tìm thấy gì để trả về, chẳng hạn pdf-to-csv trên PDF không có bảng, trả về Code: no_content thay vì tệp rỗng. Xem Mã lỗi.
Làm sao dùng endpoint MCP lưu trữ sẵn?
API nhúng sẵn một máy chủ MCP tại POST https://pdf123.xyz/mcp. Xác thực bằng cùng header X-API-KEY mà REST API dùng. Không có khóa thì endpoint trả 401. Hãy tạo khóa ở trang dành cho nhà phát triển.
{
"mcpServers": {
"pdf123": {
"url": "https://pdf123.xyz/mcp",
"headers": { "X-API-KEY": "<your-key>" }
}
}
}Máy chủ lưu trữ sẵn liệt kê bảy công cụ: pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload và pdf_toolbox_download. Mỗi công cụ theo danh mục nhận tên operation và tham số của nó, cùng một tệp hoặc một fileId do công cụ tải lên trả về. Hãy dùng công cụ describe để lấy schema của một thao tác.
Trang liên quan
- Skill cho agent dành cho Claude Code, Codex và Cursor: một skill cho cả danh mục và một skill cho từng công cụ
- /llms.txt, chỉ mục văn bản thuần của các công cụ, API và endpoint MCP
- Dòng lệnh pdfx và SDK TypeScript, dùng chung danh mục
- Tổng quan cho nhà phát triển, tài liệu OpenAPI và Swagger UI
- Các trang công cụ: Gộp, Nén, OCR, Bảo vệ, Sửa
- Các bài "Xây cho AI agent, không chỉ trình duyệt: API hoạt động thế nào" và "Cùng một thao tác, bốn client: trình duyệt, curl, MCP, pdfx" trên blog PDF123
Câu hỏi thường gặp
MCP là gì?
MCP, tức Model Context Protocol, là chuẩn mở để kết nối các ứng dụng AI với công cụ bên ngoài. Một ứng dụng như Claude Code khởi chạy hoặc kết nối tới máy chủ MCP, liệt kê các công cụ của nó và gọi chúng thay mặt người dùng.
Máy chủ MCP cục bộ có hoạt động ngoại tuyến không?
Không. Nó tải tệp lên API PDF123, hoặc máy chủ được chỉ định trong PDFX_API_BASE, rồi lưu kết quả về máy. Phải truy cập được API base.
Có cần khóa API không?
Máy chủ cục bộ không cần khóa khi dùng ẩn danh. Hãy đặt PDFX_API_KEY nếu máy chủ của bạn yêu cầu khóa. Endpoint lưu trữ sẵn tại /mcp luôn cần header X-API-KEY.
Agent có đọc được mọi tệp trên máy tính của tôi không?
Theo mặc định, nó đọc được mọi đường dẫn mà tiến trình máy chủ truy cập được. Hãy đặt PDFX_MCP_ROOT để giới hạn việc đọc và ghi trong các thư mục bạn chọn.
Tệp của tôi được xử lý ra sao?
Máy chủ cục bộ tải từng đầu vào lên API PDF123, hoặc máy chủ riêng của bạn, để xử lý. Mô tả công cụ nêu rõ rằng tệp được xóa ở đó sau khi xử lý. Kết quả được lưu trên máy của bạn. Để biết chi tiết, hãy đọc trang quyền riêng tư tệp.
Agent dùng được bao nhiêu công cụ?
Máy chủ cục bộ truy cập cả 97 công cụ trong danh mục thông qua năm công cụ MCP. Endpoint lưu trữ sẵn gom các thao tác theo danh mục (convert, pages, misc và security) sau bảy công cụ MCP.