MCP Lệnh gọi và ví dụ về công cụ

Khám phá các công cụ có sẵn

Sau khi ủy quyền OAuth, hãy sử dụng ứng dụng khách MCP với Streamable HTTP để khởi tạo kết nối và nhận các công cụ thông qua tools/list. Gọi công cụ qua tools/call. Đọc từng lược đồ đầu vào được trả về thay vì lấy tham số từ URL REST. ID lấy từ các lần đọc thường là chuỗi thập phân cho đối số đường dẫn; trường số bên trong nội dung vẫn là số ở nơi lược đồ yêu cầu.

Các ví dụ bên dưới là các thông báo của công cụ JSON-RPC sau khi khởi tạo, không hoàn thành các yêu cầu HTTP độc lập. Máy khách cung cấp mã thông báo truy cập và tiêu đề giao thức. Thay thế ID minh họa bằng hồ sơ được trả về cho đối tượng thuê của chính bạn.

Đọc danh mục

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "knowledge_get_categories",
    "arguments": {}
  }
}

Tạo bản nháp

Chọn một danh mục hiện có từ kết quả đọc. Danh mục này là bắt buộc. Không đặt trạng thái đã xuất bản trừ khi bạn có ý định xuất bản và hoàn thành bất kỳ xác nhận cần thiết nào.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "knowledge_create_article",
    "arguments": {
      "requestId": "support-demo-create-001",
      "body": {
        "title": "Withdrawal guide draft",
        "content": "Reviewed withdrawal instructions go here.",
        "categoryId": 12,
        "status": "draft"
      }
    }
  }
}

Xem trước bản cập nhật hoặc xóa

Đọc bài viết đầu tiên. Xem trước nội dung chính xác dự kiến viết, bao gồm cả ID yêu cầu mới. Xem trước không thực hiện nó.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "mcp_preview",
    "arguments": {
      "tool": "knowledge_delete_article",
      "arguments": {
        "id": "123",
        "requestId": "support-demo-delete-001"
      }
    }
  }
}

Sao chép version được trả về vào expectedVersion mà không thay đổi mục tiêu hoặc tham số dự định:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "knowledge_delete_article",
    "arguments": {
      "id": "123",
      "requestId": "support-demo-delete-001",
      "expectedVersion": "REPLACE_WITH_THE_64_CHARACTER_VERSION_FROM_PREVIEW"
    }
  }
}

Trình giữ chỗ không phải là phiên bản hợp lệ. Sử dụng giá trị thực tế gồm 64 ký tự được bản xem trước trả về.

Xác nhận và kiểm tra kết quả

Nếu kết quả báo cáo awaiting_approval, hãy mở approvalUrl, đăng nhập với tư cách là tài khoản ủy quyền và xem lại hành động. Chỉ phê duyệt nó mới chạy hoạt động đang chờ xử lý. Xác nhận hiện hết hạn sau 15 phút. Việc từ chối hoặc hết hạn không thực hiện việc ghi.

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "mcp_operation",
    "arguments": {
      "operationId": "REPLACE_WITH_RETURNED_OPERATION_ID"
    }
  }
}

Đầu ra của công cụ được chứa trong nội dung văn bản chứa JSON; kiểm tra nó và bất kỳ cờ isError nào. Chỉ riêng phản hồi HTTP hoặc liên kết phê duyệt không chứng minh được thành công. Đọc trạng thái hoạt động và khi hữu ích, hãy truy vấn bản ghi bị ảnh hưởng.

Thử lại an toàn

Sử dụng lại cùng một requestId và các đối số để thử lại mạng với cùng một lần ghi. Không sử dụng lại nó cho một hành động khác. Nếu nội dung đã thay đổi, hãy đọc và xem trước lại, sau đó gửi thao tác dự định mới cùng với ID yêu cầu mới. Nếu phản hồi bị mất hoặc một thao tác vẫn đang chạy, hãy truy vấn trạng thái và hồ sơ kinh doanh của nó trước khi quyết định phải làm gì; đừng bao giờ cho rằng thời gian chờ có nghĩa là không có gì xảy ra.

Máy khách AI thường thực hiện giao thức này cho người dùng. Những chi tiết này dành cho nhà phát triển khách hàng và để chẩn đoán quy trình làm việc của công cụ.