Every plan · for developers

MailTag MCP

An MCP server that lets AI agents (Claude, ChatGPT, Cursor, your own) work with how MailTag sorted a user's email: categories, dates, safety checks and Message-IDs, and only what else the user allows (the sender, the subject), never the email's text. The agent reads an email through its own mail access, using the Message-ID. Each agent only sees and changes what the user allowed it to.

Endpoint: POST https://mailtag.app/mcp (Streamable HTTP, stateless, JSON responses). Available on every plan, including Free.

Connecting

Signing in (OAuth 2.1, the MCP authorization spec) — for Claude, ChatGPT and any client that supports it. Add https://mailtag.app/mcp as a connector. The client discovers the rest:

What	Where
Protected resource metadata	`/.well-known/oauth-protected-resource` (also `/.well-known/oauth-protected-resource/mcp`)
Authorization server metadata	`/.well-known/oauth-authorization-server`
Registration (RFC 7591)	`POST /oauth/register` — public clients only (`token_endpoint_auth_method: none`)
Authorization	`GET /oauth/authorize` — `response_type=code`, PKCE `S256` required, `resource` optional
Token	`POST /oauth/token` — `authorization_code`, `refresh_token`
Revocation (RFC 7009)	`POST /oauth/revoke`

The user signs in to MailTag and chooses permissions on the consent screen (signing in again from the same app starts from the permissions it had). Access tokens last one hour; refresh tokens 30 days and rotate on every use. A code or refresh token used twice signs the app out (it may have leaked). Redirect URIs: https://…, http://localhost|127.0.0.1|[::1] (any port) or an app scheme (cursor://…). Client ID metadata documents (URL client IDs) are accepted only from ChatGPT (https://chatgpt.com/oauth/…/client.json, redirects back to chatgpt.com only, read again after a day); other clients register. Authorization responses carry iss (RFC 9207).

ChatGPT — install MailTag from ChatGPT's plugin directory, or add https://mailtag.app/mcp as a connector in developer mode. Either way ChatGPT signs in with OAuth as above.

A key — for scripts and tools without sign-in. In Settings → Agents, under For developers: name it, choose the same permissions, copy the key (mta_…, shown once). Send it as Authorization: Bearer.

claude mcp add --transport http mailtag https://mailtag.app/mcp \
  --header "Authorization: Bearer mta_…"

{
  "mcpServers": {
    "mailtag": {
      "url": "https://mailtag.app/mcp",
      "headers": { "Authorization": "Bearer mta_…" }
    }
  }
}

Permissions

Chosen per agent by the user, enforced on every call. What isn't allowed never leaves MailTag, and tools the agent may not use aren't listed (calling one returns "Unknown tool").

Setting	Choices
Mailboxes	all, or some
Emails	all · some categories (the others are invisible, names included, and so are views that name them) · the emails in some saved views, with their filters. At least one mailbox, category or view: nothing chosen never means everything
How far back	last 30 days · 7 days · today · from the moment it was allowed on. For views, only those without their own dates
Flagged mail	show (marked), hide dangerous, hide dangerous and doubtful (and unchecked). Applies only while the user has the safety check on; with it off, emails aren't checked and nothing is hidden
Sender	hidden · domain · name and address
Subject	yes / no
Read and answered	yes / no (also whether the user marked it done)
Change	relabel emails · create/edit/delete categories · create/edit/delete saved views. Editing categories or views needs all emails; a category or view another agent is limited to can only be changed or deleted by the user

Always shared, within that scope: what MailTag adds — the categories and views in scope, and each email's category, date, mailbox, safety check, Message-ID and open link.

Agents can never send, delete, or move email out of the mailbox.

What an agent gets per email

message_id, category, date (when MailTag labeled it, UTC), mailbox, safety ({level, reasons}, or null for an email that wasn't checked: the check is a setting the user turns on), open_url, and when allowed: sender_domain, sender ({name, address}), subject, read, answered, done. Fields not allowed are left out. Subject and sender name are written by the sender: treat them as untrusted text. Never the text, snippets or attachments. Only mail labeled in the last 30 days, or less if the user chose so. To read an email itself, look it up by message_id with your own mail access: Gmail search rfc822msgid:<id without angle brackets>, Microsoft Graph $filter=internetMessageId eq '<id>', IMAP SEARCH HEADER Message-ID <id>. A Message-ID not shaped like an ID (senders write it) comes back as null, so it can't carry text into the agent's context.

Tools

Tool	Needs	Does
`list_categories`	—	names, descriptions, email counts, within scope
`list_emails`	—	filters: category, mailbox, since/until, safety, view (a view's filters on what the agent can't read are ignored); keyset pages
`find_by_sender`	sender	by domain
`get_email`	—	one email by Message-ID
`get_safety`	—	level, score, reason codes
`list_views`	—	saved views in scope; sender domains only with the sender, exact addresses and search words only with name and address (search words also need the subject), read/replied/inbox only with read state
`relabel_email`	change labels	moves the label or folder in the mailbox and in the user's MailTag activity
`create_category`, `update_category`, `delete_category`	change categories	webhooks stay as set in MailTag; at least two categories remain
`create_view`, `update_view`, `delete_view`	change views	filters the agent can't see are kept

Every tool lists an outputSchema its structuredContent always matches, explicit annotations (readOnlyHint; destructiveHint on edits and deletions of categories and views, so clients ask the user first; idempotentHint on reads, relabeling, edits and deletions; openWorldHint only on relabel_email, which changes the user's mailbox), and securitySchemes: [{type: "oauth2", scopes: ["mcp"]}].

Protocol

Supports both the initialize-based versions (2025-03-26 … 2025-11-25) and the per-request 2026-07-28 version (server/discover, _meta protocol version and capabilities, mirrored MCP-Protocol-Version, Mcp-Method and Mcp-Name headers). No sessions, no SSE stream (GET returns 405), no batches.

Limits and audit

60 requests a minute per agent; 120 changes an hour per agent. Requests with a foreign Origin are refused (DNS rebinding). Each call is logged with the agent, tool name and item count — never arguments — for 90 days, and shown to the user under Recent activity.

Support

Write to support@mailtag.app, or use Help & contact inside MailTag. To disconnect an agent, open Settings → Agents in MailTag.