MCP Tools Reference: workspacemcp.googleapis.com

Tool: search_corpus

Performs a search across multiple Workspace corpora (Drive, Gmail, Calendar, and Chat) based on the provided query.

This tool is a cross-corpus search tool that by default fans out to all supported corpora (Drive, Gmail, Calendar, and Chat). If the user's query does not specify a particular corpus (e.g., "where am i planning to go for my photography walks in june?"), you MUST call this cross-corpus "search_corpus" tool first, rather than calling specific tools like "list_events", "search_threads", "list_threads", or "search_files". If this tool returns no results, you can then fallback to these per-product (single-corpus) search tools.

Note that if the user specifies a particular corpus in their query (e.g., "search for content in my email"), it is recommended to use a single-corpus tool, such as the GmailTool, for more focused results if available. However, this cross-corpus search tool will still function for those queries, and should be used if specific tools are not available.

This tool can filter results based on a query string. Pagination is not supported for cross-corpus search. Note that if a Gmail message contains attachments, they are not returned as a separate field; instead, attachment details will be included directly within the message's snippet.

The following code sample shows how to use curl to call the search_corpus MCP tool.

Curl Request 
curl --location 'https://workspacemcp.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_corpus",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

Request message for WorkspaceToolService.SearchCorpus.

SearchCorpusRequest

JSON representation 
{
  "query": string,
  "pageSize": integer,
  "pageToken": string
}
Fields
query

string

Required. The raw query string provided by the user.
pageSize

integer

Optional. Currently ignored. The server returns up to a server-defined number of results. Pagination isn't supported.
pageToken

string

Optional. Currently ignored. Pagination isn't supported.

Output Schema

Response message for WorkspaceToolService.SearchCorpus.

SearchCorpusResponse

JSON representation 
{
  "items": [
    {
      object (SearchResultItem)
    }
  ],
  "nextPageToken": string
}
Fields
items[]

object (SearchResultItem)

A list of universal search result items, each potentially from a different corpus.
nextPageToken

string

Currently always empty. Pagination isn't supported.

SearchResultItem

JSON representation 
{

  "driveResult": {
    object (DriveResult)
  },
  "gmailResult": {
    object (GmailResult)
  },
  "calendarResult": {
    object (CalendarResult)
  },
  "chatResult": {
    object (ChatResult)
  }
}
Fields
Union field item_result. The specific search result from a workspace corpus. item_result can be only one of the following:
driveResult

object (DriveResult)

A search result from Google Drive.
gmailResult

object (GmailResult)

A search result from Gmail.
calendarResult

object (CalendarResult)

A search result from Google Calendar.
chatResult

object (ChatResult)

A search result from Google Chat.

DriveResult

JSON representation 
{
  "itemId": string,
  "title": string,
  "mimeType": string,
  "viewUrl": string,
  "contentSnippet": string
}
Fields
itemId

string

Unique identifier for the Drive item (e.g., document, sheet, presentation).
title

string

The title of the Drive item.
mimeType

string

The mime type of the Drive item.
viewUrl

string

The URL to view the Drive item.
contentSnippet

string

The content snippet of the Drive item.

GmailResult

JSON representation 
{
  "thread": {
    object (GmailThread)
  }
}
Fields
thread

object (GmailThread)

The thread that match the search query.

GmailThread

JSON representation 
{
  "threadId": string,
  "messages": [
    {
      object (GmailMessage)
    }
  ]
}
Fields
threadId

string

Identifier for the Gmail thread.
messages[]

object (GmailMessage)

A list of messages in the thread.

GmailMessage

JSON representation 
{
  "messageId": string,
  "subject": string,
  "snippet": string,
  "sender": string,
  "recipients": [
    string
  ],
  "ccRecipients": [
    string
  ],
  "viewUrl": string
}
Fields
messageId

string

Identifier for the Gmail message.
subject

string

The subject of the Gmail message.
snippet

string

The content snippet of the Gmail message.
sender

string

The sender's email address of the Gmail message.
recipients[]

string

The recipients' email addresses of the Gmail message.
ccRecipients[]

string

The cc recipients' email addresses of the Gmail message.
viewUrl

string

The URL to view the Gmail message.

CalendarResult

JSON representation 
{
  "eventId": string,
  "title": string,
  "description": string,
  "calendarId": string,
  "viewUrl": string,
  "location": string,
  "start": {
    object (DateOrDateTime)
  },
  "end": {
    object (DateOrDateTime)
  }
}
Fields
eventId

string

Unique identifier for the Calendar event.
title

string

The title of the Calendar event.
description

string

The description of the Calendar event.
calendarId

string

The calendar id of the Calendar event, which is the owner's email address.
viewUrl

string

The URL to view the Calendar event.
location

string

Represents the location of the Calendar event.
start

object (DateOrDateTime)

The start time of the Calendar event (inclusive).
end

object (DateOrDateTime)

