Өөрийн API-г MCP хэрэгсэл болгох

API-гаа бүртгэх

Хөгжүүлэгчийн API хэсэгт орон зайн owner болон admin өөрсдийн HTTP endpoint-ийг Сэхэгийн MCP гарцаар ашиглах боломжтой. Бусад гишүүн тохиргоог харна. API болон нууц түлхүүр сонгосон орон зайд харьяалагдана.

https://api.example.com/v1 гэх мэт 443 порттой нийтийн HTTPS хаяг ашиглана. Endpoint зам энэ угтварт нэмэгдэнэ. Дотоод, loopback, link-local хаяг, URL доторх нэвтрэх мэдээлэл, redirect, мөн үндсэн URL-ийн query болон fragment-ийг зөвшөөрөхгүй.

1. API-г эзэмших орон зайгаа сонгоод Хөгжүүлэгчийн API → Нэмэх товчийг дарна.
2. Нэр, crm гэх мэт тогтмол namespace болон үндсэн HTTPS хаягийг оруулна. Namespace болон хэрэгслийн нэр нь жижиг латин үсгээр эхэлсэн, үсэг, тоо, доогуур зураас бүхий 1–40 тэмдэгт байна. Үүсгэсний дараа нэрийг өөрчлөхгүй.
3. Нэвтрэлтгүй, bearer token эсвэл API-key header сонгоно. Нууц түлхүүрийг энэ form-д оруулж хадгална. Түлхүүр backend дээр шифрлэгдэж, дахин харагдахгүй, MCP хэрэгслийн жагсаалтад орохгүй. Солих талбарыг хоосон үлдээвэл өмнөх түлхүүр хадгалагдана.
4. API-гаа хадгалаад AI client-д ашиглуулах endpoint бүрд хэрэгсэл нэмнэ. Тохиргоо хадгалах нь API хүсэлт илгээхгүй.

Endpoint параметрийг хэрэгслийн оролттой холбох

Хэрэгсэл нь нэр, тайлбар, HTTP арга, харьцангуй зам, оролтын JSON Schema болон параметрийн холбоос агуулна. AI-д хэзээ ашиглахыг тодорхой тайлбарлана. GET, HEAD нь custom.read.<namespace>.<tool_name>; POST, PUT, PATCH, DELETE нь custom.write.<namespace>.<tool_name> нэртэй болно.

Параметрийн холбоосын key нь endpoint параметрийн нэр, value нь оролтын property нэр байна. path, query, body-г тусад нь тохируулна. Оролт бүрийг дор хаяж нэг параметрт холбоно. Path оролт заавал required, scalar төрөлтэй байна. Query мөн scalar утгатай; JSON body нь nested object, array агуулж болно. GET, HEAD нь body mapping хүлээн авахгүй.

Жишээнд get_customer нэртэй GET хэрэгсэл, /customers/{id} зам тохируулна. custom.read.crm.get_customer нь customer_id болон include_orders авч, /v1/customers/<customer_id>?includeOrders=<include_orders> хүсэлт илгээнэ. Өгөөгүй нэмэлт оролтыг хүсэлтэд оруулахгүй.

Input JSON Schema:
{
  "type": "object",
  "properties": {
    "customer_id": { "type": "string", "description": "Customer ID" },
    "include_orders": { "type": "boolean" }
  },
  "required": ["customer_id"],
  "additionalProperties": false
}

Parameter mapping:
{
  "path": { "id": "customer_id" },
  "query": { "includeOrders": "include_orders" },
  "body": {}
}

Өөрчлөлт бичих endpoint тохируулах

POST /customers endpoint-д create_customer хэрэгсэл үүсгэж, доорх схем болон холбоосыг оруулаад POST сонгоно. Нэр нь custom.write.crm.create_customer болно. Дуудах үед хүсэлт бэлтгэж зөвшөөрлийн холбоос буцаана; шууд API руу илгээхгүй. Өөрчлөлт бичих хэрэгсэл бүр MCP дуудлагын _idempotency_key мөрөн аргументыг нэмэлтээр шаарддаг (1–100 тэмдэгт). Энэ нь endpoint руу дамжихгүй; ижил хүсэлтийг дахин оролдоход өмнөх key-г ашиглана.

Input JSON Schema:
{
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "email": { "type": "string" }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}

Parameter mapping:
{
  "path": {},
  "query": {},
  "body": { "name": "name", "email": "email" }
}

