कौन-सा MCP सर्वर इस्तेमाल करें?
दोनों सर्वर PDF123 के ऑपरेशन उपलब्ध कराते हैं। फ़र्क इस बात में है कि वे कहाँ चलते हैं और फ़ाइलें उन तक कैसे पहुँचती हैं।
| स्थानीय: @pdf123/mcp | होस्टेड: /mcp | |
|---|---|---|
| कहाँ चलता है | आपकी मशीन पर, MCP क्लाइंट इसे stdio से शुरू करता है | PDF123 सर्वर पर, https://pdf123.xyz/mcp पर |
| इनपुट | डिस्क पर फ़ाइल पथ। सर्वर उन्हें अपलोड करता है और नतीजा इनपुट के बगल में सेव करता है | अपलोड टूल से भेजी गई फ़ाइलें |
| क्रेडेंशियल | गुमनाम उपयोग के लिए कोई नहीं। PDFX_API_KEY वैकल्पिक है | हर अनुरोध पर X-API-KEY हेडर। इसके बिना जवाब 401 है |
| इंस्टॉल | npx -y @pdf123/mcp | कुछ नहीं। क्लाइंट में URL और हेडर जोड़ें |
| टूल | पूरे 97 टूल के कैटलॉग के लिए पाँच टूल | सात टूल: describe, convert, pages, misc, security, upload और download |
| कब इस्तेमाल करें | जब एजेंट किसी स्थानीय फ़ोल्डर के दस्तावेज़ों पर काम करे | जब कोई एजेंट या होस्टेड सेवा अपलोड पहले से API से सँभालती हो |
लैपटॉप पर कोडिंग असिस्टेंट के लिए स्थानीय सर्वर इस्तेमाल करें। जब एजेंट क्लाउड में चलता हो और आपकी डिस्क नहीं पढ़ सकता हो, तब होस्टेड एंडपॉइंट इस्तेमाल करें।
स्थानीय MCP सर्वर कैसे इंस्टॉल करें?
कुछ इंस्टॉल करने की ज़रूरत नहीं, क्योंकि MCP क्लाइंट सर्वर को npx से शुरू करता है। Claude Code में इसे एक कमांड से जोड़ें।
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 दो बार, कॉल करता है, फ़ाइलें PDF123 पर अपलोड करता है और सेव की गई फ़ाइल के पथ के साथ जवाब देता है। नतीजा पहले इनपुट के बगल में सेव होता है और किसी मौजूदा फ़ाइल को कभी नहीं बदलता। वेबसाइट पर यही ऑपरेशन मिलाएँ और संपीड़ित करें के रूप में हैं।
स्थानीय सर्वर कौन-से टूल देता है?
सर्वर में पाँच टूल हैं। merge जैसी टूल आईडी सादे स्ट्रिंग आर्गुमेंट हैं, इसलिए टूल सूची छोटी रहती है।
| टूल | क्या करता है | मुख्य आर्गुमेंट |
|---|---|---|
pdf123_list_tools | टूल की सूची देता है, हर टूल की एक पंक्ति | group, query, format |
pdf123_describe_tool | टूल के फ़ील्ड, डिफ़ॉल्ट, अनुमत मान और बैच के रूप में चलने की जानकारी दिखाता है | tool |
pdf123_run_tool | स्थानीय फ़ाइलों पर एक टूल चलाता है और सेव किया गया पथ या JSON रिपोर्ट लौटाता है | tool, files, params, output |
pdf123_run_pipeline | एक अनुरोध में अधिकतम 8 टूल जोड़ता है | steps, files, output |
pdf123_call | किसी भी टूल आईडी, ऑपरेशन आईडी या /api/... पथ पर कच्चा अनुरोध भेजता है | target, files, fields |
एजेंट आमतौर पर टूल खोजने के लिए pdf123_list_tools, उसके फ़ील्ड पढ़ने के लिए pdf123_describe_tool, और फिर pdf123_run_tool कॉल करता है। गलत टाइप की गई आईडी पर "क्या आपका मतलब था" वाले सुझाव मिलते हैं।
बैच, पासवर्ड और पाइपलाइन कैसे काम करते हैं?
- बैच। एक-फ़ाइल वाले टूल को कई फ़ाइलें देने पर वह बैच के रूप में चलता है, हर फ़ाइल का अलग नतीजा आता है। हर फ़ाइल पूरी होते ही सेव हो जाती है। जवाब हर फ़ाइल की रिपोर्ट होता है। कोई फ़ाइल विफल हो तो जवाब रिपोर्ट के साथ एक त्रुटि होता है, ताकि एजेंट सिर्फ़ विफल फ़ाइलें दोबारा चला सके।
- पासवर्ड।
input_passwordहर एन्क्रिप्टेड इनपुट खोलता है।passwordsहर फ़ाइल का अलग पासवर्ड तय करता है,filesके क्रम में ही, और खुली फ़ाइल के लिए खाली स्ट्रिंग। यह मिलाएँ जैसे कई-फ़ाइल वाले टूल के लिए भी चलता है। - पाइपलाइन।
pdf123_run_pipelineअधिकतम 8 चरण लेता है, और हर चरण अगले को आउटपुट देता है। इसमें वही पासवर्ड आर्गुमेंट चलते हैं। - कच्चे कॉल।
pdf123_callउन ऑपरेशन तक पहुँचता है जो सर्वर से नए हैं। स्थानीय स्तर पर कुछ वैलिडेट नहीं होता। - फ़िल्टर टूल। जिस टूल की आईडी
filter-से शुरू होती है, वह शर्त पूरी न होने पर{"matched": false}देता है। यह नतीजा है, त्रुटि नहीं। - दोबारा कोशिश।
idempotencyKey24 घंटे तक पहला नतीजा दोहराती है।
एजेंट कौन-से फ़ोल्डर इस्तेमाल कर सकता है, यह कैसे सीमित करें?
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 की ओर मोड़ता है; देखें सेल्फ-होस्ट।
नतीजे और त्रुटियाँ कैसी दिखती हैं?
एकल नतीजा एक छोटा JSON ऑब्जेक्ट है, जिसमें सेव किया गया path, contentType और bytes में आकार होता है। बैच के नतीजे में 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.यदि टूल आईडी में टाइपो हो, तो त्रुटि मिलती-जुलती आईडी सूचीबद्ध करती है और Code: unknown_tool पर खत्म होती है। जिस टूल के पास लौटाने को कुछ नहीं होता, जैसे बिना तालिका वाले PDF पर pdf-to-csv, वह खाली फ़ाइल के बजाय Code: no_content लौटाता है। देखें त्रुटि कोड।
होस्टेड MCP एंडपॉइंट कैसे इस्तेमाल करें?
API में POST https://pdf123.xyz/mcp पर एक MCP सर्वर जुड़ा है। उसी X-API-KEY हेडर से प्रमाणित करें जो REST API में चलता है। कुंजी के बिना एंडपॉइंट 401 देता है। कुंजी डेवलपर पेज पर बनाएँ।
{
"mcpServers": {
"pdf123": {
"url": "https://pdf123.xyz/mcp",
"headers": { "X-API-KEY": "<your-key>" }
}
}
}होस्टेड सर्वर सात टूल सूचीबद्ध करता है: pdf_toolbox_describe_operation, pdf_toolbox_convert, pdf_toolbox_pages, pdf_toolbox_misc, pdf_toolbox_security, pdf_toolbox_upload और pdf_toolbox_download। श्रेणी वाला हर टूल एक operation नाम और उसके पैरामीटर लेता है, साथ में एक फ़ाइल या अपलोड टूल से मिली fileId। किसी एक ऑपरेशन का स्कीमा पाने के लिए describe टूल इस्तेमाल करें।
संबंधित पेज
- Claude Code, Codex और Cursor के लिए एजेंट स्किल: एक कैटलॉग के लिए और एक हर टूल के लिए
- /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 या आपके अपने सर्वर पर अपलोड करता है। टूल के विवरण में लिखा है कि प्रोसेसिंग के बाद फ़ाइलें वहाँ से मिटा दी जाती हैं। नतीजा आपकी मशीन पर सेव होता है। ब्योरे के लिए फ़ाइल गोपनीयता पेज पढ़ें।
एजेंट कितने टूल इस्तेमाल कर सकता है?
स्थानीय सर्वर पाँच MCP टूल के ज़रिए कैटलॉग के सभी 97 टूल तक पहुँचता है। होस्टेड एंडपॉइंट अपने ऑपरेशन श्रेणी (convert, pages, misc और security) के अनुसार सात MCP टूल के पीछे समूहित करता है।