The end time of the Calendar event (exclusive).

DateOrDateTime

JSON representation 
{
  "date": string,
  "dateTime": string,
  "timeZone": string
}
Fields
date

string

ISO 8601 date in yyyy-mm-dd format (for example, '2019-11-20').
dateTime

string

ISO 8601 timestamp (for example, '2019-11-20T08:19:06-07:00').
timeZone

string

The original time zone in IANA Time Zone Database format (for example, 'America/Los_Angeles'). The returned 'date_time' might be in a different display time zone (for example the viewer's current time zone).

ChatResult

JSON representation 
{
  "messages": [
    {
      object (ChatMessage)
    }
  ]
}
Fields
messages[]

object (ChatMessage)

A list of messages that could be grouped together as a conversation.

ChatMessage

JSON representation 
{
  "id": {
    object (ChatMessageId)
  },
  "plaintextBody": string,
  "sender": {
    object (ChatUser)
  },
  "createTime": string,
  "threadedReply": boolean,
  "attachments": [
    {
      object (ChatAttachment)
    }
  ],
  "reactionSummaries": [
    {
      object (ChatReaction)
    }
  ],
  "viewUrl": string
}
Fields
id

object (ChatMessageId)

Unique identifier for the message and thread.
plaintextBody

string

Plain text body of the message.
sender

object (ChatUser)

The sender of the message.
createTime

string (Timestamp format)

Timestamp when the message was created.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
threadedReply

boolean

Whether message is a thread reply.
attachments[]

object (ChatAttachment)

Attachments included in the message.
reactionSummaries[]

object (ChatReaction)

The emoji reactions summary included in the message.
viewUrl

string

The URL to view the Chat message.

ChatMessageId

JSON representation 
{
  "messageId": string,
  "threadId": string
}
Fields
messageId

string

Resource name of the message.
threadId

string

The thread this message belongs to.

ChatUser

JSON representation 
{
  "userId": string,
  "displayName": string,
  "email": string,
  "chatUserType": enum (ChatUserType)
}
Fields
userId

string

Unique identifier for the user.
displayName

string

The display name of the user.
email

string

The email address of the user.
chatUserType

enum (ChatUserType)

The type of the user.

Timestamp

JSON representation 
{
  "seconds": string,
  "nanos": integer
}
Fields
seconds

string (int64 format)

Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be between -62135596800 and 253402300799 inclusive (which corresponds to 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z).
nanos

integer

Non-negative fractions of a second at nanosecond resolution. This field is the nanosecond portion of the duration, not an alternative to seconds. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be between 0 and 999,999,999 inclusive.

ChatAttachment

JSON representation 
{
  "attachmentId": string,
  "filename": string,
  "mimeType": string,
  "source": enum (Source)
}
Fields
attachmentId

string

Resource name of the attachment.
filename

string

Name of the attachment.
mimeType

string

Content type (MIME type).
source

enum (Source)

The source of the attachment.

ChatReaction

JSON representation 
{
  "emoji": string,
  "count": integer
}
Fields
emoji

string

The emoji unicode string or custom emoji name.
count

integer

The total number of reactions using the associated emoji.

ChatUserType

Enum indicating the chat user type.

Enums
CHAT_USER_TYPE_UNSPECIFIED Default value. Do not use.
CHAT_USER_TYPE_HUMAN Human user.
CHAT_USER_TYPE_BOT Bot user.

Source

The source of the attachment.

Enums
SOURCE_UNSPECIFIED Reserved.
DRIVE_FILE The file is a Google Drive file.
UPLOADED_CONTENT The file is uploaded to Chat.

Tool Annotations

Tool annotations are sent to MCP clients to describe the basic risk of a given tool. Most clients treat these hints as untrusted, but they can be used to decide when a confirmation prompt might be sent to a user.

Along with the title string, the following boolean hints are defined as follows:

  • readOnlyHint: If true, the tool doesn't modify its environment. Default: false.
  • destructiveHint: If true, then the tool can perform destructive actions. If false, then the tool can only perform additive actions. Default: true.
  • idempotentHint: If true, then calling the tool repeatedly with the same arguments will have no additional effect on its environment. Default: false.
  • openWorldHint: If true, then the tool can interact with an 'open world' of external entities. If false, then the tool can only interact with internal entities. For example, a web search tool would be open world, while a memory tool would not be open world.

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.readonly
  • https://mail.google.com/
  • https://www.googleapis.com/auth/gmail.modify
  • https://www.googleapis.com/auth/gmail.readonly
  • https://www.googleapis.com/auth/calendar
  • https://www.googleapis.com/auth/calendar.readonly
  • https://www.googleapis.com/auth/chat.messages
  • https://www.googleapis.com/auth/chat.messages.readonly
  • https://www.googleapis.com/auth/chat.spaces.readonly
  • https://www.googleapis.com/auth/chat.memberships.readonly