Superserve Sandbox MCP
आधिकारिकसुपरसर्व द्वारा होस्ट किए गए एजेंटों के लिए सुरक्षित वर्चुअल मशीनें
Superserve Sandbox MCP के साथ आप क्या कर सकते हैं?
- एक पृथक सैंडबॉक्स बनाएं — सहायक से
sandbox_createके साथ एक Firecracker microVM शुरू करने के लिए कहें, वैकल्पिक रूप से गोपनीय जानकारी और आउटगोइंग नियम संलग्न करें। - सैंडबॉक्स के अंदर शेल कमांड चलाएं —
sandbox_execके माध्यम से कमांड निष्पादित करें और stdout, stderr, तथा एग्जिट कोड प्राप्त करें (रुके हुए सैंडबॉक्स को स्वचालित रूप से फिर से शुरू करता है)। - सैंडबॉक्स में फ़ाइलें पढ़ें और लिखें — फ़ाइलों का निरीक्षण या रखने के लिए
sandbox_files_readऔरsandbox_files_writeका उपयोग करें, स्वचालित पैरेंट-डायरेक्ट्री निर्माण के साथ। - सैंडबॉक्स से एक सार्वजनिक एंडपॉइंट प्रकट करें — एक सर्वर प्रक्रिया शुरू करें और एक सुनने वाले पोर्ट के लिए सार्वजनिक रूप से सुलभ URL प्राप्त करने हेतु
sandbox_preview_urlको कॉल करें। - आउटबाउंड नेटवर्क ट्रैफ़िक का ऑडिट करें — जांचें कि सैंडबॉक्स ने किन होस्टों से संपर्क किया और
sandbox_network_logके साथ वे अनुमत या अस्वीकृत थे या नहीं। - कस्टम टेम्पलेट बनाएं और प्रबंधित करें —
sandbox_template_createका उपयोग करके विशिष्ट vCPU/मेमोरी/डिस्क या पूर्व-स्थापित सॉफ़्टवेयर वाला एक टेम्पलेट बनाएं, फिर उससे सैंडबॉक्स लॉन्च करें।
दस्तावेज़
MCP सर्वर
किसी भी MCP क्लाइंट से Superserve सैंडबॉक्स बनाएँ, चलाएँ और प्रबंधित करें।
Superserve MCP सर्वर (@superserve/mcp) सैंडबॉक्स प्रिमिटिव को Model Context Protocol उपकरणों के रूप में उजागर करता है, ताकि कोई भी MCP-सक्षम क्लाइंट — Claude, Cursor, VS Code, Windsurf, Codex — सैंडबॉक्स बना सके, कमांड चला सके, फ़ाइलें पढ़ और लिख सके, टेम्पलेट बना सके, सीक्रेट का प्रबंध कर सके, और एक पृथक Firecracker microVM में नेटवर्क एक्सेस को नियंत्रित कर सके।
इसे दो तरीकों से चलाएँ: npx के माध्यम से stdio पर स्थानीय रूप से, या बिना किसी स्थानीय इंस्टॉल के https://mcp.superserve.ai पर होस्टेड एंडपॉइंट के विरुद्ध। दोनों आपके SUPERSERVE_API_KEY से प्रमाणित होते हैं और प्रति कॉल ID द्वारा एक सैंडबॉक्स को लक्षित करते हैं। यह TypeScript SDK के ऊपर एक पतला आवरण है, इसलिए प्रति-सैंडबॉक्स डेटा-प्लेन टोकन कभी मॉडल तक नहीं पहुँचता।
त्वरित शुरुआत
सर्वर को अपने क्लाइंट में जोड़ें (देखें इंस्टॉल), फिर एजेंट से कहें कि "एक सैंडबॉक्स बनाएँ और उसमें python --version चलाएँ।" एजेंट sandbox_create को कॉल करता है, फिर sandbox_exec को, और परिणाम रिपोर्ट करता है — आपकी ओर से कोई कोड नहीं।
आपको एक Superserve API कुंजी की आवश्यकता है — API कुंजी पृष्ठ पर एक बनाएँ। कोई वैश्विक इंस्टॉल नहीं है; npx पहले उपयोग पर सर्वर प्राप्त करता है।
इंस्टॉल करें
सर्वर के `env` में `SUPERSERVE_API_KEY` सेट करें — MCP क्लाइंट इसे आपके शेल से इनहेरिट नहीं करते। जहाँ आपका क्लाइंट इसका समर्थन करता हो, वहाँ कच्ची कुंजी चिपकाने के बजाय एक गुप्त-इनपुट संकेत को प्राथमिकता दें (नीचे VS Code देखें)। ```bash theme={"theme":{"light":"github-light","dark":"vitesse-dark"}} claude mcp add superserve \ --env SUPERSERVE_API_KEY=ss_live_xxxxxxxxxxxxxxxx \ -- npx -y @superserve/mcp ``` `claude_desktop_config.json` में जोड़ें (macOS: `~/Library/Application Support/Claude/`):```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
"mcpServers": {
"superserve": {
"command": "npx",
"args": ["-y", "@superserve/mcp"],
"env": { "SUPERSERVE_API_KEY": "ss_live_xxxxxxxxxxxxxxxx" }
}
}
}
```
`.cursor/mcp.json` (प्रोजेक्ट) या `~/.cursor/mcp.json` (वैश्विक) में जोड़ें:
```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
"mcpServers": {
"superserve": {
"command": "npx",
"args": ["-y", "@superserve/mcp"],
"env": { "SUPERSERVE_API_KEY": "ss_live_xxxxxxxxxxxxxxxx" }
}
}
}
```
`.vscode/mcp.json` में जोड़ें। `inputs` ब्लॉक कुंजी को सादे पाठ में संग्रहीत करने के बजाय इसके लिए संकेत देता है:
```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
"inputs": [
{
"id": "superserve-key",
"type": "promptString",
"description": "Superserve API key",
"password": true
}
],
"servers": {
"superserve": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@superserve/mcp"],
"env": { "SUPERSERVE_API_KEY": "${input:superserve-key}" }
}
}
}
```
`~/.codeium/windsurf/mcp_config.json` में जोड़ें:
```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
"mcpServers": {
"superserve": {
"command": "npx",
"args": ["-y", "@superserve/mcp"],
"env": { "SUPERSERVE_API_KEY": "ss_live_xxxxxxxxxxxxxxxx" }
}
}
}
```
`~/.codex/config.toml` में जोड़ें। `env_vars` आपके परिवेश से `SUPERSERVE_API_KEY` को अग्रेषित करता है, इसलिए कच्ची कुंजी कॉन्फ़िग फ़ाइल में संग्रहीत नहीं होती (पहले इसे अपने शेल में निर्यात करें)। Codex क्रॉस-टूल वर्कफ़्लो मार्गदर्शन के लिए सर्वर के `instructions` को भी पढ़ता है।
```toml theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
[mcp_servers.superserve]
command = "npx"
args = ["-y", "@superserve/mcp"]
env_vars = ["SUPERSERVE_API_KEY"]
```
[होस्टेड](#hosted-remote) एंडपॉइंट के लिए, `bearer_token_env_var = "SUPERSERVE_API_KEY"` के साथ `url = "https://mcp.superserve.ai"` का उपयोग करें।
होस्टेड (दूरस्थ)
स्थानीय रूप से कुछ भी नहीं चलाना चाहते? https://mcp.superserve.ai पर होस्टेड एंडपॉइंट स्ट्रीमेबल HTTP बोलता है — कोई npx नहीं, कोई Node नहीं। अपनी Superserve API कुंजी को बियरर टोकन के रूप में भेजें। एंडपॉइंट स्टेटलेस और खाता-स्कोप्ड है (आपकी कुंजी पहले से ही आपकी टीम से मैप होती है), और प्रति-सैंडबॉक्स डेटा-प्लेन टोकन कभी सर्वर नहीं छोड़ता।
```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
"mcpServers": {
"superserve": {
"url": "https://mcp.superserve.ai",
"headers": { "Authorization": "Bearer ss_live_xxxxxxxxxxxxxxxx" }
}
}
}
```
`.vscode/mcp.json` में जोड़ें। `inputs` ब्लॉक कुंजी को सादे पाठ में संग्रहीत करने के बजाय इसके लिए संकेत देता है:
```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
"inputs": [
{
"id": "superserve-key",
"type": "promptString",
"description": "Superserve API key",
"password": true
}
],
"servers": {
"superserve": {
"type": "http",
"url": "https://mcp.superserve.ai",
"headers": { "Authorization": "Bearer ${input:superserve-key}" }
}
}
}
```
इसे एक [Anthropic Messages API](https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector) अनुरोध में कनेक्टर के रूप में पास करें:
```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
"mcp_servers": [
{
"type": "url",
"name": "superserve",
"url": "https://mcp.superserve.ai",
"authorization_token": "ss_live_xxxxxxxxxxxxxxxx"
}
]
}
```
स्थानीय सर्वर के समान उपकरण और व्यवहार — एकमात्र अंतर ट्रांसपोर्ट है और यह कि कुंजी env चर के बजाय बियरर हेडर के रूप में यात्रा करती है।
उपकरण
| उपकरण | यह क्या करता है |
|---|---|
sandbox_create | एक नया सैंडबॉक्स बनाएँ; इसका id लौटाता है। तुरंत सक्रिय और तैयार। secrets और निकास नियम स्वीकार करता है। |
sandbox_update | निर्माण के बाद सैंडबॉक्स के मेटाडेटा या निकास (allow_out/deny_out) नियम बदलें। |
sandbox_list | अपने सैंडबॉक्स (सक्रिय और रुके हुए) सूचीबद्ध करें, मेटाडेटा द्वारा फ़िल्टर करने योग्य। |
sandbox_info | एक सैंडबॉक्स की स्थिति, संसाधन, मेटाडेटा, नेटवर्क नियम और गुप्त बाइंडिंग प्राप्त करें। केवल-पढ़ने के लिए। |
sandbox_exec | एक शेल कमांड चलाएँ; stdout, stderr, निकास कोड लौटाता है। रुके हुए सैंडबॉक्स को स्वतः-पुनः आरंभ करता है। |
sandbox_files_read | एक फ़ाइल पढ़ें (UTF-8 पाठ, या बाइनरी के लिए base64)। |
sandbox_files_write | एक फ़ाइल बनाएँ या अधिलेखित करें। मूल निर्देशिकाएँ स्वचालित रूप से बनाई जाती हैं। |
sandbox_files_list | एक निर्देशिका की प्रविष्टियाँ सूचीबद्ध करें (नाम, प्रकार, आकार, संशोधन समय)। |
sandbox_files_download_dir | एक निर्देशिका को base64 ZIP के रूप में डाउनलोड करें (सिमलिंक छोड़े गए)। 10 MiB पर सीमित; बड़ा → SDK/CLI। |
sandbox_pause | एक सैंडबॉक्स को रोकें; स्थिति संरक्षित है। |
sandbox_resume | एक रुके हुए सैंडबॉक्स को पुनः आरंभ करें (आमतौर पर अनावश्यक — exec स्वतः-पुनः आरंभ करता है)। |
sandbox_kill | एक सैंडबॉक्स को स्थायी रूप से हटाएँ। |
sandbox_preview_url | एक सुनने वाले पोर्ट के लिए सार्वजनिक URL बनाएँ (अप्रमाणीकृत — उस पोर्ट पर कुछ भी इंटरनेट-अनावृत है)। |
sandbox_network_log | एक सैंडबॉक्स के आउटबाउंड कनेक्शन का ऑडिट करें (होस्ट, निर्णय, बाइट्स)। रुके हुए सैंडबॉक्स को स्वतः-पुनः आरंभ करता है। |
sandbox_template_list | उन टेम्पलेट्स (आधार छवियाँ) को सूचीबद्ध करें जिन्हें आपकी टीम लॉन्च कर सकती है। |
sandbox_template_create | एक विशिष्ट vCPU/मेमोरी/डिस्क आकार या पूर्व-स्थापित सॉफ़्टवेयर के साथ एक कस्टम टेम्पलेट बनाएँ (एसिंक — तैयार होने के लिए पोल करें)। |
secret_list | बाइंड करने योग्य टीम सीक्रेट सूचीबद्ध करें (केवल मेटाडेटा — कभी मान नहीं)। |
sandbox_attach_secret | एक संग्रहीत सीक्रेट को एक env var के अंतर्गत चल रहे सैंडबॉक्स से बाइंड करें। |
sandbox_detach_secret | एक सैंडबॉक्स से एक सीक्रेट बाइंडिंग हटाएँ। |
अधिकांश उपकरण एक sandbox_id लेते हैं; अपवाद sandbox_create, sandbox_list, sandbox_template_list, sandbox_template_create, और secret_list हैं। ID प्राप्त करने के लिए इनमें से किसी एक से शुरू करें, फिर इसे बाद की कॉलों में थ्रेड करें। केवल-पढ़ने के उपकरण (sandbox_list, sandbox_info, sandbox_files_read, sandbox_files_list, sandbox_files_download_dir, sandbox_preview_url, sandbox_template_list, secret_list) एनोटेट किए गए हैं ताकि क्लाइंट पुष्टिकरण संकेतों को छोड़ सकें; sandbox_kill विनाशकारी एनोटेट किया गया है।
उदाहरण
"एक सैंडबॉक्स स्पिन अप करें, एक Python स्क्रिप्ट लिखें जो पहले अभाज्य संख्याएँ प्रिंट करे, और इसे चलाएँ" के लिए एक विशिष्ट एजेंट प्रवाह:
sandbox_create { name: "primes" }
→ { id: "a1b2c3…", name: "primes", status: "active" }
sandbox_files_write { sandbox_id: "a1b2c3…", path: "/app/primes.py", content: "…" }
→ { path: "/app/primes.py", bytes: 142 }
sandbox_exec { sandbox_id: "a1b2c3…", command: "python /app/primes.py" }
→ { exit_code: 0, stdout: "2 3 5 7 11 13 17 19 23 29", stderr: "" }
जब यह हो जाए, तो एजेंट sandbox_pause (स्थिति संरक्षित, रखने के लिए सस्ता) या sandbox_kill (स्थायी) कर सकता है।
कॉन्फ़िगरेशन
| चर | आवश्यक | विवरण |
|---|---|---|
SUPERSERVE_API_KEY | हाँ | आपकी Superserve API कुंजी (ss_live_ से शुरू होती है)। |
SUPERSERVE_BASE_URL | नहीं | नियंत्रण-प्लेन URL को ओवरराइड करें (डिफ़ॉल्ट https://api.superserve.ai है)। |
व्यवहार और सीमाएँ
- स्वतः-पुनः आरंभ।
sandbox_execऔर फ़ाइल उपकरण पारदर्शी रूप से एक रुके हुए सैंडबॉक्स को पुनः आरंभ करते हैं, इसलिए एजेंटों को कभी भी पहलेsandbox_resumeकॉल करने की आवश्यकता नहीं होती।sandbox_resumeकेवल एक सैंडबॉक्स को स्पष्ट रूप से गर्म करने के लिए मौजूद है। - आउटपुट संदर्भ के लिए सीमित है।
sandbox_execstdout और stderr को प्रत्येक 32 KiB तक छोटा करता है — एक छोटा किया गया परिणामtruncated: trueसेट करता है और मूल बाइट लंबाई की रिपोर्ट करता है।sandbox_files_read1 MiB से बड़ी फ़ाइलों को अस्वीकार करता है (यह आंशिक सामग्री नहीं लौटाता); त्रुटि आपकोsandbox_exec(जैसेhead -c) के साथ एक स्लाइस पढ़ने या SDK/CLI के साथ पूरी फ़ाइल डाउनलोड करने के लिए कहती है।sandbox_files_writeइनलाइन सामग्री 8 MiB पर सीमित है। - डिफ़ॉल्ट कमांड टाइमआउट 60s है, अधिकतम 10 मिनट पर सीमित। इसे प्रति कॉल
timeout_msके साथ ओवरराइड करें। - निकास नियंत्रणीय है।
allow_out(डोमेन पैटर्न या CIDR) अनुमत गंतव्य जोड़ता है;deny_out(केवल CIDR) उन्हें ब्लॉक करता है। अकेलाallow_outकिसी सैंडबॉक्स को लॉक डाउन नहीं करता — एक सख्त अनुमति सूची के लिए, इसेdeny_out: ["0.0.0.0/0"]के साथ संयोजित करें (सभी को अस्वीकार करें, फिर सूचीबद्ध गंतव्यों को अनुमति दें)। इन्हेंsandbox_createयाsandbox_updateपर सेट करें, औरsandbox_network_logके साथ ऑडिट करें कि एक सैंडबॉक्स वास्तव में कहाँ पहुँचा। - त्रुटियाँ कार्रवाई योग्य हैं। एक विफल उपकरण कॉल एक छोटा संदेश लौटाता है जो एजेंट को बताता है कि आगे क्या करना है — जैसे "सैंडबॉक्स कोटा पूरा हो गया। एक सैंडबॉक्स को रोकें या समाप्त करें, या बाद में पुनः प्रयास करें।" — एक कच्चे स्टैक ट्रेस के बजाय, ताकि एजेंट स्वयं-सही कर सके।
सीक्रेट, टेम्पलेट और पोर्ट
सीक्रेट। क्रेडेंशियल्स को सादे पाठ env_vars के रूप में पास न करें। इसके बजाय:
- TypeScript SDK (
Secret.create()) या कंसोल के साथ एक बार सीक्रेट बनाएँ — कच्चा मान कभी एजेंट या MCP सर्वर के माध्यम से यात्रा नहीं करता, इसलिए सीक्रेट निर्माण जानबूझकर एक MCP उपकरण नहीं है। secret_listके साथ बाइंड करने योग्य सीक्रेट खोजें (केवल मेटाडेटा — मान कभी प्लेटफ़ॉर्म नहीं छोड़ते)।- निर्माण पर बाइंड करें —
sandbox_createपरsecrets: { ANTHROPIC_API_KEY: "anthropic-prod" }— या बाद मेंsandbox_attach_secret/sandbox_detach_secretके साथ।
सैंडबॉक्स एक प्रॉक्सी टोकन देखता है; प्लेटफ़ॉर्म केवल सीक्रेट के अनुमत होस्ट के लिए आउटबाउंड अनुरोधों के लिए वास्तविक क्रेडेंशियल में बदलता है।
टेम्पलेट। एक सैंडबॉक्स अपने vCPU/मेमोरी/डिस्क को अपने टेम्पलेट से इनहेरिट करता है और sandbox_create समय पर उन्हें ओवरराइड नहीं कर सकता। एक विशिष्ट आकार (जैसे, एक 4 vCPU सैंडबॉक्स) या पूर्व-स्थापित सॉफ़्टवेयर प्राप्त करने के लिए, sandbox_template_create के साथ एक टेम्पलेट बनाएँ, फिर sandbox_template_list को तब तक पोल करें जब तक इसका status ready न हो जाए, इसे from_template के रूप में पास करने से पहले।
पोर्ट। सैंडबॉक्स में एक सर्वर शुरू करें (sandbox_exec, जैसे python3 -m http.server 8000), फिर इसका सार्वजनिक URL प्राप्त करने के लिए sandbox_preview_url कॉल करें। किसी पोर्ट से बंधी कोई भी प्रक्रिया https://{port}-{id}.sandbox.superserve.ai पर बिना प्रमाणीकरण के पहुँच योग्य है — केवल उन्हीं पोर्ट को उजागर करें जिन्हें आप सार्वजनिक करना चाहते हैं।
अभी तक MCP सतह में नहीं
MCP सर्वर सामान्य एजेंट लूप को कवर करता है; ऊपर दी गई तालिका पूर्ण v1 उपकरण सेट है। कुछ SDK क्षमताएँ अभी तक उजागर नहीं हुई हैं — सीधे TypeScript SDK के लिए पहुँचें:
- सीक्रेट निर्माण —
Secret.create()(MCP सर्वर केवल मौजूदा सीक्रेट को बाइंड करता है)। - स्ट्रीमिंग और इंटरैक्टिव कमांड —
run()कॉलबैक औरcommands.spawn(stdin, सिग्नल, लंबे समय तक चलने वाली प्रक्रियाएँ) स्ट्रीमिंग। - बड़े या स्ट्रीमिंग स्थानांतरण — निर्देशिका डाउनलोड
sandbox_files_download_dirके माध्यम से 10 MiB तक समर्थित है; उससे परे (और संग्रह/स्ट्रीमिंग अपलोड या 1 MiB पढ़ने / 8 MiB इनलाइन-लिखने की सीमा से अधिक एकल फ़ाइलों के लिए), SDK/CLI का उपयोग करें (files.downloadDir, स्ट्रीमिंग अपलोड)। - बिलिंग और प्रदाता खोज — उपयोग डेटा और सीक्रेट-प्रदाता सेटअप के लिए
Provider.list()।
इन्हें अनुवर्ती के रूप में ट्रैक किया जाता है।
यह कैसे काम करता है
सर्वर TypeScript SDK को लपेटता है और केवल आपके नियंत्रण-तल SUPERSERVE_API_KEY को धारण करता है। प्रत्येक उपकरण कॉल आईडी द्वारा लक्षित सैंडबॉक्स से जुड़ता है; एसडीके प्रति-सैंडबॉक्स डेटा-तल अभिगम टोकन को आंतरिक रूप से प्रबंधित करता है और पुनरारंभ पर इसे घुमाता है, इसलिए यह कभी भी मॉडल के सामने उजागर नहीं होता या उपकरण आउटपुट में वापस नहीं आता। उपकरण स्थितिहीन हैं — कोई छिपा हुआ "वर्तमान सैंडबॉक्स" नहीं है — जो बहु-मोड़ और समानांतर उपकरण कॉल में व्यवहार को पूर्वानुमेय बनाए रखता है।
समस्या निवारण
- उपकरण दिखाई नहीं देते, या सर्वर प्रारंभ होने में विफल रहता है। एपीआई कुंजी लगभग हमेशा कारण होती है — एमसीपी क्लाइंट आपके शेल से पर्यावरण चर प्राप्त नहीं करते हैं। सर्वर के
envब्लॉक मेंSUPERSERVE_API_KEYसेट करें (देखें इंस्टॉल), न कि केवल अपने टर्मिनल में। Authentication failed। कुंजी गुम है या अमान्य है। उत्पादन कुंजियाँss_live_से शुरू होती हैं; एपीआई कुंजी पृष्ठ पर एक बनाएँ।- पहली कॉल धीमी है।
npxपहले उपयोग पर पैकेज डाउनलोड करता है और इसे कैश करता है; बाद के प्रारंभ तेज़ होते हैं। - Node 18+ आवश्यक है। स्थानीय सर्वर
npxके माध्यम से Node पर चलता है। (होस्टेड समापन बिंदु की कोई स्थानीय रनटाइम आवश्यकता नहीं है।) - होस्टेड समापन बिंदु से
401 Unauthorized। बियरर टोकन गुम है या मान्यss_live_कुंजी नहीं है। इसेAuthorization: Bearer ss_live_…के रूप में भेजें (देखें होस्टेड)।