MCP Chamadas de ferramentas e exemplos

Conheça as ferramentas disponíveis

Após a autorização de OAuth, use um cliente MCP com Streamable HTTP para inicializar a conexão e obter ferramentas por meio de tools/list. Chame ferramentas através de tools/call. Leia cada esquema de entrada retornado em vez de derivar parâmetros de URLs REST. IDs obtidos de leituras são normalmente strings decimais para argumentos de caminho; um campo numérico dentro de um corpo permanece numérico onde o esquema exige.

Os exemplos abaixo são mensagens da ferramenta JSON-RPC após a inicialização, e não solicitações HTTP independentes completas. O cliente fornece o token de acesso e os cabeçalhos do protocolo. Substitua IDs ilustrativos por registros retornados para seu próprio locatário.

Ler categorias

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

Crie um rascunho

Escolha uma categoria existente no resultado da leitura. A categoria é obrigatória. Não defina um status de publicado, a menos que pretenda publicar e preencher qualquer confirmação necessária.

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

Visualizar uma atualização ou exclusão

Leia o artigo primeiro. Visualize a gravação exata pretendida, incluindo um novo ID de solicitação. A visualização não a executa.

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

Copie o version retornado em expectedVersion sem alterar o destino ou os parâmetros pretendidos:

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

O espaço reservado não é uma versão válida. Use o valor real de 64 caracteres retornado pela visualização.

Confirme e confira o resultado

Se o resultado for awaiting_approval, abra approvalUrl, faça login como a conta de autorização e revise a ação. Somente aprová-lo executa a operação pendente. A confirmação atualmente expira após 15 minutos. A rejeição ou expiração não executa a gravação.

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

A saída da ferramenta é transportada em conteúdo de texto contendo JSON; inspecione-o e qualquer sinalizador isError. Uma resposta HTTP ou um link de aprovação por si só não prova sucesso. Leia o status da operação e, quando útil, consulte o registro afetado.

Tente novamente com segurança

Reutilize os mesmos requestId e argumentos para uma nova tentativa de rede da mesma gravação. Não o reutilize para outra ação. Se o conteúdo tiver sido alterado, leia e visualize novamente e, em seguida, envie uma nova operação pretendida com um novo ID de solicitação. Se uma resposta for perdida ou uma operação continuar em execução, consulte seu status e registro comercial antes de decidir o que fazer; nunca presuma que um tempo limite significa que nada aconteceu.

O cliente AI geralmente executa este protocolo para o usuário. Esses detalhes são para desenvolvedores de clientes e para diagnosticar o fluxo de trabalho de uma ferramenta.