MCP Tools Reference: chatmcp.googleapis.com

Herramienta: search_messages

Busca mensajes de Google Chat con palabras clave y filtros, y los devuelve en formato Markdown. Funciona en todos los espacios a los que el usuario tiene acceso o se puede limitar a una conversación específica.

Sigue esta guía cuando decidas usar search_messages en lugar de otras herramientas de búsqueda o lectura:

  • Usa search_messages cuando busques contenido de mensajes, palabras clave, menciones, vínculos, remitentes o mensajes no leídos específicos, posiblemente en varios espacios o sin un ID de conversación conocido.
  • Usa list_messages cuando conozcas el ID del espacio o de la conversación específicos y quieras leer los mensajes de forma secuencial en orden cronológico.
  • Usa search_conversations para encontrar metadatos de espacios, como IDs de conversaciones, por nombre visible del espacio o participantes (solo busca metadatos, no contenido de mensajes).

Si se proporciona searchParameters sin filtros específicos, se devuelven los mensajes recientes de las conversaciones a las que puede acceder el usuario.

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

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_messages",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Esquema de entrada

SearchMessagesRequest

Representación JSON 
{
  "searchParameters": {
    object (SearchParameters)
  },
  "pageSize": integer,
  "pageToken": string
}
Campos
searchParameters

object (SearchParameters)

Obligatorio. Son los parámetros de búsqueda que se usarán para la búsqueda.
pageSize

integer

Opcional. Es la cantidad máxima de resultados que se devolverán (hasta 100). Si no se especifica, se devuelven, como máximo, 25.
pageToken

string

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

SearchParameters

Representación JSON 
{
  "keywords": [
    string
  ],
  "conversationId": string,
  "sender": string,
  "isUnread": boolean,
  "hasLink": boolean,
  "startTime": string,
  "endTime": string,
  "mentionsMe": boolean,
  "conversationIncludesUser": string,
  "spaceDisplayNames": [
    string
  ],
  "conversationTypes": [
    enum (ConversationType)
  ],
  "hasAttachment": boolean
}
Campos
keywords[]

string

Opcional. Es un conjunto de palabras clave que se usan para filtrar los resultados.
conversationId

string

Opcional. Limita la búsqueda a un identificador de conversación específico, como el que devuelve la herramienta search_conversations. Formato: spaces/{ID}.
sender

string

Opcional. Filtrar los mensajes de un usuario específico Se puede usar el correo electrónico o el nombre del recurso del remitente. Los nombres de los recursos de usuario tienen el formato users/{ID}, en el que {ID} puede ser un ID de persona o su dirección de correo electrónico.
isUnread

boolean

Opcional. Filtra los mensajes que el usuario que llama no leyó.
hasLink

boolean

Opcional. Filtra los mensajes que contienen al menos una URL.
startTime

string

Opcional. Filtra los mensajes creados después de este momento. Formato: Marca de tiempo ISO 8601.
endTime

string

Opcional. Filtra los mensajes creados antes de esta hora. Formato: Marca de tiempo ISO 8601.
mentionsMe

boolean

Opcional. Filtra los mensajes que mencionan explícitamente al usuario que llama.
conversationIncludesUser

string

Opcional. Filtra los mensajes en los MD y los chats en grupo que incluyan el correo electrónico o el ID del usuario específico.
spaceDisplayNames[]

string

Opcional. Filtra por una lista de nombres de espacios. Los nombres visibles de los espacios coinciden parcialmente. Nota: Solo se devuelven las 5 coincidencias principales.
conversationTypes[]

enum (ConversationType)

Opcional. Filtrar por tipo de conversación
hasAttachment

boolean

Opcional. Filtra los mensajes que contienen al menos un archivo adjunto. Nota: Este campo está en desarrollo y es posible que aún no sea compatible con todos los entornos.

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.

Esquema de salida

Respuesta para buscar mensajes de Google Chat. Si se propaga next_page_token, se puede volver a llamar a SearchMessages con ese token para recuperar la siguiente página de resultados.

SearchMessagesResponse

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

object (ChatMessage)

Es una lista de objetos de mensaje que coinciden con los criterios de búsqueda.
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.

ChatMessage

Representación JSON 
{
  "messageId": string,
  "threadId": string,
  "plaintextBody": string,
  "sender": {
    object (User)
  },
  "createTime": string,
  "threadedReply": boolean,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "reactionSummaries": [
    {
      object (ReactionSummary)
    }
  ],
  "quotedMessageMetadata": {
    object (QuotedMessageMetadata)
  }
}
Campos
messageId

string

Es el nombre del recurso del mensaje. Formato: spaces/{space}/messages/{message}
threadId

string

Es la conversación a la que pertenece este mensaje. Este campo estará vacío si el mensaje no está en un hilo. Formato: spaces/{space}/threads/{thread}
plaintextBody

string

Es el cuerpo del mensaje con formato de Markdown.
sender

object (User)

Es el remitente del mensaje.
createTime

string

