MCP server ทำอะไรได้บ้าง
MCP (Model Context Protocol) คือมาตรฐานเปิดที่แอป AI ใช้เรียกเครื่องมือภายนอก
พอเชื่อมต่อแล้ว ผู้ช่วย AI จะตัดสินใจเองว่าเมื่อไรควรเรียกเครื่องมือของเรา ลองบอกว่า “ขอไอคอน 3D หมาจิ้งจอกน่ารักๆ ทำไอคอนแอป” มันจะค้นหาในคลัง โชว์ตัวอย่างให้ดู แล้วส่งลิงก์ดาวน์โหลดหรือสร้างแบบใหม่ให้ได้ โดยไม่ต้องเปิดเว็บเลย
- ค้นหาไอคอนกว่า 12,000 ชิ้น ด้วยคำค้น หมวดหมู่ สไตล์ (realistic / isometric / clay) หรือ collection ที่คัดไว้
- มองเห็นไอคอนจริง: get_icon แนบรูปตัวอย่างไปด้วย ผู้ช่วยที่รองรับรูปภาพจะประเมินให้ได้
- ดาวน์โหลดไฟล์ 512px หรือต้นฉบับ และสร้างไอคอนใหม่ด้วย Studio โดยคิดเครดิตแบบเดียวกับบนเว็บทุกประการ
ทุก tool เป็นของแพลน Studio ทั้งค้นหา ดูรายละเอียด ดาวน์โหลด 512px/ต้นฉบับ สร้างไอคอน และดูข้อมูลบัญชี ต้องใช้ API key ส่วนตัวของบัญชี Studio (Settings → API keys) ถ้าไม่มีคีย์ หรือใช้คีย์ของแพลน Free/Designer จะเชื่อมต่อและเห็นรายชื่อ tool ได้ แต่เรียกใช้ไม่ได้ทุกตัว ส่วนบนเว็บยังเข้าดูและค้นหาไอคอนได้ฟรีเหมือนเดิม
Endpoint
URL เดียว ใช้ Streamable HTTP ไม่มี session ค้าง
client ที่รองรับ MCP ทุกตัวจะถาม URL ของ server ของเราคือ:
เปิด URL นี้ในเบราว์เซอร์จะเห็นการ์ด JSON บอกรายชื่อ tools ส่วน client จะคุยกับมันด้วย JSON-RPC ผ่าน POST เอง คุณไม่ต้องเรียกเองเลย
https://realisticicon.com/api/mcpเชื่อมต่อ client
สามขั้น ใช้เวลาประมาณหนึ่งนาที
- ถ้าอยู่บนแพลน Studio ให้สร้าง API key ที่ Settings → API keys แล้วคัดลอกไว้ (แสดงครั้งเดียว)
- เพิ่ม server ใน client ด้วย URL ด้านล่าง พร้อม header Authorization
- สั่งผู้ช่วย AI ให้หาไอคอน มันจะค้นพบ tools เองอัตโนมัติ
ทดสอบ: ถามว่า “มี tool อะไรจาก realisticicon บ้าง” ผู้ช่วยควรตอบรายชื่อ search_icons, get_icon และตัวอื่นๆ
# the key is required — MCP is part of the Studio plan
claude mcp add --transport http realisticicon https://realisticicon.com/api/mcp \
--header "Authorization: Bearer blu_live_YOUR_KEY"รันครั้งเดียวใน terminal ใส่ `--scope user` ถ้าอยากใช้ได้ทุกโปรเจกต์ เช็คสถานะด้วย `claude mcp list`
API key
คีย์ผูก server เข้ากับบัญชี Studio และเครดิตของคุณ
- เข้าสู่ระบบแล้วเปิด Settings → API keys
- กด Create key ตั้งชื่อ (เช่น “Claude Code”, “Cursor”) แล้วคัดลอกคีย์ คีย์ขึ้นต้นด้วย blu_live_ และแสดงเพียงครั้งเดียว
- ส่งเป็น header Authorization: Bearer blu_live_… ตอนเพิ่ม server
- หมุนเวียนหรือเพิกถอนได้จากหน้าเดิมทุกเมื่อ คีย์เก่าจะหยุดทำงานทันที
- คีย์ใช้เครดิตของคุณได้ (ดาวน์โหลด, สร้างไอคอน) ดูแลเหมือนรหัสผ่าน
- คีย์แก้ไขบัญชี ซื้อเครดิต หรือสร้างคีย์เพิ่มไม่ได้ สิ่งเหล่านั้นต้องล็อกอินผ่านเบราว์เซอร์
- มีคีย์ที่ใช้งานได้สูงสุด 10 ตัว แนะนำแยกคีย์ต่อเครื่องมือ จะได้เพิกถอนทีละตัวได้
Tools
สิ่งที่ผู้ช่วย AI เรียกได้ ทุก tool ตอบกลับทั้งข้อความอ่านง่ายและข้อมูลแบบมีโครงสร้าง
| Tool | ต้องใช้ | ทำอะไร | ลองพูดว่า |
|---|---|---|---|
search_icons | API key | ค้นหาไอคอนด้วยคำค้น หมวดหมู่ สไตล์ ชนิด (image / video) หรือ collection ได้ผลลัพธ์ทีละหน้า พร้อม URL ตัวอย่าง 256px และลิงก์หน้าไอคอน | “หาไอคอน 3D แก้วกาแฟ สไตล์ clay ให้หน่อย” |
get_icon | API key | รายละเอียดเต็มของไอคอนหนึ่งชิ้น คำอธิบาย แท็ก prompt ที่ใช้สร้าง ขนาดที่มี พร้อมรูป 128px ให้ผู้ช่วยมองเห็น | “ขอดูอันที่สอง แล้วบอกว่ามีขนาดอะไรบ้าง” |
list_collections | API key | รายชื่อ collection ที่คัดไว้ (Christmas, Marketing essentials, …) เอาไปใส่ search_icons เพื่อไล่ดูได้ | “มี collection ตามธีมอะไรบ้าง” |
get_account | API key | แพลน ยอดเครดิต ขนาดดาวน์โหลดสูงสุด และรวมการสร้างด้วย Studio หรือไม่ | “เหลือเครดิตเท่าไร” |
download_icon | API key | URL ไฟล์ตรงที่ 256px (ฟรี), 512px หรือ PNG ต้นฉบับ หักเครดิตครั้งแรกที่ดาวน์โหลดไอคอนนั้นแบบความละเอียดสูง ดาวน์โหลดซ้ำฟรี | “ดาวน์โหลดหมาจิ้งจอกตัวนั้นที่ 512px” |
generate_icon | API key | สร้างไอคอนใหม่ 1–4 รูปจาก prompt ด้วย Studio ใช้ไอคอนในคลังเป็นตัวอ้างอิงสไตล์ได้ ได้ URL รูปและ prompt ที่ขยายแล้ว (ปกติใช้เวลา 1–2 นาที) | “สร้างไอคอน 3D แพนด้าแดงถือแก้วกาแฟ” |
list_generations | API key | รายการที่คุณสร้างด้วย Studio ล่าสุด พร้อม URL รูปและ prompt ผู้ช่วยจะได้หยิบของเดิมมาใช้แทนการเสียเครดิตสร้างซ้ำ | “ขอดูไอคอนที่ฉันสร้างไว้ครั้งก่อน” |
เครดิตและแพลน
กติกาเดียวกับบนเว็บ เพราะ MCP server เรียกโค้ดคิดเงินชุดเดียวกัน
- 256px หรือเล็กกว่า: ไม่หักเครดิต แต่ก็ยังต้องเรียกด้วยคีย์เหมือน tool อื่น
- 512px และต้นฉบับ: 1 เครดิตในครั้งแรกที่ดาวน์โหลดไอคอนนั้น ดาวน์โหลดไอคอนเดิมซ้ำขนาดใดก็ฟรี แพลน Studio ดาวน์โหลดไอคอนใหม่ได้สูงสุดวันละ 60 ชิ้น
- การสร้างด้วย Studio: คิดต่อรูปตามอัตราของ Studio กันเครดิตไว้ก่อนรัน และคืนให้สำหรับรูปที่สร้างไม่สำเร็จ
- ถ้าเครดิตหมด tool จะบอกผู้ช่วย AI ให้พาคุณไปหน้า Billing แทนที่จะลองซ้ำ
- คีย์ของแพลน Free หรือ Designer เห็นรายชื่อ tool ได้แต่เรียกใช้ไม่ได้ เหมือนไม่มีคีย์ ทุก tool ต้องเป็นบัญชี Studio อัปเกรดแล้วคีย์เดิมใช้ได้ทันที
- 3D เป็นฟีเจอร์เบต้าของแพลน Studio: generate_icon ที่ kind เป็น "3d" จะถูกปฏิเสธในแพลนอื่น
| แพลน | ขนาดดาวน์โหลดสูงสุด | สร้างด้วย Studio |
|---|---|---|
| Studio | 1024px | รวมอยู่ในแพลน |
ตัวอย่างคำสั่ง
คำสั่งที่ใช้ได้ดีเมื่อเชื่อมต่อ server แล้ว
- “อยากได้ไอคอนแอปติดตามนิสัย ขอดูตัวเลือก 3D แบบ realistic 6 แบบ”search_icons → เห็นตัวอย่างในแชท → สั่งต่อว่า “อันที่สาม แต่เป็นสไตล์ isometric” เพื่อปรับ
- “สามอันนี้ อันไหนเข้ากับพื้นหลังสีกรมท่าที่สุด”get_icon ทีละอัน → ผู้ช่วยดูรูปจริงก่อนตอบ
- “ขอไฟล์ต้นฉบับของไอคอนหมาจิ้งจอกอาร์กติก”get_account (เช็คแพลน) → download_icon size=original → ได้ URL ไว้บันทึก
- “ทำไอคอน 3D จรวดสไตล์ clay ให้เหมือนสไตล์ของไอคอน cute-shiba-inu-icon”generate_icon พร้อม referenceIconIds → ได้ PNG ใหม่ และบันทึกในประวัติ Studio ด้วย
ข้อจำกัด
เหลือเฟือสำหรับคนใช้จริง แต่รัดกุมสำหรับ loop ที่หลุด
- เรียก tool ได้ 300 ครั้งต่อเดือน ตามที่การ์ด Studio เขียนไว้ — get_account บอกว่าเหลือเท่าไรและรีเซ็ตเมื่อไร ทุกการเรียก tool นับ รวม search_icons ด้วย ส่วนการเชื่อมต่อ ดูรายชื่อ tool และตัว get_account เองไม่นับ
- 300 คำขอต่อนาทีต่อคีย์ (คำขอที่ไม่มีคีย์ไปไม่ถึง tool อยู่แล้ว) เกินจากนั้นจะได้ 429 พร้อม Retry-After
- ค้นหาได้สูงสุด 50 ไอคอนต่อหน้า ไล่หน้าต่อด้วย page และ seed ที่ tool ส่งกลับมา
- generate_icon ทำงานแบบรอผล อาจใช้เวลาถึงสองสามนาที และจำกัด count ไม่เกิน 4 รูปต่อครั้ง
- รูปตัวอย่างที่แนบในผลลัพธ์ถูกย่อเหลือ 256px เพื่อให้บทสนทนาเบา
แก้ปัญหา
ข้อความที่ผู้ช่วย AI จะบอก และสิ่งที่ควรทำ
| เจอข้อความ | ทำแบบนี้ |
|---|---|
| 401 “`get_icon` is part of the Studio plan and needs an API key” | เชื่อมต่อโดยไม่มีคีย์ จึงเห็นรายชื่อ tool ได้แต่เรียกใช้ไม่ได้ สร้างคีย์จากบัญชีแพลน Studio ที่ Settings → API keys แล้วเพิ่ม header Authorization จากนั้นเชื่อมต่อใหม่ |
| “The API key was rejected (invalid_api_key / api_key_revoked)” | พิมพ์ผิด หรือคีย์ถูกหมุนเวียน/เพิกถอนแล้ว คัดลอกคีย์ปัจจุบันจาก Settings หรือสร้างใหม่ |
| “Not enough credits” | เติมเครดิตหรืออัปเกรดที่หน้า Billing ดาวน์โหลด 256px ยังใช้ได้ฟรี |
| 403 “`download_icon` is included in the Studio plan only” | คีย์ใช้ได้ แต่บัญชีอยู่บนแพลน Free หรือ Designer ซึ่งไม่มีสิทธิ์ใช้ MCP อัปเกรดเป็น Studio ที่หน้า Billing แล้วคีย์เดิมจะใช้ได้ทันที |
| client บอกว่าติดต่อ server ไม่ได้ | เช็คว่า URL ลงท้ายด้วย /api/mcp และใช้ https เปิดในเบราว์เซอร์ควรเห็นการ์ด JSON |
| 429 rate_limited | รอตามวินาทีใน Retry-After แล้วลดความถี่ของระบบอัตโนมัติลง โควตา 300/นาที คิดต่อคีย์ |
| 429 monthly_limit_reached | บัญชีใช้โควตา 300 ครั้งของเดือนนี้หมดแล้ว เริ่มใหม่วันที่ 1 ของเดือนถัดไป ระหว่างนี้ get_account ยังเรียกได้ และบอกเวลารีเซ็ตที่แน่นอน |
REST API
คลังไอคอนและการคิดเครดิตชุดเดียวกัน สำหรับโค้ดของคุณเอง
HTTPS กับ JSON ธรรมดา ใช้ได้กับ server, script และ build pipeline อ่านคลังไอคอนชุดเดียวกัน และหักเครดิตด้วยโค้ดเดียวกับเว็บและ MCP server
- การยืนยันตัวตน: ใช้ API key ส่วนตัวตัวเดียวกับ MCP — Authorization: Bearer blu_live_… — จากบัญชี Studio คีย์ของบัญชี Free หรือ Designer จะได้ 403 plan_not_allowed
- เรียกได้ 5,000 ครั้งต่อเดือนต่อบัญชี นับแยกจาก MCP ส่วน GET /api/v1/me ไม่นับ และบอกว่าเหลือกี่ครั้ง
- เครดิตคิดเหมือนบนเว็บทุกประการ: ดาวน์โหลด 256px ฟรี ภาพความละเอียดสูงหักเครดิตครั้งแรกที่เอาไอคอนนั้น ครั้งต่อไปฟรี
- ยังไม่มี endpoint สำหรับสร้างไอคอน ให้สร้างบนเว็บ หรือใช้ generate_icon ของ MCP server
https://realisticicon.com/api/v1เก็บคีย์ไว้ฝั่ง server คีย์ใช้เครดิตของคุณได้ จึงควรเรียก API จาก backend ไม่ใช่จากหน้าเว็บ และทุก POST ต้องส่ง Content-Type: application/json ไม่อย่างนั้นคำขอจะถูกปฏิเสธก่อนถึง API
# search
curl "https://realisticicon.com/api/v1/icons?q=fox&limit=5" \
-H "Authorization: Bearer blu_live_YOUR_KEY"
# download — charged the first time you take this icon
curl -X POST "https://realisticicon.com/api/v1/icons/ICON_ID/download" \
-H "Authorization: Bearer blu_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"size":"512"}'Endpoint ของ REST
มี 6 endpoint รับและส่งเป็น JSON
| Method | Path | ทำอะไร | เครดิต |
|---|---|---|---|
| GET | /api/v1/icons | ค้นหาหรือไล่ดูไอคอน พารามิเตอร์: q, category, style (realistic · isometric · clay), kind (image · video), collection, page, limit (สูงสุด 50 ค่าเริ่มต้น 24), seed, locale ผลแบบไล่ดูจะส่ง seed กลับมา ให้ส่งค่านั้นไปกับหน้าถัดไปเพื่อให้ลำดับไม่เปลี่ยน | — |
| GET | /api/v1/icons/{id} | ไอคอนหนึ่งชิ้น: คำอธิบาย แท็ก prompt ที่ใช้สร้าง ขนาดที่มี รูปตัวอย่าง 256px และลิงก์หน้าไอคอน | — |
| POST | /api/v1/icons/{id}/download | Body {"size": "256" | "512" | "original"} (ค่าเริ่มต้น 512) ได้ URL ไฟล์ บอกว่าครั้งนี้หักเครดิตไหม และยอดเครดิตที่เหลือ | 256px ฟรี ส่วน 512px หรือต้นฉบับ: 1 เครดิตในครั้งแรกของไอคอนนั้น ครั้งต่อไปฟรี วันละไม่เกิน 60 ไอคอนใหม่ |
| GET | /api/v1/collections | collection ที่คัดไว้ กรองตาม theme ได้ เอา id ของ collection ไปใส่ collection= ใน /icons เพื่อดูไอคอนในชุดนั้น | — |
| GET | /api/v1/generations | รายการที่คุณสร้างด้วย Studio ล่าสุด พร้อม URL รูป (limit สูงสุด 40) | — |
| GET | /api/v1/me | แพลน เครดิต ขนาดดาวน์โหลดสูงสุด และจำนวนครั้งที่เรียก API เดือนนี้ ไม่นับรวมใน 5,000 ครั้ง | — |
GET /api/v1 ไม่ต้องใช้คีย์ จะได้การ์ด JSON บอกรายชื่อ endpoint ทั้งหมด ใส่ locale=th (หรือภาษาอื่นของเว็บ) เพื่อให้ชื่อไอคอนและลิงก์หน้าเป็นภาษานั้น
Error และข้อจำกัดของ REST
ใช้ status code มาตรฐาน และรูปแบบ JSON แบบเดียว
ทุก error มีหน้าตาแบบ { "error": { "code": "…", "message": "…" } } ให้เขียนโค้ดแยกกรณีด้วย code ซึ่งจะไม่เปลี่ยน ส่วน message เขียนไว้ให้คนอ่าน และอาจเปลี่ยนถ้อยคำได้
| Status | code | ความหมาย |
|---|---|---|
| 400 | invalid_request | พารามิเตอร์ขาดหรือเกินช่วง ข้อความจะบอกชื่อพารามิเตอร์ |
| 401 | missing_api_key · invalid_api_key | ไม่ได้ส่งคีย์ หรือคีย์ผิด ถูกหมุนเวียน หรือถูกเพิกถอนแล้ว |
| 402 | insufficient_credits | เครดิตไม่พอสำหรับการดาวน์โหลดนั้น เติมเครดิตได้ที่หน้า Billing |
| 403 | plan_not_allowed · over_plan_cap | บัญชีของคีย์ไม่ใช่แพลน Studio หรือขนาดที่ขอเกินเพดานของแพลน |
| 404 | not_found | ไม่มีไอคอน collection หรือ endpoint นั้น |
| 405 | method_not_allowed | path ถูกแต่ method ผิด ดู method ที่ถูกได้จาก header Allow |
| 429 | rate_limited · monthly_limit_reached · daily_limit_reached | เกิน 300 คำขอต่อนาทีต่อคีย์ (รอตาม Retry-After) หรือเกิน 5,000 ครั้งต่อเดือน (รีเซ็ตตาม X-Quota-Reset) หรือเกินเพดานดาวน์โหลดไอคอนใหม่ต่อวันของแพลน (รีเซ็ตเที่ยงคืน UTC) |
| 5xx | upstream_unavailable · internal_error | ปัญหาฝั่งเรา ลองใหม่ได้อย่างปลอดภัย ไอคอนเดิมจะไม่ถูกหักเครดิตซ้ำ |
- X-RateLimit-Limit และ X-RateLimit-Remaining: ของนาทีนี้
- X-Quota-Limit, X-Quota-Remaining และ X-Quota-Reset: ของเดือนนี้ (UTC)
- Retry-After: มากับทุก 429 หน่วยเป็นวินาที
พร้อมลองหรือยัง
ถ้าอยู่บนแพลน Studio: สร้างคีย์ แล้วเพิ่ม URL ในผู้ช่วย AI หรือเรียก REST API จากโค้ดของคุณได้เลย