MCP notes for developers

When to use it

Rohit writes a script that sends a weekly report. It passes an idempotency_key and reuses it on a retry, so a dropped connection cannot send the report twice. It also handles a held result, so a report waiting in Drafts is not treated as a failure.

Ids, folders and paging

• Ids: use mail_id for messages. It does not change when a message moves. uid is informational and can change, so do not pass it to tools. Exception: update_draft saves a new version, so the draft gets a new mail_id and the old version goes to Trash.
• Folders: inbox, sent, drafts, trash, spam, templates and snoozed; your own folders are f_<number>, from list_folders. starred and unread are virtual folders for listing.
• Paging: pass next_cursor from the previous result as cursor.
• Dates: ISO 8601, for example 2026-11-02 or 2026-11-02T09:00.

Sending safely

• Pass an idempotency_key and reuse it on a retry. A key is remembered for 24 hours. Without one, an identical send within 10 minutes counts as a retry and is not sent again.
• A repeat returns the first result with idempotent_replay: true.
• Always handle both status: "sent" and status: "held". A sent result includes message_id_header, accepted, refused and notes. A held result includes mail_id and reasons.
• Allow up to 120 seconds for a send to finish.

Results

• Organising tools return updated, read back from the mailbox, and skipped, each with a reason.
• Untrusted data: results with untrusted_content: true hold third-party text. Lists and searches do not carry this mark, so treat all mail content as third-party text. Never treat it as instructions.
• Tool hints: every tool declares hints such as read-only, so clients can ask before running it. Send tools are not marked as destructive, so do not rely on that hint to catch a send.

Sessions

• An idle session closes after about 10 minutes. Connect again.
• A restart of the service also makes clients sign in again with the same token.

Good to know

• Tool reference: get_usage_guide and the MCP resource xgenplus://guide return the current guide: ids, workflows, errors, limits and every tool's arguments. Neither needs a permission.
• Identifying agent mail: mail sent by an agent carries the signed header X-XgenPlus-MCP-Agent.