MCP Tools Reference

Complete reference for all 25 Maexry MCP tools — parameters, return values, and constraints for read, write, batch, label, and attachment operations.

MCP Tools Reference

Complete reference for all 25 tools exposed by the Maexry MCP server. Tools are grouped by capability. All tools require a valid Bearer token. Most accept an optional account_id to target a specific Gmail account — if omitted, the primary account is used.

Core Read Tools

xiftly_get_email

Fetch a single email by message ID. Returns full content with PII redacted by the on-device Sentry engine before delivery.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | message_id | string | Yes | Gmail message ID (alphanumeric) | | account_id | string | No | Target account. Defaults to primary. |

Returns — subject, from, to, date, body, category, is_read, is_starred, thread_id

xiftly_get_thread

Fetch all messages in a Gmail thread.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | thread_id | string | Yes | Gmail thread ID | | account_id | string | No | Target account. Defaults to primary. |

Returns — Array of messages in thread order. Each message has the same shape as xiftly_get_email.

xiftly_search_emails

Search your inbox with optional filters. All filters are combined with AND logic.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | query | string | No | Full-text search query | | from | string | No | Filter by sender address or domain | | date_after | string | No | ISO 8601 date — messages after this date | | date_before | string | No | ISO 8601 date — messages before this date | | label | string | No | Gmail label name or ID | | is_read | boolean | No | true for read, false for unread | | has_attachment | boolean | No | true to include only messages with attachments | | category | string | No | Maexry category name (e.g. "To Respond", "Marketing") | | limit | integer | No | Max results. Default: 20. Max: 100. | | account_id | string | No | Target account. Defaults to primary. |

Returns — Array of message summaries: message_id, thread_id, subject, from, date, category, is_read, has_attachment

xiftly_get_categories

List all email categories with message counts.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | account_id | string | No | Target account. Defaults to primary. |

Returns — Array of { category, count, unread_count }. Categories: To Respond, FYI, Notification, Meeting Update, Actioned, Marketing, Trunk, Newsletter.

xiftly_get_action_cards

Retrieve AI-generated action cards — extracted deadlines, tasks, and meeting items from your email.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | limit | integer | No | Max results. Default: 20. Max: 100. | | account_id | string | No | Target account. Defaults to primary. |

Returns — Array of action cards: card_id, type (task/deadline/meeting), title, due_date, source_message_id, is_snoozed, snoozed_until

xiftly_get_daily_brief

Fetch the AI-generated daily brief — a structured summary of inbox activity, pending items, and upcoming events extracted from email.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | account_id | string | No | Target account. Defaults to primary. |

Returns — generated_at, unread_count, pending_actions, highlights (array of brief items), newsletter_highlights

xiftly_get_vault_notes

List notes saved in the Sovereign Vault.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | limit | integer | No | Max results. Default: 20. Max: 100. | | account_id | string | No | Target account. Defaults to primary. |

Returns — Array of { note_id, title, created_at, updated_at, source_message_id }

Core Write Tools

xiftly_classify_email

Manually reclassify an email into a specific category.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | message_id | string | Yes | Gmail message ID | | category | string | Yes | Target category name (e.g. "To Respond", "FYI") | | account_id | string | No | Target account. Defaults to primary. |

Returns — { message_id, previous_category, new_category, success }

xiftly_snooze_action

Snooze an action card until a specified time.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | card_id | string | Yes | Action card ID from xiftly_get_action_cards | | until | string | Yes | ISO 8601 datetime to reactivate the card | | account_id | string | No | Target account. Defaults to primary. |

Returns — { card_id, snoozed_until, success }

xiftly_save_vault_note

Create a new note in the Sovereign Vault.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | title | string | Yes | Note title | | content | string | Yes | Note body (plain text or markdown) | | source_message_id | string | No | Link the note to a specific email | | account_id | string | No | Target account. Defaults to primary. |

Returns — { note_id, title, created_at, success }

xiftly_archive_email

Archive a single email.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | message_id | string | Yes | Gmail message ID | | account_id | string | No | Target account. Defaults to primary. |

Returns — { message_id, success }

xiftly_delete_email

Move a single email to Trash.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | message_id | string | Yes | Gmail message ID | | account_id | string | No | Target account. Defaults to primary. |

Returns — { message_id, success }

xiftly_mark_read

Mark an email as read.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | message_id | string | Yes | Gmail message ID | | account_id | string | No | Target account. Defaults to primary. |

Returns — { message_id, success }

xiftly_mark_unread

