เซิร์ฟเวอร์ MCP

ตำแหน่งในพอร์ทัล: API reference › Tools (https://<your-domain>/apidoc) แสดงเอนด์พอยต์และสนิปเป็ตสำหรับไคลเอนต์ โดยสร้างคีย์ได้ที่ API keys (/api-keys) ไม่มีตั้งค่าในส่วนผู้ดูแลระบบ เนื่องจากเอนด์พอยต์นี้เป็นส่วนหนึ่งของแผงควบคุม

What it does

Model Context Protocol (MCP) ช่วยให้ผู้ช่วย AI สามารถเรียกใช้งานเครื่องมือต่างๆ ได้ NexCMP มีเอนด์พอยต์ MCP ที่ https://<your-domain>/mcp การทำงานของ API สาธารณะทุกรายการจะกลายเป็น เครื่องมือ หนึ่ง (vm_list, vm_start, billing_wallet, ...) ทำให้ลูกค้าสามารถถามผู้ช่วยได้ว่า "VM ไหนของฉันกำลังทำงานอยู่?" หรือ "หยุดการทำงานของ staging VM ให้หน่อย" โดยผู้ช่วยจะดำเนินการด้วยคีย์ API และสิทธิ์ของตัวลูกค้าเองเท่านั้น

กำลังกำหนดค่าตัว NexCMP เองด้วย AI อยู่ใช่ไหม

หน้านี้คือเอนด์พอยต์ MCP ของลูกค้า (/mcp) หากต้องการให้ผู้ช่วย AI ช่วยกำหนดค่าแผงควบคุมของคุณเองในฐานะผู้ดูแลระบบ โปรดดูที่ Configure with AI (เอนด์พอยต์ /mcp/admin, คีย์ของผู้ดูแลระบบ ak_)

ข้อกำหนด

Item	Requirement
Server	ไม่ต้องติดตั้ง: เอนด์พอยต์นี้ให้บริการโดยแผงควบคุมและสามารถเข้าถึงได้ทุกที่ที่แผงควบคุมตั้งอยู่ รีเวิร์สพร็อกซี่ของคุณต้องส่งต่อ `/mcp` ไปยังแผงควบคุม
ลูกค้า	API key (`vk_...`) ที่มีสิทธิ์ (scopes) ตามที่ผู้ช่วยต้องการ
ไคลเอนต์	ไคลเอนต์ MCP ที่รองรับการรับส่งข้อมูลแบบ Streamable HTTP และส่วนหัว `Authorization` แบบกำหนดเอง เช่น Claude Code, Claude Desktop (ผ่านบริดจ์ `mcp-remote`), Cursor, VS Code ในโหมด Copilot agent และอื่นๆ ที่คล้ายคลึงกัน
เวอร์ชันโปรโตคอล	2025-11-25, 2025-06-18 และ 2025-03-26

เตรียมโครงสร้างพื้นฐาน

ไม่มีอะไรมากไปกว่าการตรวจสอบให้แน่ใจว่า https://<your-domain>/mcp ไม่ถูกบล็อกโดยไฟร์วอลล์หรือกฎของพร็อกซี่ ไคลเอนต์ MCP บนเบราว์เซอร์จากต้นทางอื่นจะถูกปฏิเสธเว้นแต่จะได้รับอนุญาตให้ใช้ต้นทางนั้น ส่วนไคลเอนต์บรรทัดคำสั่งและเดสก์ท็อปจะไม่ส่งส่วนหัว Origin และสามารถทำงานได้ตามปกติ

การเชื่อมต่อ (ฝั่งลูกค้า)

สร้างคีย์ API ในพอร์ทัล (API keys › Create key) โดยกำหนดเฉพาะสิทธิ์ที่คุณต้องการให้ผู้ช่วยใช้ วันหมดอายุที่สั้น และจำกัด IP หากเป็นไปได้
เพิ่มเซิร์ฟเวอร์ลงในไคลเอนต์ของคุณ แทนที่ cloud.example.com และคีย์
Claude Code
bash
```
claude mcp add --transport http cloud https://cloud.example.com/mcp \
  --header "Authorization: Bearer vk_XXXX"
```
Cursor (~/.cursor/mcp.json หรือ .cursor/mcp.json; ตั้งค่า CLOUD_API_KEY ในสภาพแวดล้อมที่ Cursor เริ่มต้นทำงาน):
json
```
{
  "mcpServers": {
    "cloud": {
      "url": "https://cloud.example.com/mcp",
      "headers": { "Authorization": "Bearer ${env:CLOUD_API_KEY}" }
    }
  }
}
```
Claude Desktop (ต้องใช้ Node.js 18+; claude_desktop_config.json) ผ่านทางบริดจ์ mcp-remote:
json
```
{
  "mcpServers": {
    "cloud": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp", "--header", "Authorization:${CLOUD_AUTH_HEADER}"],
      "env": { "CLOUD_AUTH_HEADER": "Bearer vk_XXXX" }
    }
  }
}
```
เขียนส่วนหัวโดยไม่มีเว้นวรรคหลังเครื่องหมายทวิภาค และใส่ค่าทั้งหมดลงในตัวแปรสภาพแวดล้อมดังตัวอย่างด้านบน
รีสตาร์ทไคลเอนต์แล้วขอให้แสดงรายการเครื่องมือของคุณ

ตรวจสอบการเชื่อมต่อโดยไม่ต้องใช้ไคลเอนต์:

bash

curl -s https://cloud.example.com/mcp \
  -H "Authorization: Bearer vk_XXXX" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

วิธีการทำงาน

Item	Detail
Endpoint	`POST /mcp` พร้อมข้อความ JSON-RPC 2.0 คำตอบคือ `application/json` `GET /mcp` จะตอบกลับด้วย 405 (ไม่มีสตรีมจากเซิร์ฟเวอร์ไปยังไคลเอนต์); `DELETE /mcp` จะสิ้นสุดเซสชัน
การยืนยันตัวตน	เฉพาะ `Authorization: Bearer vk_...` เท่านั้น (โทเค็นเซสชัน คุกกี้ และคีย์ผู้ดูแลระบบจะถูกปฏิเสธด้วยสถานะ 401 และส่วนหัว `WWW-Authenticate: Bearer`)
เซสชัน	`Mcp-Session-Id` ออกโดย `initialize` ผูกกับคีย์นั้น และมีอายุการใช้งาน 24 ชั่วโมง โดยมีเซสชันสูงสุด 16 เซสชันต่อคีย์
เครื่องมือ	หนึ่งรายการต่อการทำงานของ API สาธารณะที่คีย์มองเห็น ชื่อเครื่องมือคือคำสั่ง CLI ที่ใช้ `_` แทนที่ช่องว่างและขีด (`vm firewall add` กลายเป็น `vm_firewall_add`) และตรงกับ `operationId` ของ OpenAPI เครื่องมือจะแสดงรายการก็ต่อเมื่อคีย์มีสิทธิ์นั้นและเปิดใช้งานโมดูลอยู่
ความสามารถ	เฉพาะเครื่องมือเท่านั้น (ไม่มีทรัพยากรหรือพรอมต์)
ขนาด	เนื้อหาคำขอสูงสุด 1 MB; ข้อความผลลัพธ์ของเครื่องมือสูงสุดประมาณ 100 KB (ส่วนที่เหลือจะถูกตัดทอนพร้อมหมายเหตุ); การเรียกใช้งานแต่ละครั้งใช้เวลาสูงสุด 55วินาที

กฎความปลอดภัย

ประตูเดียวกันกับ REST. แต่ละ tools/call จะต้องผ่านท่อส่งคำขอของระบบเอง ทั้งขอบเขต ขอบเขตเว็บไซต์ การจำกัด IP การจำกัดอัตราการเรียกใช้ ความเป็นอิสระ การตรวจสอบความเป็นเจ้าของ (แสดง 404 สำหรับทรัพยากรของผู้อื่น) และโควตาจะมีผลทั้งหมด MCP ไม่สามารถให้สิทธิ์เกินกว่าที่คีย์มีอยู่
การยืนยัน. เครื่องมือที่มีค่าใช้จ่าย มีการลบ หรือส่งคืนข้อมูลรับรอง (ตั๋วคอนโซล, kubeconfig, ข้อมูลลับ S3 หรือ SSH, การรีเซ็ตรหัสผ่าน, คีย์ใหม่) จำเป็นต้องมีอาร์กิวเมนต์ confirm: true คำอธิบายเครื่องมือจะบอกให้ผู้ช่วยส่งต่อเมื่อผู้ใช้ได้รับการอนุมัติแล้วเท่านั้น ดังนั้นคำสั่งที่ซ่อนอยู่ในหน้าเว็บหรือบันทึกจึงไม่สามารถเรียกใช้งานได้ด้วยตัวเอง
ความเป็นอิสระของการทำซ้ำ (Idempotency). เครื่องมือที่มีค่าใช้จ่ายจะยอมรับ idempotency_key; หากละเว้น คีย์เสถียรจะถูกสร้างขึ้นจากชื่อเครื่องมือและอาร์กิวเมนต์ ดังนั้นการลองใหม่ที่เหมือนกันจึงไม่สามารถคิดเงินซ้ำได้
ไม่เปิดเผยเป็นเครื่องมือ: จุดสิ้นสุดสำหรับการสตรีม (แชท AI Agent), ตั๋ว SSH หรือคอนโซล WebSocket แบบใช้ครั้งเดียว, การดาวน์โหลดไบนารี และจุดสิ้นสุดแอป VPN (/v1/ext/*)
เป็นไปไม่ได้อย่างเด็ดขาด: API ไม่อนุญาตให้เติมเงิน เปลี่ยนรหัสผ่าน ลบ 3 บัญชี หรือสร้างคีย์ ดังนั้นจึงไม่มีผู้ช่วยใดสามารถทำสิ่งเหล่านี้ได้

ขีดจำกัด

ขีดจำกัด	ค่าเริ่มต้น
การเรียกใช้เครื่องมือต่อคีย์	60 ครั้งต่อนาที
คำขอ MCP ต่อคีย์	240 ครั้งต่อนาที
บวกกับขีดจำกัดคีย์และบัญชีปกติ	ดู REST API

หากเกินขีดจำกัด จุดสิ้นสุดจะตอบกลับด้วย HTTP 429 พร้อมข้อผิดพลาด JSON-RPC และ Retry-After

ตรวจสอบ

คำสั่ง curl ด้านบนจะส่งคืนผลลัพธ์ JSON-RPC พร้อมรายการ tools โดยจะมีเฉพาะเครื่องมือที่ตรงกับขอบเขตของคีย์เท่านั้นที่ปรากฏ
ในไคลเอนต์ของคุณ ให้ถามว่า "list my VMs": ผู้ช่วยจะเรียก vm_list และแสดงผลลัพธ์
ในพอร์ทัล เวลา Last used ของคีย์จะเปลี่ยนไป และการเรียกที่เขียนข้อมูลจะปรากฏใน Key usage log

ขีดจำกัดและหมายเหตุ

การเข้าสู่ระบบผ่านเบราว์เซอร์ (OAuth). หน้าอ้างอิงยังอธิบายถึงการเข้าสู่ระบบผ่านเบราว์เซอร์สำหรับไคลเอนต์ที่รองรับ MCP OAuth อีกด้วย สำหรับ NexCMP ที่ติดตั้งแล้ว วิธีการที่รองรับและผ่านการทดสอบคือคีย์ API (หรือ cmp login สำหรับ CLI)
เว็บไซต์ตัวแทนจำหน่าย จะไม่แสดงส่วน MCP โดยลูกค้าของพวกเขาจะใช้โดเมนของตัวแทนจำหน่ายสำหรับ API
สิทธิ์น้อยที่สุด (Least privilege). สร้างคีย์เฉพาะสำหรับผู้ช่วยแต่ละตัวโดยให้ขอบเขตการอ่านก่อน แล้วจึงเพิ่มขอบเขตการเขียนเมื่อจำเป็นเท่านั้น
เพิกถอนคีย์ใน API keys เพื่อตัดการเข้าถึงของผู้ช่วยทันที

การแก้ Problme

อาการ	สาเหตุ	วิธีแก้ปัญหา
401 พร้อม `WWW-Authenticate: Bearer`	ไม่มีคีย์ คีย์ไม่ถูกต้อง หรือโทเค็นเซสชัน	ส่ง `Authorization: Bearer vk_...`
403 เกี่ยวกับ `Origin`	หน้าเว็บเบราว์เซอร์บนต้นทางอื่น	ใช้เดสก์ท็อปหรือไคลเอนต์ CLI หรือขอให้ผู้ดูแลระบบของคุณอนุญาตต้นทาง (`mcp_allowed_origins`)
404 ในคำขอที่มี `Mcp-Session-Id`	เซสชันเป็นของคีย์อื่นหรือหมดอายุแล้ว	เรียกใช้ `initialize` อีกครั้ง
405 บน `GET /mcp`	ที่คาดไว้: เซิร์ฟเวอร์ไม่มีสตรีมเหตุการณ์	ใช้ POST เท่านั้น (ไคลเอนต์จะทำสิ่งนี้โดยอัตโนมัติ)
รายการเครื่องมือสั้นเกินไป	ขอบเขตคีย์หรือโมดูล	เพิ่มขอบเขตให้กับคีย์; เปิดใช้งานโมดูล
เครื่องมือตอบกลับว่าต้องการ `confirm: true`	เครื่องมือที่มีค่าใช้จ่าย การลบ หรือละเอียดอ่อน	ผู้ช่วยต้องตั้งค่า `confirm` หลังจากที่คุณอนุมัติ
429	ขีดจำกัดอัตรา MCP หรือคีย์	รอ `Retry-After`
ไคลเอนต์ไม่สามารถเชื่อมต่อด้วยส่วนหัวได้	ไคลเอนต์ไม่มีการรองรับส่วนหัวแบบกำหนดเอง	ใช้บริดจ์ `mcp-remote`

เซิร์ฟเวอร์ MCP ​

What it does ​

ข้อกำหนด ​

เตรียมโครงสร้างพื้นฐาน ​

การเชื่อมต่อ (ฝั่งลูกค้า) ​

วิธีการทำงาน ​

กฎความปลอดภัย ​

ขีดจำกัด ​

ตรวจสอบ ​

ขีดจำกัดและหมายเหตุ ​

การแก้ Problme ​