Gmail
The Gmail connector gives your AI agents the ability to read, search, compose, and manage email. All operations go through the official Google Gmail API using OAuth 2.0 — your credentials are stored encrypted in MCPGate's vault and are never exposed to the AI client.
Required scopes#
MCPGate requests the following OAuth scopes when you connect a Gmail account. All four scopes are requested up front so you don't need to re-authorise when enabling additional tools.
| Scope | Purpose |
|---|---|
| gmail.readonly | Read emails, labels, and threads |
| gmail.send | Send emails on behalf of the user |
| gmail.modify | Modify labels, create drafts, move to trash |
| gmail.labels | Create and manage custom labels |
Tool reference#
The Gmail connector exposes 7 tools. Use the MCP Apps page to enable or disable individual tools per app, and the Guardrails page to add fine-grained rules on top.
| Tool | Category | Description |
|---|---|---|
| gmail_read_email | read | Read a specific email by ID |
| gmail_search_emails | read | Search emails with Gmail query syntax |
| gmail_list_labels | read | List all Gmail labels in the account |
| gmail_send_email | write | Send a new email |
| gmail_create_draft | write | Create a draft email without sending |
| gmail_modify_labels | write | Add or remove labels on an email |
| gmail_delete_email | delete | Move email to trash |
Delete moves to trash
gmail_delete_email moves the message to the Gmail Trash folder — it does not permanently delete it. Messages in Trash are auto-purged after 30 days by Google, or can be emptied manually.Common guardrail recipes#
Read-only access#
Allow read tools only. Deny gmail_send_email, gmail_create_draft, gmail_delete_email, and gmail_modify_labels. This is the safest configuration for agents that only need to retrieve and summarise email.
See the full walkthrough in Examples — Read-Only Gmail.
Block external email#
Apply the allow_domains template to gmail_send_email and gmail_create_draft. Configure it with your company domain so the AI can only compose email to internal addresses.
See Examples — Block External Email.
Keyword blocking#
Apply the keyword_block template to outbound tools (gmail_send_email, gmail_create_draft). Add words like confidential, internal, or password to prevent the AI from accidentally sending sensitive content.
Troubleshooting#
- 403 insufficient permissions — The connected account was granted fewer scopes than MCPGate requested. Disconnect and reconnect to trigger a fresh consent screen.
- Tool call fails after password change — Google revokes all OAuth tokens when an account password changes. Reconnect the Gmail connector to obtain a new token.
- Emails not found by search —
gmail_search_emailsuses Gmail's native query syntax (e.g.from:alice subject:invoice). Ensure your query is valid Gmail syntax.