ابزارها و مهارت‌ها

سرور MCP

ابزارهای یک سرور MCP که برای 1ai تعریف شده را با پروتکل JSON-RPC از برنامه یا ابزار خودتان صدا بزنید، با همان کلید API.

POST/v1/mcp/{slug}

سرورهای MCP از پیش برای 1ai تعریف می‌شوند؛ شما سرور نمی‌سازید. slug نام سروری است که برایتان فعال شده. سرور ناشناخته یا غیرفعال 404 می‌دهد، و سروری که فقط برای سطح‌های بالاتر حساب باز است 403 (پیام می‌گوید در سطح API شما در دسترس نیست). هر سرور هم فقط ابزارهای مجاز خودش را اجازه می‌دهد؛ صدا زدن ابزار ممنوع 403 می‌دهد. بدنه یک درخواست JSON-RPC 2.0 یا یک آرایه (batch) از آن‌هاست و بی‌تغییر به سرور MCP می‌رود. متدهای رایج MCP مثل initialize ، tools/list و tools/call را می‌توانید بفرستید. اگر آرایه‌ای بفرستید و یکی از tools/call ‌ها ممنوع باشد، کل آرایه رد می‌شود. پاسخ سرور (شامل خطاهای خودش) با همان کد وضعیت برمی‌گردد؛ اگر پاسخ سرور جریان رویداد باشد، آخرین پیام JSON-RPC آن برگردانده می‌شود. نشست MCP با هدر mcp-session-id منتقل می‌شود: مقدار آن را که در پاسخ initialize می‌آید نگه دارید و در درخواست‌های بعدی بفرستید. اعلان‌ها (درخواست بدون id) اگر پذیرفته شوند، پاسخ 202 بدون بدنه می‌گیرند. این مسیر اعتبار مصرف نمی‌کند، ولی هر فراخوانی در سقف تعداد درخواست در دقیقه‌ی کلید شما حساب می‌شود و هدرهای سقف (x-ratelimit-*) در پاسخ می‌آید.

نمونه‌ها

curl https://1ai.ir/v1/mcp/docs-search \
  -H "Authorization: Bearer $ONEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}'

200پاسخ

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "search_docs",
        "description": "Search the documentation and return matching passages.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string"
            }
          },
          "required": [
            "query"
          ]
        }
      }
    ]
  }
}

هدرها

mcp-session-idstring
$شناسه‌ی نشست MCP که سرور در پاسخ initialize می‌دهد. در درخواست‌های بعدی همان نشست بفرستید.$

پارامترهای مسیر

slugstringالزامی
$نام سرور MCP. حروف بزرگ و کوچک فرقی ندارد.$

بدنه‌ی درخواست

jsonrpcstringالزامی
$نسخه‌ی JSON-RPC.$
مقادیر مجاز:2.0
idstring | integer
$شناسه‌ی درخواست؛ پاسخ با همین شناسه برمی‌گردد. بدون آن، درخواست یک اعلان است.$
methodstringالزامی
$متد MCP، مثلاً tools/list یا tools/call . بدنه می‌تواند آرایه‌ای از چنین شیءهایی هم باشد.$
paramsobject
$پارامترهای متد. برای tools/call باید name ابزار و در صورت لزوم arguments را داشته باشد.$

خطاها

-32600400
بدنه شیء JSON-RPC یا آرایه‌ی غیرخالی از آن نیست، یا method رشته نیست. در JSON-RPC این error.code است، نه error.code معمول API.
-32602400
tools/call نام ابزار ندارد.
-32001403
سرور در سطح API شما باز نیست، یا ابزار خواسته‌شده ممنوع است.
-32002404
سروری با این نام نیست یا غیرفعال است.
rate_limit_exceeded429
سقف تعداد درخواست در دقیقه‌ی کلید پر شده؛ هدر retry-after را ببینید.
-32003502
سرور MCP پاسخ نداد یا خطا داد.

سرور MCP

نمونه‌ها

هدرها

پارامترهای مسیر

بدنه‌ی درخواست

خطاها

صفحه‌های مرتبط