มาตรฐานการผสานรวมแอปที่เชื่อมต่อ MCP

เซิร์ฟเวอร์ MCP จะสร้างเฟรมเวิร์กสำหรับการเชื่อมต่อฟังก์ชันของแอป (เครื่องมือ MCP) กับแพลตฟอร์มแอปที่เชื่อมต่อ เพื่อให้สามารถเลือก เรียกใช้ และประมวลผลผลลัพธ์ของบริการได้อย่างน่าเชื่อถือมากขึ้น การกำหนดค่า MCP ของคุณต้องเป็นไปตามมาตรฐานต่อไปนี้อย่างเคร่งครัด

หลักการชี้นำ

สำหรับแต่ละฟังก์ชัน ให้มุ่งเน้นที่ความตั้งใจของผู้ใช้และกรณีการใช้งาน ไม่ใช่ความสามารถของฟังก์ชัน คำอธิบายเป็นวิธีหลักในการบอกโมเดลว่าเครื่องมือของคุณมีไว้เพื่ออะไรและสามารถตอบสนองต่อกรณีการใช้งานใดได้บ้าง

การกำหนดเวอร์ชัน

หากต้องการรองรับการติดตั้งใช้งาน MCP ที่ปรับขนาดได้และมีประสิทธิภาพ ให้ใช้สถาปัตยกรรม URI ที่มีโครงสร้างซึ่งใช้การกำหนดเวอร์ชันตามเส้นทาง เช่น /v1, /v2 การดำเนินการดังกล่าวจะช่วยรักษาความเข้ากันได้แบบย้อนหลังและควบคุมฟีเจอร์ใหม่ๆ การเสริมด้วยโดเมนย่อยเฉพาะผู้ให้บริการ เช่น https://gemini.mcp.company.com/mcp/v1 จะช่วยให้จัดการการเข้าชมแบบละเอียดและเพิ่มประสิทธิภาพคำจำกัดความของเครื่องมือที่ปรับให้เหมาะกับบริบทและลักษณะการประมวลผลที่ไม่ซ้ำกันของโมเดล AI ต่างๆ ได้

ความเข้ากันได้ของเวอร์ชันโปรโตคอล MCP

แพลตฟอร์มแอปที่เชื่อมต่อรองรับข้อกำหนดเฉพาะของ Model Context Protocol (MCP) สูงสุดถึงเวอร์ชัน 2025-11-25 ระบบยังไม่รองรับข้อกำหนดเวอร์ชันใหม่

  • ความรับผิดชอบของนักพัฒนาแอป: คุณมีหน้าที่ตรวจสอบว่าเซิร์ฟเวอร์ MCP ของคุณเป็นไปตามเวอร์ชันโปรโตคอลที่แพลตฟอร์มแอปที่เชื่อมต่อ (2025-11-25) รองรับอย่างเคร่งครัดในระหว่างแฮนด์เชค initialize และในคำจำกัดความของเครื่องมือและสคีมาทั้งหมด
  • ความเข้ากันได้แบบย้อนหลังของแพลตฟอร์ม: เนื่องจากแพลตฟอร์มแอปที่เชื่อมต่อจะใช้ข้อกำหนด MCP เวอร์ชันใหม่ในอนาคต ไคลเอ็นต์ของเราจะรักษาความเข้ากันได้แบบย้อนหลังกับเวอร์ชันโปรโตคอลที่รองรับก่อนหน้านี้ เพื่อให้การผสานรวมเวอร์ชันที่ใช้งานจริงที่มีอยู่ยังคงทำงานต่อไปได้โดยไม่หยุดชะงัก
  • การจัดการการอัปเกรด: เมื่อคุณพร้อมที่จะใช้ข้อกำหนดเฉพาะของ MCP ที่รองรับใหม่หรือแนะนำการเปลี่ยนแปลงสคีมา ให้แสดงการอัปเดตเหล่านั้นในเส้นทาง URI ที่กำหนดเวอร์ชันใหม่ (เช่น /mcp/v2) ขณะที่ยังคงรักษาปลายทางที่มีอยู่ (/mcp/v1) สำหรับการเข้าชมที่ใช้งานอยู่

อนุญาตให้ทำการเปลี่ยนแปลงสคีมา MCP ระหว่างแอปเวอร์ชันต่างๆ ได้ เราขอแนะนำให้คุณใช้ประโยชน์จากฟีเจอร์นี้และกำหนดเวอร์ชันของปลายทาง MCP เพื่อรองรับการเปิดตัวฟีเจอร์ใหม่ๆ อย่างค่อยเป็นค่อยไป หรือพึ่งพาการเปลี่ยนแปลงที่เข้ากันได้แบบย้อนหลังอย่างเคร่งครัด

ข้อกำหนดของโปรโตคอลการนำส่ง

