MCP Chiamate degli strumenti ed esempi

Scopri gli strumenti disponibili

Dopo l’autorizzazione OAuth, utilizzare un client MCP con Streamable HTTP per inizializzare la connessione e ottenere strumenti tramite tools/list. Chiama gli strumenti tramite tools/call. Leggere ogni schema di input restituito anziché derivare parametri dagli URL REST. Gli ID presi dalle letture sono in genere stringhe decimali per gli argomenti del percorso; un campo numerico all’interno di un corpo rimane numerico laddove lo schema lo richiede.

Gli esempi seguenti sono messaggi dello strumento JSON-RPC dopo l’inizializzazione, non richieste complete HTTP autonome. Il client fornisce il token di accesso e le intestazioni del protocollo. Sostituisci gli ID illustrativi con i record restituiti per il tuo tenant.

Leggi le categorie

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

Crea una bozza

Scegli una categoria esistente dal risultato della lettura. La categoria è obbligatoria. Non impostare uno stato pubblicato a meno che non intendi pubblicare e completare l’eventuale conferma richiesta.

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

Anteprima di un aggiornamento o di un’eliminazione

Leggi prima l’articolo. Visualizza in anteprima l’esatta scrittura prevista, incluso un nuovo ID richiesta. L’anteprima non lo esegue.

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

Copia il version restituito in expectedVersion senza modificare la destinazione o i parametri previsti:

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

Il segnaposto non è una versione valida. Utilizza il valore effettivo di 64 caratteri restituito dall’anteprima.

Conferma e controlla il risultato

Se il risultato riporta awaiting_approval, apri approvalUrl, accedi come account di autorizzazione ed esamina l’azione. Solo approvandolo viene eseguita l’operazione in sospeso. La conferma attualmente scade dopo 15 minuti. Il rifiuto o la scadenza non eseguono la scrittura.

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

L’output dello strumento viene riportato nel contenuto testuale contenente JSON; ispezionalo e qualsiasi flag isError. Una risposta HTTP o un link di approvazione da soli non dimostrano il successo. Leggere lo stato dell’operazione e, quando utile, interrogare il record interessato.

Riprova in tutta sicurezza

Riutilizzare gli stessi requestId e argomenti per un nuovo tentativo di rete della stessa scrittura. Non riutilizzarlo per un’altra azione. Se il contenuto è cambiato, leggi di nuovo e visualizza l’anteprima, quindi invia una nuova operazione prevista con un nuovo ID richiesta. Se si perde una risposta o un’operazione rimane in esecuzione, interrogarne lo stato e il record aziendale prima di decidere cosa fare; non dare mai per scontato che un timeout significhi che non è successo nulla.

Il client AI solitamente esegue questo protocollo per l’utente. Questi dettagli sono destinati agli sviluppatori client e alla diagnosi del flusso di lavoro dello strumento.