Overview
The Gmail integration lets users connect their Gmail account so Alysio can search and manage their email on their behalf. Users can ask Alysio to find messages (e.g. by sender, unread, or subject), read message or draft details, move messages to trash or restore them, list labels, and get message counts—all in natural language. The integration uses the user’s connected Google account so all actions apply to their own mailbox.
Supported capabilities / objects
- User profile — Get the authenticated user’s Gmail profile.
- Messages — Search messages (Gmail query format), get message details (ID, labels, snippet, Subject/From/To/Date), trash and untrash messages.
- Labels — List all labels (with counts), get a single label by ID.
- Drafts — Get draft details, search drafts (Gmail query format). (Create/delete draft are not exposed in the current tool set.)
- Message count — Get total or unread count per label (thread-level or message-level).
Authentication
Method: OAuth 2.0 (Google). The MCP sends requests using a Bearer token and a credential ID that identifies the user’s connected Google account.
Redirect URI: Configured when the Gmail integration is set up in Alysio.
Token handling
- OAuth tokens for the connected Google account are stored securely and refreshed automatically.
- Each user/tenant has their own credential; the MCP sends the appropriate credential ID with each request so calls are isolated per connection.
- On disconnect, that credential is no longer used and Gmail tools will not be available for that user until they reconnect Gmail.
Required scopes
https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/gmail.labels
| Scope | Purpose |
|---|
| gmail.readonly | Search and get messages, get drafts, list/get labels, get message counts, get user profile. |
| gmail.modify | Move messages to trash and restore from trash. |
Connection required: Users must connect Gmail in Alysio before Gmail tools work. If the connection is missing or expired, they may need to re-authorize in Settings → Integrations.
The Gmail MCP exposes the following tools. Users can invoke these capabilities through natural language in Alysio.
| Tool | Description | Example user prompts |
|---|
get_gmail_user_profile | Returns the authenticated user’s Gmail profile. | ”What’s my Gmail profile?”, “Who am I in Gmail?” |
search_gmail_messages | Searches messages using Gmail query format (e.g. from:, is:unread, subject:). | ”Find emails from boss@company.com”, “Show my unread emails.” |
get_gmail_message_details | Returns details for a message by ID (labels, snippet, Subject, From, To, Date). | ”Open this email”, “Show me the full details of message 18abc123.” |
trash_gmail_message | Moves a message to Trash by ID. | ”Delete this email”, “Move message 18abc123 to trash.” |
untrash_gmail_message | Restores a message from Trash by ID. | ”Restore this email”, “Untrash message 18abc123.” |
list_gmail_labels | Lists all Gmail labels (ID, name, type, message/thread counts). | ”What labels do I have?”, “List my Gmail labels.” |
get_gmail_label | Returns a single label’s details by ID. | ”Get my INBOX label”, “Show details for label ID INBOX.” |
get_gmail_draft_details | Returns draft details by ID (labels, snippet, Subject, From, To, Date). | ”Show draft r-123”, “What’s in this draft?” |
search_gmail_drafts | Searches drafts using Gmail query format. | ”Find drafts about the proposal”, “Search my drafts.” |
get_gmail_message_count | Returns message or thread count (total or unread) for a label; defaults to unread thread count for INBOX. | ”How many unread emails do I have?”, “Count of messages in INBOX.” |
App Behavior
- API calls are made on-demand only when the user asks something that requires Gmail data or an action (e.g. search messages, get details, trash/untrash, list labels, get count). There is no background sync; each request triggers the relevant Gmail API call using the user’s OAuth credential.
Example flow
- User asks: “How many unread emails do I have?”
- Alysio routes the request to the Gmail MCP.
- The MCP calls
get_gmail_message_count with label INBOX and a field such as threadsUnread (or messagesUnread).
- The request is sent to the Gmail API using the user’s stored OAuth credential.
- The MCP returns the count; Alysio presents the answer in chat.
Troubleshooting
Common issues
- Missing or expired connection — User sees errors or no email data. Fix: Reconnect Gmail in Settings → Integrations (re-authorize with Google).
- 401 Unauthorized — Token invalid or revoked. Fix: Re-authorize the integration in Settings → Integrations.
- 403 Forbidden — Often due to insufficient OAuth scopes. Fix: Ensure the Gmail integration is configured with the required scopes (e.g.
gmail.readonly, gmail.modify).
- Search returns nothing — Query may be too strict or use unsupported operators. Fix: Use standard Gmail search operators (e.g.
from:, to:, subject:, is:unread); see Gmail search help if needed.
- Message count confusion — Default is unread thread count. Fix: Use
get_gmail_message_count with fields set to messagesUnread or messagesTotal for individual message counts.
Support