แพลตฟอร์มแอปที่เชื่อมต่อรองรับข้อกำหนดเฉพาะของ Model Context Protocol สำหรับการรับส่งข้อมูล HTTP ที่สตรีมได้เวอร์ชัน 2025-03-26 ขึ้นไปอย่างเคร่งครัด แต่ไม่รองรับ HTTP เดิมที่มีการส่ง SSE ตามที่อธิบายไว้ในข้อกำหนดเฉพาะวันที่ 5 พฤศจิกายน 2024

  • ปลายทาง HTTP เดียว ปลายทาง MCP ที่ระบุไว้ใน Connected Console (เช่น https://api.example.com/mcp) คือ URL เดียวที่ผลิตภัณฑ์ Google ที่เกี่ยวข้องจะส่งคำขอ JSON-RPC ทั้งหมด (initialize, tools/list, tools/call) ผ่าน HTTP POST มาตรฐาน
  • สตรีมมิง SSE ภายใน HTTP ที่สตรีมได้ ระบบไม่รองรับการส่ง SSE แบบหลายปลายทางเดิม แต่รองรับ Server-Sent Events เช่น text/event-stream ภายใน Streamable HTTP คำขอขาออกจากผลิตภัณฑ์ Google ที่เกี่ยวข้องจะมี Accept: application/json, text/event-stream ซึ่งหมายความว่าเซิร์ฟเวอร์ของคุณสามารถแสดงผลเพย์โหลด application/json มาตรฐานหรือสตรีมการตอบกลับแบบเพิ่มทีละส่วนโดยใช้ Content-Type: text/event-stream ในเนื้อหาการตอบกลับ HTTP POST โดยตรงได้
  • สตรีม GET และ 405 Method Not Allowed ไคลเอ็นต์อาจพยายามใช้สตรีม GET ที่ไม่บังคับในปลายทางสำหรับการแจ้งเตือนจากเซิร์ฟเวอร์ไปยังไคลเอ็นต์ หากเซิร์ฟเวอร์ของคุณเป็นแบบไม่เก็บสถานะหรือแบบคำขอ-การตอบกลับเท่านั้น พร็อกซีไคลเอ็นต์ของผลิตภัณฑ์ Google ที่เกี่ยวข้องจะรองรับและจัดการการแสดงผล HTTP 405 Method Not Allowed อย่างชัดเจน

วิธีการสำหรับเซิร์ฟเวอร์

แพลตฟอร์มแอปที่เชื่อมต่อได้รับการเพิ่มประสิทธิภาพให้รับคำสั่งจากเซิร์ฟเวอร์ ซึ่งช่วยให้ควบคุมพฤติกรรมของโมเดลได้ในระดับที่วิธีอื่นๆ ทำไม่ได้

ทำตามวิธีการของเซิร์ฟเวอร์

ถือเป็น "คำแนะนำโมเดล" ที่มีบริบทการใช้งาน

ทำตามหลักเกณฑ์ต่อไปนี้เกี่ยวกับการให้คำแนะนำแก่โมเดล

  • เขียนวิธีการเป็น "คำแนะนำ" ระดับสูงหรือแนวทางเพื่อช่วยให้ LLM เข้าใจวัตถุประสงค์และความสามารถโดยรวมของเซิร์ฟเวอร์
  • อธิบายสิ่งที่ทำได้ แทนที่จะแสดงรายการฟีเจอร์หรืออธิบายวิธีที่โมเดลควรใช้เครื่องมือและทรัพยากรของเซิร์ฟเวอร์ หากโมเดลเข้าใจ "สิ่งที่" ผู้ใช้ต้องการอย่างถูกต้อง ก็จะระบุวิธีดำเนินการได้ค่อนข้างดีโดยอิงตามเส้นทางของผู้ใช้
  • สมมติว่าระบบจะเพิ่มข้อความนี้ลงในพรอมต์ของระบบของโมเดลโดยตรง ทำให้ชัดเจน เป็นคำสั่ง และใช้โทเค็นอย่างมีประสิทธิภาพ

ควรเสริมข้อมูล ไม่ควรทำซ้ำ

ใช้พื้นที่นี้สำหรับบริบทส่วนกลางที่ใช้กับเครื่องมือทั้งหมด โดยหลีกเลี่ยงความซ้ำซ้อนกับคำอธิบายเครื่องมือแต่ละรายการ

ตัวอย่างวิธีการใช้เซิร์ฟเวอร์

ตัวอย่างต่อไปนี้แสดงสิ่งที่ควรทำและไม่ควรทำเกี่ยวกับการเขียนวิธีการของเซิร์ฟเวอร์อย่างถูกต้อง

แนะนำ ไม่แนะนำ

สมมติว่าคุณเป็นผู้ดูแลที่เก็บ GitHub ที่มีความเชี่ยวชาญเฉพาะทาง เซิร์ฟเวอร์นี้ให้สิทธิ์เข้าถึงข้อมูลเมตาของที่เก็บ Issue Tracker และเวิร์กโฟลว์ PR อย่างละเอียด ใช้เพื่อรักษาประสิทธิภาพของโปรเจ็กต์ จัดการการคัดแยกโดยอัตโนมัติ และตรวจสอบมาตรฐานของโค้ด ถือว่าการดำเนินการทั้งหมดเกิดขึ้นภายในบริบทขององค์กรที่ตรวจสอบสิทธิ์แล้ว เว้นแต่จะระบุไว้เป็นอย่างอื่น ให้ความสำคัญกับการระบุชุดข้อความที่ไม่มีการอัปเดตหรือ PR ที่ไม่ได้ลิงก์เพื่อจัดระเบียบที่เก็บข้อมูล

กระชับ เป็นคำสั่ง และเสริมโมเดล

  • กำหนด "สิ่งที่ต้องทำ" (ความสมบูรณ์ของโปรเจ็กต์ การคัดแยก) แทนที่จะเป็น "วิธีการทำ"
  • พูดถึงขอบเขตการตรวจสอบสิทธิ์ซึ่งใช้กับเครื่องมือทั้งหมด

เซิร์ฟเวอร์นี้มีเครื่องมือสำหรับ GitHub คุณควรใช้เครื่องมือ list_issues เมื่อผู้ใช้สอบถามเกี่ยวกับปัญหา คุณใช้ create_pull_request เพื่อสร้าง PR ได้ ใช้เครื่องมือเหล่านี้อย่างระมัดระวังเพื่อช่วยผู้ใช้จัดการโค้ด ตรวจสอบชื่อที่เก็บก่อนเรียกใช้เครื่องมือเสมอ หากผู้ใช้ขอสรุป ให้เรียกใช้เครื่องมือก่อน แล้วจึงสรุปผลลัพธ์

  • don't relist tool names,
  • อย่าบอกโมเดลว่า "วิธี" คิดซึ่งอาจขัดแย้งกับการให้เหตุผลในตัวของโมเดลที่จะใช้บริบทของผู้ใช้เพื่อเลือกตัวเลือกที่ถูกต้อง
  • ไม่ได้อธิบายลักษณะการเข้าถึงของเซิร์ฟเวอร์หรือข้อจำกัดที่เฉพาะเจาะจง)

หลักเกณฑ์ของเครื่องมือ

หลักเกณฑ์ต่อไปนี้อธิบายแนวทางปฏิบัติแนะนำในการสร้างการกำหนดค่าเซิร์ฟเวอร์ MCP สำหรับฟังก์ชันหรือเครื่องมือต่างๆ ภายในแอปของคุณ

รูปแบบการตั้งชื่อเครื่องมือ

ดูหลักเกณฑ์ต่อไปนี้สำหรับการตั้งชื่อเครื่องมือ

ใช้ชื่อที่เข้าใจง่ายและมนุษย์อ่านได้

ใช้ชื่อที่มนุษย์อ่านได้ซึ่งมีความหมายชัดเจนและเข้าใจง่ายแทนชื่อที่กำกวม ตัวอย่างเช่น get_user_information จะตรงไปตรงมามากกว่า userInfo

ใช้รูปแบบตัวพิมพ์ที่เหมาะสม

ปฏิบัติตามกฎการใช้อักษรตัวพิมพ์ใหญ่-เล็กต่อไปนี้สำหรับชื่อฟังก์ชันเครื่องมือและทริกเกอร์แอป

  • ตัวพิมพ์ของฟังก์ชันเครื่องมือ ใช้ snake_case หรือ camelCase สำหรับชื่อฟังก์ชันเครื่องมือที่กำหนดไว้ในสคีมา MCP (เช่น get_user_information หรือ publishDraft)
  • ตัวพิมพ์ของแฮนเดิลทริกเกอร์แอป ทริกเกอร์และการพูดถึงแอป (เช่น @MyTwoWordApp) ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ แพลตฟอร์มจะปรับข้อมูลที่ผู้ใช้ป้อนให้เป็นมาตรฐานเดียวกัน ทั้งตัวพิมพ์เล็ก (@mytwowordapp), PascalCase (@MyTwoWordApp) และ camelCase (@myTwoWordApp)
  • การจัดรูปแบบชื่อที่แสดง ลงทะเบียนชื่อแอปอย่างเป็นทางการโดยใช้ PascalCase หรือเว้นวรรคตามมาตรฐานเพื่อให้แสดงผลได้อย่างชัดเจนในองค์ประกอบ UI
  • การจัดการคำที่สะกดผิด แม้ว่าระบบจะจัดการรูปแบบตัวพิมพ์เล็กและตัวพิมพ์ใหญ่โดยอัตโนมัติ แต่การพิมพ์ผิด (เช่น @mytwowrodapp) จะอาศัยการจดจำ Intent สำรองแทนการจับคู่สตริงโดยตรง นักพัฒนาแอปควรส่งเสริมให้มีการสะกดแฮนเดิลอย่างถูกต้องในเอกสารประกอบ

ใช้การตั้งชื่อแบบคำกริยา-คำนามที่ชัดเจน

ใช้การตั้งชื่อ verb_noun ที่เฉพาะเจาะจงและหลีกเลี่ยงความกำกวม เช่น publish_draft ดีกว่า handle_content

รายละเอียดของเครื่องมือ

โปรดปฏิบัติตามหลักเกณฑ์ต่อไปนี้เกี่ยวกับรายละเอียดของเครื่องมือ

มองเครื่องมือเป็นปลายทางแบบอะตอม

มองเครื่องมือเป็นปลายทางแบบอะตอมมิกที่ไม่มีเงื่อนไขเครื่องมือภายในหรือฟังก์ชันการทำงานหลายอย่างพร้อมพารามิเตอร์ที่จำเป็นที่เกี่ยวข้อง เครื่องมือที่ละเอียดช่วยให้โมเดลเชื่อมโยงขั้นตอนต่างๆ ได้อย่างสมเหตุสมผล ซึ่งช่วยลดอาการหลอนได้

ใช้สคีมาที่แบนราบกว่า

หากคุณต้องการออบเจ็กต์ที่ซ้อนกันหลายชั้นหรือตรรกะสคีมา oneOf / anyOf ที่ซับซ้อนเพื่อตรวจสอบอินพุต เครื่องมือของคุณอาจกว้างเกินไป

สังเกตการป้องกันการรวมข้อมูลล่วงหน้าและเพย์โหลด

