MCP Tools Reference: chatmcp.googleapis.com

Ferramenta: search_conversations

Pesquisa conversas do Google Chat (espaços nomeados, mensagens diretas ou chats em grupo) por nome de exibição ou participantes para encontrar IDs de conversa.

Essa ferramenta pesquisa metadados de conversas, NÃO o conteúdo das mensagens. Para pesquisar no histórico de mensagens ou encontrar mensagens por palavra-chave/remetente/carimbo de data/hora, use search_messages.

Se apenas participants forem fornecidos, essa ferramenta vai encontrar mensagens diretas 1:1 (se um participante for fornecido) ou chats em grupo (se vários participantes forem fornecidos) que incluam os participantes especificados e o usuário que fez a chamada.

Se apenas uma query for fornecida, essa ferramenta vai pesquisar conversas em que a consulta seja uma substring sem distinção entre maiúsculas e minúsculas do nome de exibição da conversa.

Se participants e query forem fornecidos, essa ferramenta vai encontrar conversas por participantes e, em seguida, filtrá-las por nome de exibição.

Se nem participants nem query forem fornecidos, essa ferramenta vai listar todas as conversas de que o usuário que fez a chamada faz parte.

Essa ferramenta lista apenas as conversas de que o usuário que fez a chamada faz parte.

Retorna uma lista de objetos de conversa que contêm IDs de conversa (formato: spaces/{space}), nomes de exibição e tipos de conversa.

IMPORTANTE: uma lista conversations vazia não significa que não há mais resultados. Se next_page_token estiver presente, mais páginas poderão ser buscadas. Se você receber uma lista vazia, mas um next_page_token, pergunte ao usuário se você deve continuar a pesquisa.

O exemplo de código a seguir mostra como usar curl para chamar a ferramenta MCP search_conversations.

Solicitação curl 
curl --location 'https://chatmcp.googleapis.com/mcp/v1' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "search_conversations",
    "arguments": {
      // provide these details according to the tool MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Esquema de entrada

SearchConversationsRequest

Representação JSON 
{
  "spaceNameQuery": string,
  "pageSize": integer,
  "pageToken": string,
  "participants": [
    string
  ]
}
Campos
spaceNameQuery

string

Opcional. O texto a ser pesquisado nos nomes de exibição do espaço (correspondência de substring sem distinção entre maiúsculas e minúsculas).
pageSize

integer

Opcional. O número máximo de espaços a serem retornados. O serviço pode retornar um valor inferior a este. Se não for especificado, no máximo 20 espaços serão retornados. O valor máximo é 1.000. Valores maiores serão convertidos para 1.000.
pageToken

string

Opcional. Um token de página recebido de uma chamada search_conversations anterior. Forneça isso para recuperar a página subsequente.
participants[]

string

Opcional. Lista de endereços de e-mail dos participantes para filtrar as conversas, excluindo o autor da chamada.

Esquema de saída

Resposta contendo a lista de conversas correspondentes.

SearchConversationsResponse

Representação JSON 
{
  "conversations": [
    {
      object (Conversation)
    }
  ],
  "nextPageToken": string
}
Campos
conversations[]

object (Conversation)

Lista de objetos de conversa que correspondem aos critérios de pesquisa. Cada conversa inclui o conversation_id (formato: spaces/{space}), display_name, conversation_type e last_active_timestamp.
nextPageToken

string

Um token que pode ser enviado como page_token para recuperar a próxima página. Se esse campo for omitido, não haverá páginas subsequentes.

Conversa

Representação JSON 
{
  "conversationId": string,
  "displayName": string,
  "conversationType": enum (ConversationType),
  "lastActiveTimestamp": string
}
Campos
conversationId

string

O ID da conversa (por exemplo, "spaces/AAAAAAAAA").
displayName

string

O nome de exibição da conversa.
conversationType

enum (ConversationType)

O tipo de conversa (DIRECT_MESSAGE, GROUP_CHAT ou NAMED_SPACE).
lastActiveTimestamp

string (Timestamp format)

A última hora ativa da conversa no formato ISO 8601.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de "Z", outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

Carimbo de data/hora

Representação JSON 
{
  "seconds": string,
  "nanos": integer
}
Campos
seconds

string (int64 format)

Representa os segundos do horário UTC desde a época Unix 1970-01-01T00:00:00Z. Precisa estar entre -62135596800 e 253402300799, inclusive (o que corresponde a 0001-01-01T00:00:00Z a 9999-12-31T23:59:59Z).
nanos

integer

Frações não negativas de um segundo com resolução de nanossegundos. Esse campo é a parte de nanossegundos da duração, não uma alternativa aos segundos. Os valores de segundos negativos com frações ainda precisam ter valores em nanossegundos não negativos que representam períodos posteriores. Precisa estar entre 0 e 999.999.999, inclusive.

ConversationType

Define o tipo de conversa.

Tipos enumerados
CONVERSATION_TYPE_UNSPECIFIED Não especificado.
NAMED_SPACE Um espaço nomeado.
GROUP_CHAT Um grupo de chat entre três ou mais pessoas.
DIRECT_MESSAGE Uma mensagem direta entre dois humanos ou um humano e um app do Chat.

Anotações de ferramentas

As anotações de ferramentas são enviadas aos clientes MCP para descrever o risco básico de uma determinada ferramenta. A maioria dos clientes trata essas dicas como não confiáveis, mas elas podem ser usadas para decidir quando um aviso de confirmação pode ser enviado a um usuário.

Além da string de título, as seguintes dicas booleanas são definidas da seguinte maneira:

  • readOnlyHint: se for verdadeiro, a ferramenta não modifica o ambiente. Padrão: falso.
  • destructiveHint: se for verdadeiro, a ferramenta poderá realizar ações destrutivas. Se for falso, a ferramenta só poderá realizar ações aditivas. Padrão: verdadeiro.
  • idempotentHint: se for verdadeiro, chamar a ferramenta repetidamente com os mesmos argumentos não terá efeito adicional no ambiente. Padrão: falso.
  • openWorldHint: se for verdadeiro, a ferramenta poderá interagir com um "mundo aberto" de entidades externas. Se for falso, a ferramenta só poderá interagir com entidades internas. Por exemplo, uma ferramenta de pesquisa na Web seria de mundo aberto, enquanto uma ferramenta de memória não seria.

Dica destrutiva: ❌ | Dica idempotente: ✅ | Dica somente leitura: ✅ | Dica de mundo aberto: ❌

Escopos de autorização

Requer um dos seguintes escopos do OAuth:

  • https://www.googleapis.com/auth/chat.memberships.readonly
  • https://www.googleapis.com/auth/chat.spaces
  • https://www.googleapis.com/auth/chat.spaces.readonly