Solo salida. Es la marca de tiempo de cuando se creó el mensaje. Formato: Marca de tiempo ISO 8601.
threadedReply

boolean

Indica si el mensaje es una respuesta en una conversación.
attachments[]

object (ChatAttachmentMetadata)

Son los archivos adjuntos que se incluyen en el mensaje.
reactionSummaries[]

object (ReactionSummary)

Es el resumen de las reacciones con emojis que se incluyen en el mensaje.
quotedMessageMetadata

object (QuotedMessageMetadata)

Solo salida. Información sobre un mensaje original que se cita o reenvía en este mensaje. Nota: Este campo está en desarrollo y es posible que aún no esté presente en todos los entornos.

Usuario

Representación JSON 
{
  "userId": string,
  "displayName": string,
  "email": string,
  "userType": enum (UserType)
}
Campos
userId

string

Es el nombre del recurso de un usuario de Chat. Formato: users/{user}.
displayName

string

Es el nombre visible de un usuario de Chat.
email

string

Es la dirección de correo electrónico del usuario. Este campo solo se propaga cuando el tipo de usuario es HUMAN.
userType

enum (UserType)

Es el tipo de usuario.

ChatAttachmentMetadata

Representación JSON 
{
  "attachmentId": string,
  "filename": string,
  "mimeType": string,
  "source": enum (Source),
  "driveFileId": string
}
Campos
attachmentId

string

Es el nombre del recurso del archivo adjunto. Formato: spaces/{space}/messages/{message}/attachments/{attachment}.
filename

string

Nombre del archivo adjunto.
mimeType

string

Tipo de contenido (tipo de MIME)
source

enum (Source)

Es la fuente del archivo adjunto.
driveFileId

string

Solo salida. Es el ID del archivo de Google Drive. Solo se propaga cuando la fuente es DRIVE_FILE. Se usa con el MCP de Google Drive.

ReactionSummary

Representación JSON 
{
  "emoji": string,
  "count": integer
}
Campos
emoji

string

Es la cadena Unicode del emoji o el nombre del emoji personalizado.
count

integer

Es la cantidad total de reacciones con el emoji asociado.

QuotedMessageMetadata

Representación JSON 
{
  "messageId": string,
  "lastUpdateTime": string,
  "quoteType": enum (QuoteType),
  "plaintextBody": string,
  "sender": string,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "forwardedMetadata": {
    object (ForwardedMetadata)
  }
}
Campos
messageId

string

Solo salida. Es el nombre del recurso del mensaje original que se cita o reenvía. Formato: spaces/{space}/messages/{message}
lastUpdateTime

string

Solo salida. Es la marca de tiempo de cuando se creó o actualizó por última vez el mensaje original antes de citarlo o reenviarlo. Formato: Marca de tiempo ISO 8601.
quoteType

enum (QuoteType)

Solo salida. Es el tipo de cotización.
plaintextBody

string

Solo salida. Instantánea del cuerpo del texto del mensaje original en el momento de citarlo o reenviarlo Se aplica el formato de Markdown para FORWARD y de texto sin formato para REPLY.
sender

string

Solo salida. Es el nombre visible del autor del mensaje original.
attachments[]

object (ChatAttachmentMetadata)

Solo salida. Son los archivos adjuntos que formaban parte del mensaje original. Se propaga solo para el tipo de cuota FORWARD.
forwardedMetadata

object (ForwardedMetadata)

Solo salida. Son los metadatos sobre la conversación de origen del mensaje reenviado. Se propaga solo para el tipo de cuota FORWARD.

ForwardedMetadata

Representación JSON 
{
  "conversationId": string,
  "conversationDisplayName": string
}
Campos
conversationId

string

Solo salida. Es el nombre del recurso de la conversación de origen. Formato: spaces/{space}
conversationDisplayName

string

Solo salida. Es el nombre visible de la conversación de origen en el momento en que se reenvió el mensaje. 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.

UserType

Es el tipo de usuario de Google Chat.

Enums
USER_TYPE_UNSPECIFIED Sin especificar.
HUMAN Usuario humano.
APP Usuario de la app

Fuente

Es la fuente del archivo adjunto.

Enums
SOURCE_UNSPECIFIED Reservados.
DRIVE_FILE El archivo es de Google Drive.
UPLOADED_CONTENT El archivo se subirá a Chat.

QuoteType

Es el tipo de cita que indica si el mensaje es una respuesta de cita o un mensaje reenviado.

Enums
QUOTE_TYPE_UNSPECIFIED Reservados. Tipo de cita no definido.
REPLY El mensaje es una respuesta con cita a un mensaje original en la misma conversación.
FORWARD El mensaje se reenvía desde un mensaje original en una conversación diferente o desde un hilo diferente en la misma conversación.

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.messages.readonly
  • https://www.googleapis.com/auth/chat.spaces.readonly
  • https://www.googleapis.com/auth/chat.memberships.readonly
  • https://www.googleapis.com/auth/chat.users.readstate.readonly