แม้ว่าโปรโตคอลจะไม่บังคับให้รวมข้อมูลล่วงหน้าสำหรับเพย์โหลดขนาดเล็กที่มีขอบเขตจำกัด แต่ในทางปฏิบัติแล้ว การรวมข้อมูลล่วงหน้าในแบ็กเอนด์เป็นสิ่งจำเป็นอย่างยิ่งเมื่อทำงานกับชุดระเบียนขนาดใหญ่ ประวัติระยะยาว และชุดข้อมูลจากหลายแหล่ง แพลตฟอร์มแอปที่เชื่อมต่อจะบังคับใช้มาตรการป้องกันเกี่ยวกับขีดจำกัดของหน้าต่างบริบท เวลาในการตอบสนองของการดำเนินการ และขั้นตอนการให้เหตุผลของโมเดล โปรดทำตามหลักเกณฑ์ต่อไปนี้เพื่อให้เป็นไปตามมาตรการป้องกันเหล่านี้

  • กรองและสรุปในแบ็กเอนด์ กรอง รวมข้อมูลล่วงหน้า หรือสรุปสตรีมข้อมูลขนาดใหญ่บนเซิร์ฟเวอร์ MCP ของคุณเสมอก่อนที่จะแสดงคำตอบไปยังผลิตภัณฑ์ Google ที่เกี่ยวข้อง
  • หลีกเลี่ยงการดัมพ์ข้อมูลดิบ อย่าดัมพ์แถวฐานข้อมูลดิบหรือบันทึกที่ไม่มีการจัดทำดัชนีแบบสมบูรณ์ลงในเพย์โหลดที่เครื่องมือแสดงผล

ละเว้นเครื่องมือภายในและเครื่องมือเมตา

แสดงเฉพาะความสามารถที่โมเดลใช้ได้ในการตอบกลับ tools/list ของเซิร์ฟเวอร์ ดังนี้

  • กรองเครื่องมือตัวช่วย: ละเว้นเครื่องมือภายใน เครื่องมือการดูแลระบบ หรือเครื่องมือเมตาที่ไม่ได้มีไว้ให้โมเดลเรียกใช้ (เช่น การตรวจสอบประสิทธิภาพของเซิร์ฟเวอร์ รูทีนการตั้งค่าภายใน หรือตัวช่วยยูทิลิตีสำหรับนักพัฒนาซอฟต์แวร์)
  • ประสิทธิภาพของหน้าต่างบริบท: การยกเว้นเครื่องมือที่ไม่จำเป็นจะช่วยให้สคีมา MCP ของคุณกระชับ ลดการใช้โทเค็นหน้าต่างบริบท และป้องกันความสับสนในการกำหนดเส้นทางเครื่องมือของโมเดล เซิร์ฟเวอร์ MCP ที่แสดงเครื่องมือหลายสิบรายการหรือสคีมา "เครื่องมือขนาดใหญ่" ที่ซ้อนกันอย่างซับซ้อนจะได้รับการแจ้งว่าไม่เหมาะสมในระหว่างการตรวจสอบเพื่อแก้ไข

สิ่งที่ควรและไม่ควรทำเกี่ยวกับรายละเอียดของเครื่องมือ

ตัวอย่างต่อไปนี้แสดงสิ่งที่ควรทำและไม่ควรทำเกี่ยวกับการตั้งชื่อเครื่องมือและการใช้รายละเอียด

แนะนำ ไม่แนะนำ

เครื่องมือแบบละเอียดที่มีชื่อและพารามิเตอร์ที่ชัดเจน

สคีมอินพุตสำหรับเครื่องมือแต่ละรายการมีความเข้มงวด หาก LLM ต้องการสร้างผู้ใช้ ก็ต้องระบุอีเมล หากต้องการลบ คุณต้องระบุรหัส คุณจึงไม่ต้องคาดเดา

...
@mcp.tool()
def create_user(email: str, role: str = "viewer") -> str:
    """Register a new user. Returns the new User ID."""
    # Logic is purely creation
    return "user_123"

@mcp.tool()
def delete_user(user_id: str) -> str:
    """Permanently remove a user by their ID."""
    # Logic is purely deletion
    return f"User {user_id} deleted"

@mcp.tool()
def update_user_role(user_id: str, new_role: str) -> str:
    """Change an existing user's permission level."""
    return f"User {user_id} is now {new_role}"

    ...

ชื่อเครื่องมือ: manage_user

คำอธิบาย: "ใช้เครื่องมือนี้เพื่อสร้าง อัปเดต ลบ หรือเรียกดูผู้ใช้"