AI client-д эрх өгөх

Эдгээр эрх тухайн credential-ийн орон зайн бүх идэвхтэй custom API-г хамарна; API тус бүрийн эрх биш. Хандалтыг тусгаарлах шаардлагатай бол тусдаа орон зай ашиглана. API-ийн нууц түлхүүр backend дээр үлдэж, AI client зөвхөн Сэхэгийн MCP credential авна.

1. MCP эрх хэсэгт орон зайн credential үүсгэнэ. custom:read, custom:write нь анхдагчаар сонгогдоогүй, тусад нь идэвхжүүлэх эрхүүд юм.
2. GET, HEAD хэрэгсэлд custom:read сонгоно. Эдгээр хүсэлт шууд ажиллах тул зөвхөн өгөгдөл уншдаг endpoint ашиглана.
3. Өөрчлөлт бичих хүсэлт бэлтгэх шаардлагатай үед custom:write нэмнэ. Нэвтэрсэн owner, admin эсвэл editor хүн яг тухайн хүсэлтийг браузерт зөвшөөрөх ёстой.
4. Хөгжүүлэгчийн API хэсэгт харагдах Streamable HTTP хаягт Authorization: Bearer YOUR_MCP_TOKEN тохируулна. Тохиргоо, эрх өөрчлөгдвөл client-ийн хэрэгслийн жагсаалтыг шинэчилнэ. Зөв эрхтэй, идэвхтэй API болон хэрэгслүүд л харагдана.

Хүсэлтийг хянаж нэг удаа илгээх

Өөрийн API хүсэлт тусдаа зөвшөөрлийн урсгалтай. Social үйлдэл нь одоогийн зөвшөөрлийн хуудас, боломжийн тохиргоогоо ашиглана.

1. AI custom.write хэрэгслийг дуудаж, буцсан call ID болон бүтэн зөвшөөрлийн URL-ийг хадгална. Workspace параметр, token fragment-ийг өөрчлөхгүйгээр зөвшөөрөх хүнд холбоосыг өгнө.
2. Хүн нэвтэрч яг HTTP арга, бүрэн URL, JSON body-г шалгана. Зөвшөөрч, хүсэлт илгээх товч бэлтгэсэн хүсэлтийг нэг удаа ажиллуулна. Хүсэлт цуцлах нь API руу илгээхгүйгээр дуусгана.
3. Зөвшөөрлийн хуудсан дахь Төлөв шинэчлэх эсвэл custom.calls.get(call_id)-аар үр дүнг уншина. Ижил бэлтгэсэн хүсэлтийг дахин зөвшөөрөх нь давтан ажиллуулахгүй. Ижил дуудлагыг дахин оролдохдоо өмнөх _idempotency_key-г ашиглана; шинэ key нь шинэ хүсэлт болно.
4. Зөвшөөрөл дууссан, тохиргоо өөрчлөгдсөн бол шинэ хүсэлт бэлтгэнэ. Хүсэлт алдаатай болсон эсвэл хариу тасарсан бол давтан бичихээс өмнө өөрийн API дээрх үр дүнг шалгана; өөрчлөлт аль хэдийн хийгдсэн байж болно.

Дэмжих схем ба хүсэлтийн хязгаар

Оролтын схем JSON object, 32 KiB хүртэл хэмжээтэй, object бүрд 50 хүртэл property, найм хүртэл nested түвшинтэй байна. type, title, description, properties, required, additionalProperties, items, enum, const, тоон хязгаар, мөрийн урт, array хэмжээ, object хэмжээ, uniqueItems дэмжинэ. Reference, schema combinator, regex pattern болон бусад keyword дэмжихгүй. Үндсэн object-ийн нэмэлт property-г зөвшөөрөхгүй.

Үндсэн URL болон endpoint зам тус бүр 2,000 тэмдэгт хүртэл байна. Зам /-ээр эхэлж {parameter} ашиглана; query string, traversal, encoded path segment оруулахгүй. Query параметрийг mapping-аар өгнө. Request body 64 KiB, response 1 MiB хүртэл, хүсэлтийн хугацаа 20 секунд.

Нэг endpoint-ийг нуух бол хэрэгслийг, бүх endpoint-ийг нуух бол API-г идэвхгүй болгоно. Ижил тохиргооны form-оос дахин идэвхжүүлж болно. Дуудлага ажиллах үед одоогийн тохиргоо, эрхийг дахин шалгана.