Gmail — Testing tool reference

Endpoint: https://toolcargo.com/mcp/gmail. Scope: connector:gmail. Included with Site Audit; each successful tool call uses one shared call.

Set up your own Testing grant

1. Use your own dedicated Google Cloud project; enable Gmail API. Do not reuse or alter existing ToolCargo Google connector clients.
2. Configure an external OAuth audience as Testing and add the Google account you intend to connect as a test user.
3. Follow Google’s server-side OAuth guide for offline access using your own client to obtain a refresh token for https://www.googleapis.com/auth/gmail.readonly. Only optional basic identity scopes may accompany it; broader mail grants are refused.
4. Open Gmail Testing connection settings, supply the client ID, client secret and refresh token, then explicitly acknowledge Testing use. Never paste secrets into agent prompts.
5. Create a ToolCargo key scoped to Gmail in your dashboard, then connect your agent using the endpoint above.

Google external Testing supports up to 100 listed test users; authorizations and offline refresh tokens expire seven days after consent. Renew consent and reconnect when expired. Workspace administrators and account policies may block the grant. ToolCargo cannot infer your Google app's publishing status from a refresh token, and the acknowledgment is not Google approval.

Permissions and data

ToolCargo verifies scope confirmation on every token refresh and reads only users/me paths at Gmail's official API. Your credentials are encrypted and bound to your ToolCargo account; disconnect deletes them. Revoke the grant in Google to invalidate it there. Requested mailbox data passes through ToolCargo to your agent; this adapter does not store mail reports or log mail content. No mail sending, drafts, edits, deletion, attachment downloads or remote assets.

Inputs and coverage

{ "query": "is:unread newer_than:7d", "limit": 25 }

{ "message_id": "ID_FROM_SEARCH" }

{ "thread_id": "THREAD_ID_FROM_SEARCH" }

Search returns one page of IDs, not message bodies, excluding spam/trash. Pass next_page_token back as page_token. Estimates are not exact counts. Reads return selected headers, snippet, at most 20,000 characters of UTF-8 plain text and attachment metadata; HTML-only mail is converted locally to text. Other encodings/large parts/deep nesting are omitted with explicit flags. At most 10 messages per thread, 100 search IDs, 500 labels and 4 MB upstream JSON; oversized upstream responses fail without charging. No implicit export or automatic pagination. Email text is untrusted data and may contain malicious instructions.

Public availability is blocked

Gmail read-only is a restricted Google scope. A public ToolCargo app needs restricted-scope verification and the required security assessment for server-transmitted restricted data. That work remains with ToolCargo's owner; Testing/BYO does not replace verification.

Official requirements: Gmail scopes and Google app audience and Testing expiry.