...
@mcp.tool()
def manage_user(
    action: Literal["create", "update", "delete", "get"],
    user_id: Optional[str] = None,
    email: Optional[str] = None,
    role: Optional[str] = "viewer"
) -> str:
    """
    Use this to manage users.
    WARNING: logic is hidden inside Python, not visible in the schema.
    """
    if action == "create":
        if not email: return "Error: Email required for creation" # Runtime error, not schema error
        return f"Created user {email}"
    elif action == "delete":
        if not user_id: return "Error: User ID required"
        return f"Deleted {user_id}"
    
    return "Action completed"
    """
    ...

ประกาศคำอธิบายประกอบเครื่องมือเพื่อความปลอดภัย

กำหนดค่าคำอธิบายประกอบโปรโตคอลภายในคำจำกัดความของเครื่องมือเพื่อสื่อถึงลักษณะการทำงานของการดำเนินการและทริกเกอร์เกตความปลอดภัยในตัวในผลิตภัณฑ์ Google ที่เกี่ยวข้อง ดังนี้

  • เกตการยืนยันรันไทม์: ผลิตภัณฑ์ Google ที่เกี่ยวข้องจะใช้ annotations.destructiveHint: true และ annotations.openWorldHint: true เป็นแฟล็กหลักเพื่อทริกเกอร์ข้อความแจ้งการยืนยันของผู้ใช้รันไทม์ ประกาศ destructiveHint: true ในการดำเนินการที่เปลี่ยนสถานะ เขียน หรือทำลาย และตั้งค่า openWorldHint: true สำหรับเครื่องมือที่โต้ตอบกับสภาพแวดล้อมแบบโอเพนเวิลด์หรือภายนอก เพื่อให้แพลตฟอร์มแจ้งให้ผู้ใช้ยืนยันก่อนดำเนินการโดยค่าเริ่มต้น
  • คำแนะนำการค้นหาแบบอ่านอย่างเดียว: ตั้งค่า readOnlyHint: true ในเครื่องมือ Query ที่ดึงข้อมูลเท่านั้นโดยไม่ต้องแก้ไขสถานะแบ็กเอนด์
  • ค่าเริ่มต้นของคำอธิบายประกอบที่ชัดเจน: ตามข้อกำหนดเฉพาะของ Model Context Protocol การละเว้น readOnlyHint จะทำให้ไคลเอ็นต์ถือว่า readOnlyHint: false และ destructiveHint: true เป็นค่าเริ่มต้นเพื่อความปลอดภัย การประกาศคำอธิบายประกอบอย่างชัดเจนในเครื่องมือทั้งหมดช่วยให้มั่นใจได้ว่าการกำหนดเส้นทางโมเดลจะคาดการณ์ได้และความปลอดภัยในการดำเนินการที่เหมาะสม

คำอธิบายเครื่องมือ

คำอธิบายเป็นบริบทเดียวที่โมเดลมีเพื่อตัดสินใจว่าเครื่องมือของคุณสามารถแก้ปัญหาปัจจุบันได้หรือไม่ ดูหลักเกณฑ์ต่อไปนี้สำหรับการเขียนคำอธิบาย

เขียนคำสั่ง ไม่ใช่ความคิดเห็น

เขียนคำอธิบายเครื่องมือเป็นวิธีการ ไม่ใช่ความคิดเห็นในโค้ด ซึ่งมักจะเป็นแบบพาสซีฟ LLM ตอบสนองต่อคำสั่งได้ดี

อธิบาย "วิธีการ"

คำอธิบายที่ดีจะช่วยเชื่อมช่องว่างระหว่าง "ฉันมีเครื่องมือ" กับ "ฉันรู้วิธีเชื่อมต่อเครื่องมือนี้เข้ากับการสนทนา"

อธิบาย "เหตุผล"

แยกความแตกต่างของเครื่องมือนี้จากเครื่องมือที่คล้ายกัน เช่น "ใช้เครื่องมือนี้สำหรับผู้ใช้ภายใน ใช้ customer_update สำหรับผู้ใช้ภายนอก"

บอกโมเดลว่าจะหาอาร์กิวเมนต์ได้จากที่ใด เช่น "จากเครื่องมือ order_search"

ระบุรูปแบบ

ระบุหน่วย (เมตรเทียบกับฟุต) และรูปแบบ (วันที่ ISO, เวอร์ชันเชิงความหมาย)

หลีกเลี่ยงการใช้ดุลยพินิจของโมเดล

อย่าสั่งให้โมเดลใช้ "การพิจารณาที่ดีที่สุด" หรือแนะนำการดำเนินการที่ไม่บังคับและไม่มีคำแนะนำ

ตัวอย่างคำอธิบายเครื่องมือ

ตัวอย่างต่อไปนี้แสดงสิ่งที่ควรทำและไม่ควรทำเกี่ยวกับการเขียนคำอธิบายเครื่องมือ

แนะนำ ไม่แนะนำ

แหล่งข้อมูลที่เชื่อถือได้

"อัปเดตอีเมลของผู้ใช้ ต้องใช้ UUID "id" ที่แสดงผลจากเครื่องมือ search_users อย่างเคร่งครัด อย่าอนุมานหรือคาดเดารหัสผู้ใช้"

(โดยจะลิงก์เอาต์พุตของเครื่องมือหนึ่งกับอินพุตของเครื่องมือนี้อย่างชัดเจน)

"อัปเดตอีเมลของผู้ใช้"

(โมเดลอาจเดารหัส เช่น 12345)

รูปแบบและข้อจำกัด

"นัดหมายการประชุม "date" ต้องอยู่ในรูปแบบ ISO 8601 (YYYY-MM-DD) หากผู้ใช้พูดว่า "พรุ่งนี้" หรือการอ้างอิงที่เกี่ยวข้องอื่นๆ ให้คำนวณวันที่ตามบริบทปัจจุบัน"

"นัดหมายการประชุมสำหรับวันที่ที่ระบุ"

(ดูถูกต้องสำหรับมนุษย์ (เช่น "พรุ่งนี้") แต่ไม่ผ่านการตรวจสอบสคีมา (ต้องเป็น "2025-10-12"))

ความคาดหวังด้านเอาต์พุต

"ดึงข้อมูลบันทึกของเซิร์ฟเวอร์ แสดงข้อความดิบ 50 บรรทัดสุดท้าย สำหรับการวิเคราะห์ ให้ขอหน้าต่างเวลาที่เล็กลงเพื่อหลีกเลี่ยงขีดจำกัดโทเค็น"

"รับบันทึกของเซิร์ฟเวอร์"

(โมเดลอาจเรียกใช้เครื่องมือที่คาดหวังข้อมูลสรุป แต่ได้รับข้อมูลดิบขนาด 5 MB ในรูปแบบ JSON ซึ่งอาจส่งผลให้ผู้ใช้ได้รับประสบการณ์การใช้งานที่ไม่ดี)

 
@mcp.tool()
def update_campaign_status(campaign_id: str, status: str) -> str:
    """
    Promotes or pauses an advertising campaign.
    
    CRITICAL USAGE RULES:
    1. 'campaign_id': Must be the 32-character UUID retrieved from 'list_campaigns'.
    2. 'status': Must be exactly one of: ['active', 'paused', 'archived'].
    
    Returns: A confirmation string with the new status and timestamp.
    """
    # Logic...

    ...

คำอธิบายนี้ทำหน้าที่เป็นคู่มือขนาดเล็ก โดยจะจัดการแหล่งที่มา (ตำแหน่งที่จะรับรหัส) ข้อจำกัด (Enum ที่ถูกต้อง) และการดำเนินการ

 
@mcp.tool()
def update_campaign_status(id: str, status: str) -> str:
    """
    Updates the campaign status in the database.
    """
    # Logic...

ซึ่งจะใช้ชื่อตัวแปรเพื่อทำงานทั้งหมด ซึ่งทำให้โมเดลต้องเดาค่าที่ถูกต้องสำหรับ "status"

พารามิเตอร์เครื่องมือ

นอกเหนือจากตัวเครื่องมือเองแล้ว ให้อธิบายพารามิเตอร์เพื่อให้เข้าใจได้ชัดเจน

ประเภทที่อาจไม่เหมาะสม

ใช้ประเภทที่เฉพาะเจาะจงและชัดเจน (string, integer, boolean, array)

ใช้ Enum สำหรับชุดค่าคงที่

หากพารามิเตอร์ยอมรับเฉพาะชุดค่าคงที่ (เช่น daylight, cool, warm) ให้แสดงรายการในอาร์เรย์ enum ซึ่งจะช่วยปรับปรุงความแม่นยำได้อย่างมาก

ระบุพารามิเตอร์ที่จำเป็นอย่างชัดเจน

กำหนดให้ชัดเจนว่าพารามิเตอร์ใดจำเป็นสำหรับการทำงานของฟังก์ชัน

ใช้การจับคู่สคีมาเชิงความหมาย

เมื่อผสานรวมแอป คุณอาจต้องจับคู่สคีมาเชิงความหมายจากพารามิเตอร์เครื่องมือกับประเภทธุรกิจที่คุณกำลังพัฒนา คุณจะได้รับสคีมาประเภทธุรกิจที่คาดไว้ (สคีมา JSON) ในระหว่างกระบวนการเริ่มต้นใช้งาน

ตัวอย่างพารามิเตอร์เครื่องมือ

ตัวอย่างต่อไปนี้แสดงสิ่งที่ควรทำและไม่ควรทำเกี่ยวกับการจัดการพารามิเตอร์เครื่องมือ

แนะนำ ไม่แนะนำ

รูปแบบและหน่วยของอาร์กิวเมนต์

radius: "รัศมีในหน่วยเมตร ต้องเป็นค่าแบบลอยตัว > 0"

(ป้องกันอาการหลอนของ AI เกี่ยวกับหน่วย)

radius: "รัศมีของวงกลม"

รูปแบบและบริบทของรหัส

user_id: "UUID ของฐานข้อมูล (เช่น 550e8400-e29b...) อย่าใช้อีเมลที่นี่"

หมายเหตุ: แนวทางปฏิบัติแนะนำคือควรจัดการฟิลด์รหัสที่เป็นตัวเลขทั้งหมดเป็นค่าสตริง โดยเฉพาะอย่างยิ่ง หากรหัสของคุณอาจมีตัวเลขมากกว่า 10 หลัก คุณอาจเสี่ยงที่รหัสจะถูกตัดโดยระบบภายใน (บังคับให้อยู่ในคอนเทนเนอร์ 32 บิต) และโมเดลจะใช้เวอร์ชันนี้ในการเรียกใช้เครื่องมือในอนาคต

(ป้องกันข้อผิดพลาดของประเภท)

user_id: "รหัสของผู้ใช้"

ความคาดหวังเกี่ยวกับผลลัพธ์

"อัปเดตระเบียนและแสดงผลออบเจ็กต์ JSON ที่อัปเดตแล้ว รวมถึงการประทับเวลาใหม่"

(บอกโมเดลว่าไม่จำเป็นต้องเรียกใช้เครื่องมือ "get" ทันทีหลังจาก "update" เพื่อยืนยันการเปลี่ยนแปลง)

"อัปเดตระเบียน"

 

@mcp.tool()
def search_logs(query: str, limit: int = 10) -> str:
    """
    Searches server error logs using Lucene syntax (e.g. 'level:ERROR AND service:auth').
    
    Args:
        query: A Lucene-formatted search string.
        limit: Max results to return. capped at 50.
    
    Returns:
        A formatted string of log entries with timestamps.
    """
    ...
  
@mcp.tool()
def search_logs(query: str, limit: int = 10) -> str:
    """Searches the logs."""
    ...

LLM ไม่ทราบว่า "การค้นหา" รองรับไวยากรณ์ใด (SQL? นิพจน์ทั่วไป? ข้อความธรรมดา) เนื่องจากไม่ทราบว่า "ขีดจำกัด" สูงสุดคือเท่าใด

การตอบกลับและการจัดการข้อผิดพลาด

ตามหลักการสำคัญของคำตอบคือพรอมต์ถัดไป เครื่องมือจะรายงานผลลัพธ์ของการดำเนินการที่สำคัญโดยแสดงผลเพย์โหลดข้อมูล ซึ่งจะวางลงในหน้าต่างบริบทของ LLM โดยตรง ผลลัพธ์ที่สำเร็จหรือไม่สำเร็จจะเป็นตัวกำหนดสิ่งที่จะเกิดขึ้นต่อไป ดังนี้

  • หากสำเร็จ: โมเดลต้องการค่าที่แสดงผลเพื่อทราบว่าเกิดอะไรขึ้นเพื่อตัดสินใจขั้นตอนถัดไป
  • หากไม่สำเร็จ: โมเดลต้องทราบสาเหตุที่ดำเนินการไม่สำเร็จและวิธีแก้ไข ข้อขัดข้อง (ข้อผิดพลาด 500) จะหยุดการสนทนา ข้อความแสดงข้อผิดพลาดที่สื่อความหมายจะช่วยให้โมเดลแก้ไขตัวเองได้

ไม่ว่าตรรกะพื้นฐานของเครื่องมือจะสำเร็จหรือล้มเหลว คุณต้องจัดรูปแบบเพย์โหลดค่าที่แสดงผลเพื่อให้โมเดลแยกวิเคราะห์ได้ง่าย ทำตามแนวทางปฏิบัติแนะนำเหล่านี้เมื่อจัดแพ็กเกจเพย์โหลดการตอบกลับ

ใช้ JSON

จัดรูปแบบ Structured Data ใน TextContent (ข้อจำกัดชั่วคราว) เนื่องจากแพลตฟอร์มแอปที่เชื่อมต่อยังไม่รองรับ structuredContent ให้ทำการจัดเรียงข้อมูลของคุณด้วยตนเอง แม้ว่าจะแสดงรายการที่ตรงไปตรงมาก็ตาม ให้json.dumps()

รวม URL ในคำตอบ

URL ที่แสดงผลควรสั้นและไม่มีพารามิเตอร์มากนัก ขอแนะนำให้ใช้บริการย่อ URL เพื่อประหยัดจำนวนโทเค็นและลดความเสี่ยงที่จะเกิดภาพหลอน

เพย์โหลดป้องกันภาพหลอนที่อธิบายตนเองได้

จับคู่รหัสข้อมูลดิบหรือรหัสภายในกับชื่อที่แสดงที่มนุษย์อ่านได้ หน่วยวัดที่ชัดเจน และช่วงอ้างอิงเสมอ อย่าแสดงคีย์พจนานุกรมที่บีบอัดหรือรหัสตัวเลขที่ไม่ได้แมปซึ่งบังคับให้โมเดลอนุมานบริบท

ใช้การจัดการข้อผิดพลาดที่มีประสิทธิภาพ

แสดงข้อความแสดงข้อผิดพลาดที่ชัดเจนและมีความหมายเพื่อให้โมเดลเข้าใจสิ่งที่ผิดพลาดและแจ้งให้ผู้ใช้ทราบ ดูการจัดการข้อผิดพลาดของ MCP

ใช้ try/except

รวมตรรกะของเครื่องมือไว้ในบล็อก try/except และแสดงผลข้อผิดพลาดที่แปลงเป็นสตริง

ระบุข้อผิดพลาดที่นำไปใช้ได้จริง

แนะนำขั้นตอนถัดไปในข้อความแสดงข้อผิดพลาด (เช่น "ลองใช้เครื่องมือ X ก่อน")

ยืนยันการทำงาน

อย่าแสดงสตริงว่างสำหรับเครื่องมือที่มีผลข้างเคียง (สร้าง/อัปเดต/ลบ)

ตัวอย่างการตอบกลับและการจัดการข้อผิดพลาด

ตัวอย่างต่อไปนี้แสดงสิ่งที่ควรทำและไม่ควรทำเกี่ยวกับการตอบกลับและการจัดการข้อผิดพลาด

แนะนำ ไม่แนะนำ

การทำให้เป็นอนุกรมอย่างชัดเจน


...
import json

@mcp.tool()
def query_metrics(metric_id: str) -> str:
    result = {"id": metric_id, "value": 42, "unit": "ms"}
    # GOOD: Returns '{"id": "cpu", "value": 42}' -> Valid JSON
    return json.dumps(result, indent=2)


...
@mcp.tool()
def query_metrics(metric_id: str) -> str:
    result = {"id": metric_id, "value": 42, "unit": "ms"}
    # BAD: Returns "{'id': 'cpu', 'value': 42}" -> Invalid JSON
    return str(result)

ตรวจจับและแจ้งให้ทราบ


...
@mcp.tool()
def get_user_details(user_id: str) -> str:
    try:
        user = db.get_user(user_id)
        if not user:
             # GOOD: Informative error returned as content
            return f"Error: User with ID '{user_id}' not found. Please verify the ID using 'search_users'."
        return json.dumps(user)
    except Exception as e:
        return f"Error: Database connection failed ({str(e)}). Please try again later."

(เครื่องมือ "ประสบความสำเร็จ" ในทางเทคนิค (แสดงผลสตริง) แต่สตริงมีรายละเอียดข้อผิดพลาด โมเดลจะอ่านข้อมูลนี้และตระหนักว่า "โอ้ รหัสนั้นไม่มีอยู่" และสามารถขอรหัสที่ถูกต้องจากผู้ใช้ได้) 


...
@mcp.tool()
def get_user_details(user_id: str) -> str:
    # BAD: Unhandled exception if ID not found
    user = db.get_user(user_id)
    return json.dumps(user)

(หาก get_user ล้มเหลว เซิร์ฟเวอร์จะแสดงข้อผิดพลาด 500 LLM ได้รับข้อผิดพลาดในการดำเนินการทั่วไปและไม่ทราบสาเหตุ (รหัสไม่ถูกต้องใช่ไหม ฐานข้อมูลไม่ทำงานใช่ไหม สิทธิ์ถูกปฏิเสธ) เนื่องจากระบบอาจลองป้อนข้อมูลที่ไม่ถูกต้องแบบเดิมอีกครั้ง)

การตอบกลับที่ว่างเปล่า

...
@mcp.tool()
def post_story(story_content: str) -> str:
    service_name = "story_service"
    api_client.post("/stories", json={"content": story_content})
    # GOOD: Explicit confirmation of state change.
    return f"Service '{service_name}' successfully posted content. Status is now 'posted'."


...
@mcp.tool()
def post_story(storyContent: str):
    subprocess.post(["postsrv", "story", storyContent])
    # BAD: Returns null/empty string. Model is confused.

LLM มักจะสับสนกับคำตอบที่ว่างเปล่า โมเดลอาจสร้างภาพหลอนว่า "เครื่องมือทำงานไม่สำเร็จ" หรือเพียงแค่เรียกใช้ซ้ำ

เพย์โหลดป้องกันภาพหลอนที่อธิบายตนเอง

จับคู่รหัสข้อมูลดิบหรือรหัสภายในกับชื่อที่แสดงที่มนุษย์อ่านได้ หน่วยวัดที่ชัดเจน และช่วงอ้างอิงปกติเสมอ

{"lab_code": "2345-7", "display_name": "Glucose [Mass/volume] in Blood", "value": 105, "unit": "mg/dL", "reference_range": "70-99 mg/dL"}

(วิธีนี้จะบอกโมเดลอย่างชัดเจนว่าค่าหมายถึงอะไร โดยไม่ต้องบังคับให้โมเดลอนุมานหน่วยหรือเกณฑ์อ้างอิง)

รหัสดิบ การบีบอัดที่กำหนดเอง หรือรหัสที่ไม่ได้จับคู่

การแสดงรหัสภายในแบบข้อมูลดิบ ตัวย่อพจนานุกรมที่กำหนดเอง หรือรหัสตัวเลขที่ไม่มีป้ายกำกับ

{"code": "2345-7", "v": 105}

(บังคับให้โมเดลคาดเดาว่า 105 หมายถึงอะไร ซึ่งนำไปสู่หน่วยที่เกิดจากการคิดไปเอง บริบทที่ขาดหายไป หรือคำอธิบายที่ไม่ถูกต้อง)

การจัดการข้อผิดพลาดของ MCP

การจัดการข้อผิดพลาดอย่างเหมาะสมเป็นสิ่งสำคัญอย่างยิ่ง

  • สำหรับข้อผิดพลาดที่กู้คืนได้ (เช่น รหัสผู้ใช้ไม่ถูกต้องหรือไม่มีพารามิเตอร์ที่ไม่บังคับ) ให้แสดงผลสตริงข้อความปกติที่มีรายละเอียดข้อผิดพลาดที่อธิบายไว้ในการตอบกลับของเครื่องมือ ซึ่งช่วยให้โมเดลตรวจสอบความคิดเห็น เข้าใจสิ่งที่ผิดพลาด และแก้ไขด้วยตนเองหรือแจ้งให้ผู้ใช้ชี้แจงได้
  • สำหรับข้อผิดพลาดที่ทำให้ไม่สามารถดำเนินการต่อได้ (เช่น การจำกัดอัตราคำขอ การตรวจสอบสิทธิ์หรือสิทธิ์ไม่สำเร็จ หรือเซิร์ฟเวอร์แบ็กเอนด์หยุดทำงาน) ให้แสดง McpError พร้อมรหัสข้อผิดพลาดที่เหมาะสมเพื่อให้แพลตฟอร์มจัดการกับความล้มเหลวได้อย่างเป็นระบบ

ตัวอย่างเนื้อหาการตอบกลับข้อผิดพลาด (JSON)

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32302,
    "message": "User permission denied for the requested operation.",
    "data": null
  },
  "id": 1
}

Message มีดัมพ์ JSON ของช่อง ErrorData ของ MCP การแสดงผล code ที่ถูกต้องและ message ที่โมเดลมองเห็นได้จะช่วยให้แพลตฟอร์มแอปที่เชื่อมต่อสามารถอ่านข้อความแสดงข้อผิดพลาดและส่งต่อคำอธิบายที่เป็นประโยชน์ในภาษาธรรมชาติกลับไปยังผู้ใช้ได้ เช่น "ขออภัย ไม่พบสถานที่จัดงานที่มีรหัสดังกล่าว ช่วยตรวจสอบชื่อหน่อยได้ไหม"

MCP ช่วยให้ไคลเอ็นต์เชื่อมต่อกับเซิร์ฟเวอร์ MCP โดยใช้ข้อกำหนด JSON-RPC 2.0 ได้ JSON-RPC มีข้อผิดพลาดที่กำหนดไว้ล่วงหน้าบางอย่างซึ่งส่งสำหรับข้อผิดพลาดที่เกิดขึ้นบ่อย เช่น คำขอไม่ถูกต้อง ข้อผิดพลาดในการแยกวิเคราะห์ เป็นต้น คู่มือนี้จะอธิบายวิธีที่เซิร์ฟเวอร์ MCP สามารถส่งข้อผิดพลาดที่กำหนดเองกลับมา

รหัส
สถานะ		 ข้อความ การใช้งาน หากต้องการ
แสดงผล
อย่างชัดเจน
ข้อผิดพลาดของผู้ใช้/ลูกค้า
-32300 USER_RATE_LIMITED ผู้ใช้ใช้งานถึงขีดจำกัดการใช้งานสูงสุดแล้ว ใช่
-32301 MISSING_REQUIRED_INFORMATION คำขออินพุตไม่มีข้อมูลที่จำเป็นทั้งหมด ใช่
-32302 USER_PERMISSION_DENIED ผู้ใช้ปฏิเสธสิทธิ์ในการใช้เครื่องมือ เช่น ผู้ใช้ต้องมีบัญชีองค์กร การจำกัดอายุผู้ชม ภาษา ฯลฯ หรือไม่มีการสมัครใช้บริการเครื่องมือสำหรับองค์กร ใช่
ข้อผิดพลาดของแอปพลิเคชัน/ข้อผิดพลาดด้านตรรกะทางธุรกิจ
-32400 RUNTIME_ERROR การเรียกใช้โค้ดของเซิร์ฟเวอร์ทำให้เกิดข้อผิดพลาด ใช่
-32401 NULL_POINTER_EXCEPTION พยายามเรียกใช้พอยน์เตอร์/ออบเจ็กต์ Null ใช่
-32402 OUT_OF_MEMORY หน่วยความจำในโค้ดเซิร์ฟเวอร์ไม่เพียงพอที่จะจัดสรรให้กับออบเจ็กต์ ใช่
ข้อผิดพลาดเกี่ยวกับโครงสร้างพื้นฐาน
-32500 DEADLINE_EXCEEDED คำขอใช้เวลานานกว่าที่อนุญาต อาจเกิดขึ้นได้จากหลายสาเหตุ เช่น เซิร์ฟเวอร์ทำงานหนักเกินไป ปัญหาเครือข่าย เป็นต้น ใช่
-32501 RESOURCE_EXHAUSTED เซิร์ฟเวอร์มีหน่วยความจำไม่เพียงพอ พื้นที่ในดิสก์ เทรด เวลา CPU ฯลฯ ไม่เพียงพอ ใช่
-32502 SERVICE_UNAVAILABLE บริการที่เกี่ยวข้อง (เช่น Microservice, ฐานข้อมูล, แคช ฯลฯ อื่นๆ) ไม่พร้อมใช้งาน ใช่
ข้อผิดพลาด JSON-RPC (ข้อผิดพลาดเหล่านี้เป็นส่วนหนึ่งของการส่ง MCP)
-32700 PARSE_ERROR เซิร์ฟเวอร์แยกวิเคราะห์คำขอไม่ได้ ไม่
-32600 INVALID_REQUEST คำขอของไคลเอ็นต์มีรูปแบบไม่ถูกต้อง ไม่
-32601 METHOD_NOT_FOUND ชื่อเครื่องมือ MCP ไม่ถูกต้อง ไม่
-32602 INVALID_PARAMS พารามิเตอร์คำขอไม่ถูกต้อง รวมถึงไม่มีพารามิเตอร์หรือประเภทพารามิเตอร์ไม่ตรงกัน ไม่
-32603 INTERNAL_ERROR คำตอบเริ่มต้น ไม่

ต่อไปนี้คือตัวอย่างวิธีสร้างข้อผิดพลาด MCP ในเซิร์ฟเวอร์โดยใช้ Python SDK อย่างเป็นทางการ (mcp) สร้าง McpError ที่มีเพย์โหลด ErrorData ซึ่ง SDK จะแปลงเป็นรูปแบบข้อผิดพลาด JSON-RPC ที่จำเป็นโดยอัตโนมัติพร้อมป้อนสถานะข้อผิดพลาด

from mcp import types
from mcp.shared.exceptions import McpError

@mcp.tool()
def foo_tool() -> list[types.TextContent]:
  """Always returns an error."""
  raise McpError(
    types.ErrorData(
        code=-32302, # USER_PERMISSION_DENIED
        message="Message to show to the model."
    ),
  )

บริบทของเครื่องมือ

ผลิตภัณฑ์ Google ที่เกี่ยวข้องรองรับ Tool Context API สำหรับส่งสัญญาณไปยังเซิร์ฟเวอร์ MCP API นี้ใช้ในกรณีการใช้งานที่ถูกต้องซึ่งต้องใช้ข้อมูลที่ละเอียดอ่อน เช่น ข้อมูลเมตาที่ไม่ได้เป็นส่วนหนึ่งของคำจำกัดความของเครื่องมือหลัก เช่น ในกรณีของภาษาสำหรับเครื่องมือที่ต้องมีการแปล Tool Context API จะแสดงผ่าน Connected Console เท่านั้น

เมื่อคุณลงทะเบียนสัญญาณ เช่น current_user_location_fine กับแอปใน Connected Console ผลิตภัณฑ์ Google ที่เกี่ยวข้องจะเพิ่มคำขอ MCP tools/call ด้วยรายการ _meta เพิ่มเติมที่ให้ข้อมูลที่ขอ ชุดสัญญาณที่รองรับมีดังนี้

  • current_user_location_fine (Gemini เท่านั้น สำหรับหมวดหมู่ที่ได้รับอนุญาต)
  • user_locale
  • current_user_location_coarse
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "find-restaurant",
    "arguments": {"query": "restaurants near me"},
    "_meta": {
      "current_user_location_fine": {
        "latitude_degrees": 37.7749,
        "longitude_degrees": -122.4194,
        "accuracy_meters": 112.4221
      },
      "user_locale": {
        "language_code": "en",
        "region_code": "US"
      }
    }
  }
}

วิธีแยกข้อมูลนี้

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("remote_mcp")

@mcp.tool()
async def find_restaurants(query: str, ctx: Context) -> str:
   # Access context directly from _meta
   request_context = ctx.request_context
   meta_dict = ctx.request_context.meta.model_dump() if ctx.request_context.meta else {}

   location_context = meta_dict.get("current_user_location_fine", {})
   lat = location_context.get("latitude_degrees")
   lng = location_context.get("longitude_degrees")
   if lat and lng:
       return f"Finding '{query}' near ({lat}, {lng})"
   return f"Finding '{query}' (no location provided)"

การแสดงผล UX

แอป MCP

ผลิตภัณฑ์ Google ที่เกี่ยวข้องรองรับการผสานรวมแอป MCP สำหรับเส้นทางของผู้ใช้ที่เลือกเพื่ออนุญาตให้สร้างอินเทอร์เฟซผู้ใช้ที่กำหนดเอง ทำตามข้อกำหนดสำหรับวิธีการผสานรวมทั่วไป

การผสานรวมแอป MCP ในผลิตภัณฑ์ Google ที่เกี่ยวข้องมาพร้อมกับข้อควรระวังต่อไปนี้

การนำเข้าทรัพยากร ณ เวลาที่ลงทะเบียน

ผลิตภัณฑ์ Google ที่เกี่ยวข้องจะดึงข้อมูลทรัพยากร UI ในระหว่างการนำเข้าเครื่องมือ เช่นเดียวกับรายการเครื่องมือและคำอธิบายเครื่องมือ ซึ่งหมายความว่าระบบจะไม่รับการอัปเดตทรัพยากร เช่น การเปลี่ยนแปลงใน JavaScript โดยอัตโนมัติ และต้องมีการนำเข้าเครื่องมืออีกครั้ง

ทรัพยากร UI รายการเดียวต้องมีขนาดไม่เกิน 15 MB และทรัพยากร UI สะสมในเซิร์ฟเวอร์ต้องไม่เกิน 100 MB

ทรัพยากร UI ต้องใช้ประเภท MIME ที่รองรับอย่างใดอย่างหนึ่งต่อไปนี้ text/html, text/javascript, text/css หรือ text/html;profile=mcp-app ประเภท MIME ที่ไม่ได้มาตรฐานหรือเฉพาะแพลตฟอร์มจะตรวจสอบไม่ผ่านเมื่อพุชไปยังตัวอย่าง

หลักเกณฑ์ CSP

ผลิตภัณฑ์ Google ที่เกี่ยวข้องจะเป็นไปตามข้อกำหนดอย่างเป็นทางการของ MCP Apps ซึ่งรวมถึง CSP [1], [2] และจะบล็อกคำขอที่ละเมิดคำสั่ง CSP

ผลิตภัณฑ์ Google ที่เกี่ยวข้องยังกำหนดให้เพิ่ม blob: และ data: ลงใน CSP ด้วย หากใช้ ระบบจะไม่เพิ่มรายการเหล่านี้โดยค่าเริ่มต้น นักพัฒนาแอปสามารถเลือกได้ว่าจะเพิ่ม (หรือไม่เพิ่ม) ลงใน CSP

Script-src เป็นข้อยกเว้น

คำสั่งเดียวที่เราอนุญาตคือ unsafe-inline (เพิ่มโดยค่าเริ่มต้น), wasm-unsafe-eval และ data: (หากรวมอยู่ใน resource_domains) หาก iframe กำลังโหลดสคริปต์ภายนอก คุณสามารถแก้ไขได้โดยการรวม JS ไว้ใน HTML หรือใช้แฮช Subresource Integrity (SRI)

  • ตัวเลือกที่ 1: JS แบบในบรรทัด/แพ็กเกจใน HTML (ง่ายที่สุด)

    • โค้ด JS ของแพ็กเกจ:

      • แทรกเนื้อหาของ component-init.js ไว้ในแท็ก <script> โดยตรงในเพย์โหลด HTML ที่แสดงผลสำหรับทรัพยากร UI ดังนี้

        <script>
// Paste component-init.js content directly here
</script>

    • นำแท็ก <script src> ระยะไกลออก

      • ลบการอ้างอิง <script src="https://api.mycompany.com/..."> ออกจากเอกสาร HTML

    • เครื่องมืออัปเดต/นำเข้าอีกครั้ง

  • ตัวเลือกที่ 2: ใช้แฮช Subresource Integrity (SRI)

    ใช้ตัวเลือกนี้หากต้องโฮสต์สคริปต์ภายนอกที่ https://api.company.com/...

    • คำนวณแฮช SHA-256 ของสคริปต์
      • สร้างแฮช SHA-256 แบบ base64 ของ component-init.js
    • เพิ่มแฮชลงใน resourceDomains (ต้องใส่คำนำหน้า sha256- เพื่อให้ตรงกับแอตทริบิวต์ integrity)
    • อัปเดตแท็ก HTML <script>
      • เพิ่มแอตทริบิวต์ integrity และ crossorigin ลงในแท็กสคริปต์ในวิดเจ็ต HTML
    • ยืนยันส่วนหัว CORS ใน CDN/เซิร์ฟเวอร์
      • ตรวจสอบว่า api.company.com แสดง component-init.js ด้วย Access-Control-Allow-Origin: * (หรืออนุญาต scf.usercontent.goog) เพื่อให้เบราว์เซอร์อ่านเนื้อหาการตอบกลับสำหรับการยืนยัน SRI ได้
    • เครื่องมือส่งข้อมูลอีกครั้ง/อัปเดต

หลักเกณฑ์ด้านความปลอดภัยสำหรับคำอธิบายเครื่องมือ MCP

เนื่องจากคำอธิบายเป็นบริบทเดียวที่โมเดลมีเพื่อทำความเข้าใจความสามารถของเครื่องมือ จึงต้องเขียนคำอธิบายอย่างถูกต้องและปลอดภัยเพื่อป้องกันพฤติกรรมที่ไม่พึงประสงค์ โปรดปฏิบัติตามหลักเกณฑ์ต่อไปนี้เมื่อร่างคำอธิบายเครื่องมือ

  • อธิบายฟังก์ชันการทำงาน แต่อย่ากำหนดลักษณะการทำงาน คำอธิบายต้องอธิบายสิ่งที่เครื่องมือทำอย่างถูกต้อง ไม่ใช่สั่งให้โมเดลดำเนินการต่อๆ ไป
  • กำหนดขอบเขตและข้อกำหนด ระบุเป้าหมายหลักของเครื่องมือ สถานการณ์ที่เฉพาะเจาะจง (เมื่อใด) สำหรับการใช้งาน และอินพุต (พารามิเตอร์/อาร์กิวเมนต์) ที่จำเป็นทั้งหมดให้ชัดเจน
  • ตรวจสอบความถูกต้อง คำอธิบายต้องแสดงถึงโค้ดพื้นฐานของเครื่องมืออย่างตรงไปตรงมา อย่าอ้างว่าเครื่องมือเป็นแบบอ่านอย่างเดียวหากเครื่องมือดำเนินการเขียนหรือลบ

ความเสี่ยงด้านความปลอดภัยและวิธีหลีกเลี่ยง

พื้นที่เสี่ยง แนะนำ หลีกเลี่ยงแนวทางปฏิบัตินี้โดยเด็ดขาด

การแทรกพรอมต์

ใช้ภาษาที่สื่อถึงวัตถุประสงค์และเป็นประโยคบอกเล่าเพื่อระบุวัตถุประสงค์และฟังก์ชันการทำงานของเครื่องมืออย่างชัดเจน

ใช้คำสั่งบังคับเพื่อลบล้างลักษณะการทำงานของโมเดลหรือเปลี่ยนแปลงขั้นตอนของระบบ (เช่น "คุณต้องพูดว่า..." "หลังจากวิ่ง คุณต้อง...") คำสั่ง เช่น "ต้อง" หรือ "สำคัญ" จะยอมรับได้ก็ต่อเมื่อกำหนดข้อจำกัดของพารามิเตอร์ที่มีโครงสร้างหรือกฎการใช้งานเท่านั้น

ใช้การจัดรูปแบบธรรมดามาตรฐานสำหรับข้อความคำอธิบายเครื่องมือ

ใช้การจัดรูปแบบที่ดึงดูดความสนใจ เช่น การใช้อักษรตัวพิมพ์ใหญ่มากเกินไปและแท็ก เช่น VERY IMPORTANT: หรือ **CRITICAL**

มุ่งเน้นที่ฟังก์ชันและลักษณะการทำงานที่คาดหวังของเครื่องมือเท่านั้น

มีคำสั่งหรือคำแนะนำให้สวมบทบาทเพื่อเพิกเฉยต่อคำแนะนำก่อนหน้า

การแอบใช้และการลักลอบใช้เครื่องมือ

ตรวจสอบว่าคำอธิบายมีความเจาะจงและจำกัดเฉพาะความสามารถจริงที่เกี่ยวข้องของเครื่องมือ

เขียนคำอธิบายเครื่องมือที่กว้างหรือคลุมเครือเกินไป หรืออ้างว่าเครื่องมือเดียวสามารถทำฟังก์ชันที่ไม่เกี่ยวข้องได้หลายอย่าง

เลือกชื่อเครื่องมือที่ไม่ซ้ำกัน สื่อความหมาย และสมเหตุสมผล

ใช้ชื่อเครื่องมือที่แตกต่างจากเครื่องมือที่เชื่อถือได้เพียงเล็กน้อย หรือใช้ชื่อทั่วไป (เช่น do_everything_tool, assistant_tool)

อย่าพูดถึงชื่อเครื่องมือของแอปอื่นหรือแพลตฟอร์มภายนอกในคำอธิบาย

อ้างอิงเครื่องมืออื่นๆ อย่างชัดเจน หรือสร้างกฎใหม่เกี่ยวกับเวลาหรือวิธีที่ควรใช้เครื่องมืออื่นๆ

อนุญาตให้เครื่องมือวางแผนของโมเดลเลือกเครื่องมือที่เหมาะสมที่สุดตามบริบทของผู้ใช้

รวมภาษาที่ต่อต้านการแข่งขันหรือพรอมต์ SEO ประเภทใดก็ตามที่สั่งให้โมเดลเลือกใช้เครื่องมือของคุณมากกว่าเครื่องมือที่คล้ายกัน

การจัดการทริกเกอร์

คำอธิบายไม่ได้อ้างอิงหรือตอบสนองต่อวลีในประวัติการสนทนาทั่วไป

สร้างตรรกะแบบมีเงื่อนไขที่ทริกเกอร์การดำเนินการที่เป็นอันตรายโดยอิงตามวลีของผู้ใช้ที่พบบ่อยและไม่เป็นอันตราย (เช่น "ขอบคุณ" "เพื่อสรุป")

การใช้พารามิเตอร์ในทางที่ผิด

กำหนดเฉพาะพารามิเตอร์ที่จำเป็นสำหรับฟังก์ชันของเครื่องมือ และใช้ชื่อที่เจาะจงสำหรับข้อมูลอินพุต (เช่น file_id, search_term)

กำหนดพารามิเตอร์ฟังก์ชันด้วยชื่อที่สอดคล้องกับสถานะภายในของ Agent (เช่น system_prompt, conversation_history, full_context)

การขโมยข้อมูล

การออกแบบโดยคำนึงถึงความเป็นส่วนตัว - ตัวระบุแบบทึบแสงและการตรวจสอบสิทธิ์ที่จัดการโดยโฮสต์

ใช้รหัสที่ไม่ละเอียดอ่อน ไม่ใช่ PII ดิบ การจัดการข้อมูลทั้งหมดต้องอยู่ภายในขอบเขตที่ได้รับอนุญาตและปลอดภัย และไม่มีการอ้างอิงในคำอธิบายสาธารณะว่ามีการส่งข้อมูลไปยังภายนอก การดำเนินการของเครื่องมือจะรับช่วงสิทธิ์โดยอัตโนมัติผ่านการแฮนด์เชคของ OAuth

คุณควรล้างข้อมูลที่ละเอียดอ่อนก่อนส่งไปยังผลิตภัณฑ์ Google ที่เกี่ยวข้อง

ขอ PII, PHI หรือข้อมูลส่วนบุคคลและ/หรือข้อมูลที่ละเอียดอ่อนอื่นๆ จากผู้ใช้ ข้อมูลส่วนตัวหรือข้อมูลทางธุรกิจ หรือนิติบุคคลในลักษณะใดก็ตามที่ละเมิดข้อกำหนดในการให้บริการของผลิตภัณฑ์ Google ที่เกี่ยวข้อง

พูดถึงหรือกำหนดให้ส่งข้อมูลผู้ใช้ (คำค้นหา ตำแหน่ง บริบท) ไปยัง URL ของบุคคลที่สาม บริการบันทึก หรือระบบภายนอกที่ไม่ได้รับอนุญาต

แนวทางปฏิบัติแนะนำด้านฟังก์ชันและการตั้งชื่อ

นอกจากการรักษาความปลอดภัยให้กับคำอธิบายเครื่องมือแล้ว คุณยังต้องตรวจสอบว่าโมเดลสามารถเลือกและดำเนินการได้อย่างน่าเชื่อถือโดยไม่สับสน ปฏิบัติตามแนวทางปฏิบัติแนะนำด้านฟังก์ชันและการตั้งชื่อต่อไปนี้

  • ความถูกต้องของพารามิเตอร์ ตรวจสอบว่าชื่อและประเภทพารามิเตอร์ทั้งหมดในคำอธิบายตรงกับการใช้งานจริงของเครื่องมือทุกประการ
  • การตั้งชื่อที่เหมาะสม ชื่อของเครื่องมือควรเป็นคำใบ้ที่ชัดเจนและชัดเจนเกี่ยวกับฟังก์ชันของเครื่องมือ หลีกเลี่ยงชื่อที่ธรรมดาเกินไป เช่น "execute" นอกจากนี้ ชื่อยังต้องสอดคล้องกับระบบนิเวศของเครื่องมือที่กว้างขึ้นด้วย

ภาคผนวก: การเพิ่มโครงสร้างพื้นฐานและเครือข่ายลงในรายการที่อนุญาต

หากโครงสร้างพื้นฐานการโฮสต์, เกตเวย์ API หรือไฟร์วอลล์จำกัดการเชื่อมต่อขาเข้าตามที่อยู่ IP ต้นทาง ให้เพิ่มบล็อก CIDR ขาออกของ Google ต่อไปนี้ลงในรายการที่อนุญาต

  • 108.177.64.0/20
  • 142.250.88.0/22
  • 172.217.80.0/20
  • 192.178.20.0/22
  • 192.179.0.0/20
  • 74.125.232.0/24
  • 136.121.40.0/21

ตรวจสอบว่าสภาพแวดล้อมของคุณอนุญาตการเข้าชมจากช่วง IP เหล่านี้ในพอร์ต HTTPS 443 เพื่อให้ผลิตภัณฑ์ Google ที่เกี่ยวข้องเข้าถึงเซิร์ฟเวอร์ MCP ระยะไกลของคุณสำหรับการเริ่มต้น MCP, การค้นหาเครื่องมือ และการดำเนินการตามคำขอได้