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 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 grupales (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 búsqueda sea una subcadena que no distingue 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 muestra todas las conversaciones de las que forma parte el usuario que llama.

Esta herramienta solo muestra las conversaciones de las que forma parte 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 debe continuar con la búsqueda.

En la siguiente muestra de código, se muestra 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. Lista de direcciones de correo electrónico de los participantes para filtrar las conversaciones, sin incluir 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

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

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 (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. Debe ser un valor entre 0 y 999,999,999, inclusive.

ConversationType

Define el tipo de conversación.

Enums
CONVERSATION_TYPE_UNSPECIFIED Sin especificar.
NAMED_SPACE Es 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 le puede enviar un mensaje de confirmación a un usuario.

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

  • 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