MCP Tools Reference: chatmcp.googleapis.com

Herramienta: search_conversations

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

Esta herramienta busca metadatos de conversaciones, 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 proporciona participants, esta herramienta busca mensajes directos 1:1 (si se proporciona un participante) o chats en grupo (si se proporcionan varios participantes) que incluyan a los participantes especificados y al usuario que llama.

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

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

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

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

Devuelve 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 debes continuar con la búsqueda.

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

Solicitud de 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 MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Esquema de entrada

SearchConversationsRequest

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

string

Opcional. Es el texto que se buscará en los nombres visibles de los espacios (coincidencia de subcadena que no distingue mayúsculas de minúsculas).
pageSize

integer

Opcional. Es la cantidad máxima de espacios que se devolverán. El servicio puede mostrar menos que este valor. Si no se especifica, se devolverá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

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

string

Opcional. Es la lista de direcciones de correo electrónico de los participantes para filtrar las conversaciones, sin incluir al emisor.

Esquema de salida

Es la respuesta que contiene la lista de conversaciones que coinciden.

SearchConversationsResponse

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

object (Conversation)

Es la lista de objetos de conversación que coinciden con los criterios de búsqueda. Cada conversación incluye el 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.

Solo se propaga si la solicitud se filtra por participants.

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. En el caso de los espacios con nombre, este es el nombre del espacio. En el caso de los mensajes directos 1:1, este es el nombre del otro participante. En el caso de los chats en grupo sin nombre, este es un nombre generado en función de los nombres de los miembros.
conversationType

enum (ConversationType)

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

string (Timestamp format)

Es la última hora de actividad 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 del horario UTC desde el tiempo Unix 1970-01-01T00:00:00Z. Debe estar entre -62135596800 y 253402300799 inclusive (lo 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. Deben ser valores de 0 a 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 en grupo 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 de 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 de destructivo: ❌ | Sugerencia de 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