MCP Tools Reference: chatmcp.googleapis.com

Herramienta: search_conversations

Busca conversaciones de Google Chat (espacios con nombre, mensajes directos [MD] o chats grupales) por nombre visible o participantes para encontrar IDs de conversación.

Esta herramienta busca metadatos de conversación, NO contenido de mensajes. Para buscar en el historial de mensajes o encontrar mensajes por palabra clave, remitente o marca de tiempo, usa search_messages.

Si solo se proporcionan participants, esta herramienta encuentra mensajes directos 1:1 (si se proporciona un participante) o chats grupales (si se proporcionan varios participantes) que incluyen a los participantes especificados y al usuario que llama.

Si solo se proporciona una query, esta herramienta busca conversaciones en las que la consulta es una substring que no distingue mayúsculas de minúsculas del nombre visible de la conversación.

Si se proporcionan participants y query, esta herramienta encuentra conversaciones por participantes y, luego, las filtra por nombre visible.

Si no se proporcionan participants ni query, esta herramienta muestra todas las conversaciones de las que el usuario que llama es miembro.

Esta herramienta solo muestra las conversaciones de las que el usuario que llama es miembro.

Muestra una lista de objetos de conversación que contienen IDs de conversación (formato: spaces/{space}), nombres visibles y tipos de conversación.

IMPORTANTE: Una lista conversations vacía no significa que no haya más resultados en general. Si next_page_token está presente, se pueden recuperar más páginas. Si obtienes una lista vacía, pero un next_page_token, pregúntale al usuario si debe continuar con la búsqueda.

En la siguiente muestra de código, se explica cómo usar curl para llamar a la herramienta del MCP search_conversations.

Solicitud 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

Representación JSON 
{
  "spaceNameQuery": string,
  "pageSize": integer,
  "pageToken": string,
  "participants": [
    string
  ]
}
Campos
spaceNameQuery

string

Es opcional. Es el texto que se buscará en los nombres visibles del espacio (coincidencia de substring que no distingue mayúsculas de minúsculas).
pageSize

integer

Es opcional. Es la cantidad máxima de espacios que se mostrarán. El servicio puede mostrar menos que este valor. Si no se especifica, se mostrarán como máximo 20 espacios. El valor máximo es 1,000; valores superiores a 1,000 se convertirán en 1,000.
pageToken

string

Es opcional. Un token de página, recibido desde una llamada search_conversations anterior. Proporciona esto para recuperar la página siguiente.
participants[]

string

Es opcional. Es una lista de direcciones de correo electrónico de los participantes para filtrar las conversaciones, excluyendo al llamador.

Esquema de salida

Respuesta que contiene la lista de conversaciones coincidentes.

SearchConversationsResponse

Representación JSON 
{
  "conversations": [
    {
      object (Conversation)
    }
  ],
  "nextPageToken": string
}
Campos
conversations[]

object (Conversation)

Es una lista de objetos de conversación que coinciden con los criterios de búsqueda. Cada conversación incluye conversation_id (formato: spaces/{space}), display_name, conversation_type y last_active_timestamp.
nextPageToken

string

Es un token que se puede enviar como page_token para recuperar la página siguiente. Si se omite este campo, no habrá páginas siguientes.

Conversación

Representación JSON 
{
  "conversationId": string,
  "displayName": string,
  "conversationType": enum (ConversationType),
  "lastActiveTimestamp": string
}
Campos
conversationId

string

Es el ID de la conversación (p.ej., "spaces/AAAAAAAAA").
displayName

string

Es el nombre visible de la conversación.
conversationType

enum (ConversationType)

Es el tipo de conversación (DIRECT_MESSAGE, GROUP_CHAT o NAMED_SPACE).
lastActiveTimestamp

string (Timestamp format)

Es la última hora activa de la conversación en formato ISO 8601.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

Marca de tiempo

Representación JSON 
{
  "seconds": string,
  "nanos": integer
}
Campos
seconds

string (int64 format)

Representa los segundos de la hora UTC desde la época de Unix 1970-01-01T00:00:00Z. Debe estar entre -62135596800 y 253402300799 inclusive (que corresponde a 0001-01-01T00:00:00Z a 9999-12-31T23:59:59Z).
nanos

integer

Fracciones no negativas de un segundo a una resolución de nanosegundos. Este campo es la parte de nanosegundos de la duración, no una alternativa a los segundos. Los valores de segundos negativos con fracciones deben tener valores nanos no negativos que se cuentan hacia adelante en el tiempo. Debe estar entre 0 y 999,999,999 inclusive.

ConversationType

Define el tipo de conversación.

Enums
CONVERSATION_TYPE_UNSPECIFIED Sin especificar.
NAMED_SPACE Un espacio con nombre.
GROUP_CHAT Un chat grupal entre 3 o más personas.
DIRECT_MESSAGE Un mensaje directo entre dos personas o entre una persona y una app de Chat.

Anotaciones de herramientas

Las anotaciones de herramientas se envían a los clientes del MCP para describir el riesgo básico de una herramienta determinada. La mayoría de los clientes tratan estas sugerencias como no confiables, pero se pueden usar para decidir cuándo se puede enviar un mensaje de confirmación a un usuario.

Junto con la cadena de título, las siguientes sugerencias booleanas se definen de la siguiente manera:

  • readOnlyHint: Si es verdadero, la herramienta no modifica su entorno. Valor predeterminado: false.
  • destructiveHint: Si es verdadero, la herramienta puede realizar acciones destructivas. Si es falso, la herramienta solo puede realizar acciones aditivas. Valor predeterminado: true.
  • idempotentHint: Si es verdadero, llamar a la herramienta de forma repetida con los mismos argumentos no tendrá ningún efecto adicional en su entorno. Valor predeterminado: false.
  • openWorldHint: Si es verdadero, la herramienta puede interactuar con un "mundo abierto" de entidades externas. Si es falso, la herramienta solo puede interactuar con entidades internas. Por ejemplo, una herramienta de búsqueda web sería de mundo abierto, mientras que una herramienta de memoria no lo sería.

Sugerencia destructiva: ❌ | Sugerencia idempotente: ✅ | Sugerencia de solo lectura: ✅ | Sugerencia de mundo abierto: ❌

Alcances de la autorización

Se necesita uno de los siguientes alcances de OAuth:

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