MCP ツールの呼び出しと例

利用可能なツールを発見する

OAuth 認証後、Streamable HTTP で MCP クライアントを使用して接続を初期化し、tools/list を通じてツールを取得します。 tools/call を通じてツールを呼び出します。 REST URL からパラメータを取得するのではなく、返された各入力スキーマを読み取ります。読み取りから取得された ID は通常、パス引数の 10 進文字列です。本体内の数値フィールドは、スキーマで必要な場合は数値のままになります。

以下の例は、初期化後の JSON-RPC ツールメッセージであり、完全なスタンドアロン HTTP リクエストではありません。クライアントはアクセストークンとプロトコルヘッダーを提供します。例示的な ID を、独自のテナントに対して返されたレコードに置き換えます。

カテゴリを読む

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

ドラフトを作成する

読み取り結果から既存のカテゴリを選択します。カテゴリは必須です。公開して必要な確認を完了する予定がない限り、公開ステータスを設定しないでください。

{
  "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"
      }
    }
  }
}

更新または削除をプレビューする

まずは記事をお読みください。新しいリクエスト ID を含む、正確な意図した書き込みをプレビューします。プレビューでは実行されません。

{
  "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"
      }
    }
  }
}

意図したターゲットやパラメータを変更せずに、返された version を expectedVersion にコピーします。

{
  "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"
    }
  }
}

プレースホルダーは有効なバージョンではありません。プレビューによって返された実際の 64 文字の値を使用します。

結果を確認・確認する

結果が awaiting_approval と報告した場合は、approvalUrl を開いて、認証アカウントとしてサインインし、アクションを確認してください。承認するだけで保留中の操作が実行されます。現在、確認は 15 分後に期限切れになります。拒否または期限切れの場合、書き込みは実行されません。

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

ツールの出力は、JSON を含むテキストコンテンツで伝えられます。それと isError フラグを検査します。 HTTP の応答や承認リンクだけでは成功とは証明されません。操作ステータスを読み取り、必要に応じて、影響を受けるレコードをクエリします。

安全に再試行してください

同じ書き込みのネットワーク再試行には、同じ requestId と引数を再利用します。別のアクションに再利用しないでください。コンテンツが変更された場合は、再度読み取りとプレビューを行ってから、新しいリクエスト ID を使用して新しい目的の操作を送信します。応答が失われた場合、または操作が実行されたままの場合は、何をすべきかを決定する前に、そのステータスと業務記録を問い合わせてください。タイムアウトが何も起こらなかったことを意味するとは決して考えないでください。

通常、AI クライアントはユーザーに代わってこのプロトコルを実行します。これらの詳細は、クライアント開発者とツールのワークフローの診断を対象としています。