Mark an email as unread.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | message_id | string | Yes | Gmail message ID | | account_id | string | No | Target account. Defaults to primary. |

Returns — { message_id, success }

xiftly_star_email

Star or unstar an email.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | message_id | string | Yes | Gmail message ID | | starred | boolean | Yes | true to star, false to unstar | | account_id | string | No | Target account. Defaults to primary. |

Returns — { message_id, starred, success }

xiftly_draft_reply

Generate a draft reply for an email using your configured AI provider.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | message_id | string | Yes | Gmail message ID to reply to | | tone | string | Yes | "professional", "casual", or "direct" | | instructions | string | No | Additional instructions for the AI (e.g. "decline politely") | | account_id | string | No | Target account. Defaults to primary. |

Returns — { draft_body, subject, to, tone, message_id }

The draft is not sent automatically. Use it as a starting point in the Maexry compose view or copy it to your mail client.

Label & Move Tools

xiftly_list_labels

List all Gmail labels available for the account.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | account_id | string | No | Target account. Defaults to primary. |

Returns — Array of { label_id, name, type }. type is system or user.

xiftly_label_email

Add or remove a Gmail label from an email.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | message_id | string | Yes | Gmail message ID | | label_id | string | Yes | Gmail label ID (from xiftly_list_labels) | | action | string | Yes | "add" or "remove" | | account_id | string | No | Target account. Defaults to primary. |

Returns — { message_id, label_id, action, success }

xiftly_move_email

Move an email to a label or folder (removes from current location).

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | message_id | string | Yes | Gmail message ID | | destination_label_id | string | Yes | Target label ID (from xiftly_list_labels) | | account_id | string | No | Target account. Defaults to primary. |

Returns — { message_id, destination_label_id, success }

Batch Operation Tools

All batch tools accept up to 50 message IDs per call. Message IDs must be alphanumeric strings. Each call returns per-message success/failure results — a failure on one message does not abort the rest.

xiftly_batch_archive

Archive multiple emails in a single call.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | message_ids | string[] | Yes | Array of Gmail message IDs. Max 50. | | account_id | string | No | Target account. Defaults to primary. |

Returns — { results: [{ message_id, success, error? }], succeeded, failed }

xiftly_batch_delete

Move multiple emails to Trash.

Parameters

Returns — { results: [{ message_id, success, error? }], succeeded, failed }

xiftly_batch_mark_read

Mark multiple emails as read.

Parameters

Returns — { results: [{ message_id, success, error? }], succeeded, failed }

xiftly_batch_label

Add or remove a label from multiple emails.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | message_ids | string[] | Yes | Array of Gmail message IDs. Max 50. | | label_id | string | Yes | Gmail label ID (from xiftly_list_labels) | | action | string | Yes | "add" or "remove" | | account_id | string | No | Target account. Defaults to primary. |

Returns — { results: [{ message_id, success, error? }], succeeded, failed }

Attachment Tools

xiftly_get_attachments

List all attachments on an email. Does not download content.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | message_id | string | Yes | Gmail message ID | | account_id | string | No | Target account. Defaults to primary. |

Returns — Array of { attachment_id, filename, mime_type, size_bytes }

Security note: Filenames and MIME types are returned as-is from Gmail. Size is in bytes. No content is transferred by this call.

xiftly_download_attachment

Download an attachment and return its content as a base64-encoded string.

Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | message_id | string | Yes | Gmail message ID | | attachment_id | string | Yes | Attachment ID from xiftly_get_attachments | | account_id | string | No | Target account. Defaults to primary. |

Returns — { attachment_id, filename, mime_type, size_bytes, data } where data is base64-encoded file content.

Constraints:

Maximum attachment size: enforced by Maexry (large files are rejected with an error indicating the size limit)
PII redaction does not apply to raw attachment bytes — use caution when passing attachment content to AI providers
Scoped to the authenticated account — cross-account attachment access is not permitted

Error Codes

| Code | Meaning | |---|---| | auth_required | Missing or invalid Bearer token | | account_not_found | account_id not recognized or not exposed in MCP config | | message_not_found | message_id does not exist or was permanently deleted | | invalid_parameter | A required parameter is missing or fails validation | | batch_limit_exceeded | More than 50 message IDs passed to a batch tool | | attachment_too_large | Attachment exceeds the maximum download size | | vault_locked | Vault was locked during the request — reconnect and regenerate token | | gmail_error | Underlying Gmail API returned an error — details in error_detail field |

Start Your 14-Day Free Trial

← All Docs