Skip to Content
xstate

Connect AI apps

Let Claude, Claude Code, Codex, Cursor or ChatGPT work with your xstate mail, calendar, files and contacts over MCP.

xstate runs an MCP server, so the AI app you already use can read your mail, write drafts, check your calendar and search your files. You choose what each app may do when you connect it, and you can disconnect it at any time.

The address to give your app:

https://mcp.xstate.com/mcp

Connect your app

Every app sends you to xstate to sign in and approve it the first time it connects. See What you approve.

Claude

In Claude (web or desktop), open Customize → Connectors, choose Add → Add custom connector, enter xstate as the name and the address above, then click Add and Connect.

On a Team or Enterprise plan, an Owner adds the connector under Organization settings → Connectors first. Each member then connects it with their own xstate account.

Claude Code

claude mcp add --transport http xstate https://mcp.xstate.com/mcp

Then run /mcp in Claude Code, pick xstate and sign in. Or sign in from your terminal with claude mcp login xstate.

Codex

codex mcp add xstate --url https://mcp.xstate.com/mcp
codex mcp login xstate

The second command opens xstate in your browser.

Cursor

Add this to ~/.cursor/mcp.json (or .cursor/mcp.json in one project):

{
  "mcpServers": {
    "xstate": { "url": "https://mcp.xstate.com/mcp" }
  }
}

Then open Cursor Settings → MCP and click Connect next to xstate.

ChatGPT

ChatGPT calls these apps or connectors, and where you add one depends on your plan and the current ChatGPT settings. Look for creating an app or connector from a server URL (some plans need Developer mode turned on first), and enter the address above with OAuth sign-in.

Other apps

Any app that supports remote MCP servers over Streamable HTTP with OAuth can connect. See For developers.

What you approve

When an app connects, xstate shows you:

  • Which app is asking. Apps that publish their details on their own domain (Claude, ChatGPT and Cursor do) show that domain. Others show only the name they gave, marked as unverified.
  • Where access will be sent, and a warning when that is a program on your own computer. Continue only if you just started connecting from it.

Then you choose:

ChoiceOptionsStarts on
OrganizationAny you belong toThe first
MailboxesMailboxes you can readYour own mailbox
EmailRead only · Draft only · Draft and sendDraft only
Calendar, Storage, ContactsOff · Read · Read and changeRead
Manage domains and mailboxesOff or on, for owners and adminsOff

With Draft only, the app writes drafts and you send them. It can never send mail unless you choose Draft and send.

An app never gets more than you have: every action is checked against your own access, then narrowed to what you chose. Mail and calendars of mailboxes you didn't pick are out of reach, including through search.

Some things are never available to a connected app: resetting passwords, giving people access to mailboxes, API keys, AI provider keys, secrets, inviting or removing members, and public file links.

Manage connected apps

Settings → Connected apps lists the apps you connected, what each may do and when it was last active, with Disconnect. Owners and admins also see every app connected to the organization and can disconnect any of them. Access ends at once.

A connection ends by itself 30 days after it was last used. To change what an app may do, connect it again: the new choices replace the old ones. Each app can make up to 120 calls a minute.

Email, files and calendar invitations are written by other people. A message can try to talk an AI app into doing something you didn't ask for. xstate tells connected apps to treat what they read as information, not instructions, but keep an eye on what your app does, and give it no more than it needs.

Tools

What a connected app can use, by what you allowed. Each tool also tells the app what it returns.

Always

Every connection has these.

ToolNeedsWhat it does
auth_mealwaysThe signed-in user and the organizations they belong to, with their role and member id in each.
members_listalwaysEveryone in the organization: name, email, role (owner, admin or member) and status (invited or active).
storage_list_membersalwaysPeople in the organization, with their member id, to share files with.

Email

Read only, Draft only or Draft and send.

ToolNeedsWhat it does
email_list_mailboxesread onlyList the mailboxes in the organization that you can see, optionally only one domain or kind.
email_get_mailboxread onlyGet one mailbox: its address, aliases, kind, display name and quota.
email_list_foldersread onlyList the folders (Inbox, Sent, Drafts, Archive, Junk, Trash and custom ones) with unread and total counts, for one mailbox or every mailbox in the organization whose mail you can read.
email_list_messagesread onlyList conversations, newest first, one row per conversation (its newest matching message, with threadSize): one mailbox, or every mailbox you can read when mailboxId is omitted.
email_searchread onlyFind mail by meaning: the passages of messages and their attachments (PDF, text, CSV, Markdown, JSON; any language) that best answer a question, across every mailbox you can read, or one with mailboxId.
email_get_threadread onlyGet every message in a conversation, oldest first, with plain-text and HTML bodies and attachment details (blobId, name, type, size).
email_update_messagedraft onlyChange one message: mark it read or unread (seen), pin or unpin it (pinned, shown as flagged in mail apps), or move it to a folder (inbox, archive, junk, trash).
email_senddraft and sendSend a message from a mailbox's address.
email_create_draftdraft onlySave a message to a mailbox's Drafts without sending it, so a person can review and send it.
email_update_draftdraft onlyReplace a draft in a mailbox's Drafts with a new version.
email_get_sending_statusread onlyThe organization's outbound sending limits, how many outside recipients it sent to in the last hour and day, and any active suspensions (a mailbox, or mailboxId null for the whole organization) with the reason.
storage_list_attachmentsread onlyAttachments of the mail you can read, newest first, optionally for one mailbox, only "received" or "sent", or matching a name.
storage_get_attachmentread onlyGet one mail attachment: name, type, size, received or sent, its message and thread, and the mailbox.
storage_read_attachment_textread onlyRead the whole text of a mail attachment: a PDF up to 25 MB, or a text file (CSV, Markdown, plain text, JSON) up to 1 MB.
storage_attachment_download_urlread onlyA link that downloads a mail attachment for the next 5 minutes.

Calendar

Read, or Read and change.

ToolNeedsWhat it does
calendar_list_calendarsreadList a mailbox's calendars (id, name, isDefault, color), default first.
calendar_list_eventsreadList the events in a mailbox calendar between from and to (ISO date-times; at most 365 days apart), sorted by start.
calendar_get_eventreadGet one event, or one occurrence of a repeating event, by the id from calendar_list_events.
calendar_create_eventread and changeCreate an event in a mailbox calendar (the default calendar unless calendarId is given).
calendar_update_eventread and changeChange an event you organize.
calendar_delete_eventread and change (deletes)Delete an event, or with occurrence only that occurrence of a repeating event.
calendar_respond_to_eventread and changeAnswer an invitation in a mailbox calendar: accepted, tentative (maybe) or declined.
calendar_get_invitereadRead the calendar invitation in an email's text/calendar attachment (blobId from email_get_thread): method (request = an invite or update, reply = a guest answered, cancel), the event as the email describes it, your calendar's copy if it's there (existing), whether the email is newer than that copy (outdated), and for a reply who answered and how.
calendar_apply_inviteread and changeAct on the calendar invitation in an email.

Storage

Read, or Read and change.

ToolNeedsWhat it does
storage_listreadList the top of a Storage view.
storage_get_folderreadList a folder's contents (folders first), with the folder itself and the path to it.
storage_get_itemreadGet one file or folder: name, type, size, current version, owner, your role, and the path to it.
storage_create_folderread and changeCreate a folder inside parentId, or at the top of a space when parentId is left out: "personal" (My Files, private to you) or "organization" (a team folder everyone in the organization can view until you change it).
storage_update_itemread and changeRename a file or folder, or move it: parentId moves it into that folder; parentId null with space moves it to the top of My Files ("personal") or the team folders ("organization").
storage_trash_itemread and change (deletes)Move a file or folder (with everything inside) to the trash.
storage_restore_itemread and changeTake a file or folder out of the trash, back where it was.
storage_delete_itemread and change (deletes)Delete a trashed file or folder for good, with everything inside it.
storage_download_urlreadA link that downloads the file (or an earlier version) for the next 5 minutes.
storage_read_textreadRead a text file (CSV, Markdown, plain text, JSON) up to 1 MB, or the text of a PDF up to 25 MB.
storage_searchreadFind the passages that best answer a question, by meaning, across the files you can open (your My Files, the team folders and files shared with you; text, CSV, Markdown, JSON and PDF; any language) and the mail you can read (message bodies and attachments).
storage_write_textread and changeReplace a text file's contents, saved as a new version.
storage_create_text_fileread and changeCreate a text file (e.g.
storage_list_versionsreadA file's current version and the earlier ones still kept (the last 5, each for 30 days).
storage_restore_versionread and changeMake an earlier version current again.
storage_list_accessreadWho can open a file or folder: its owner, what everyone in the organization gets, people it is shared with, and what comes from folders above it.
storage_set_accessread and changeShare a file or folder (managers only).
storage_get_usagereadSize and file count of your My Files, the team folders and the mail attachments you can read, and how many items are in your trash.
storage_save_attachmentread and changeCopy a mail attachment into Storage so it can be edited and shared: into parentId, or the top of My Files.

Contacts

Read, or Read and change.

ToolNeedsWhat it does
audience_overviewreadSummary of the Users section: how many people there are, the website domains they came from (with counts), how many contacts and auto-saved "Other contacts" you have, and every saved segment with its filter and current member count.
audience_schemareadThe custom attribute names (with type) and event names seen so far, for building segment filters.
audience_suggest_contactsreadContacts whose name or email contains q, for addressing mail: your own and shared contacts first, then auto-saved "Other contacts".
audience_list_peoplereadList people (users and leads, including anonymous visitors), most recently seen first.
audience_get_personreadOne person's profile, the segments they're in, their latest 100 events (page views and custom events), and the latest 30 emails to or from their address in the mailboxes you can read (null if mail is unavailable).
audience_add_personread and changeAdd a person by hand: a lead on a website domain (email unique per domain), or a contact (kind "contact", no domain): your own, or shared with the whole organization when shared is true.
audience_update_personread and changeChange a person's name, email or phone, or set custom attributes (null removes one).
audience_delete_peopleread and change (deletes)Delete people and all their events for good (for example on a data deletion request).
audience_countreadCount how many people a segment filter matches, without saving it.
audience_create_segmentread and changeSave a segment: a name and a filter (see audience_count for the filter shape).
audience_update_segmentread and changeRename a segment or replace its filter.
audience_delete_segmentread and change (deletes)Delete a saved segment.

Setup

Only when an owner or admin turns on Manage domains and mailboxes.

ToolNeedsWhat it does
email_add_domainsetupAdd a domain the organization owns (e.g.
email_check_domainsetupCheck a domain before adding it: whether the name is valid, exists in public DNS, is already on xstate ("taken"), and which provider hosts its DNS (e.g.
email_list_domainssetupList the organization's domains that you can see.
email_get_domainsetupGet one domain: its name, verification status and whether mail is enabled.
email_get_dns_recordssetupGet the DNS records (MX, SPF, DKIM, DMARC, SRV, MTA-STS, autoconfig) the domain owner must add, as a zone file.
email_verify_domainsetupLook up the essential mail records (MX, SPF, DKIM, DMARC) in public DNS and report each as found or not.
email_domain_connect_urlsetupGet a one-click setup link (Domain Connect) that adds the domain's mail records at its DNS provider, e.g.
email_set_domain_enabledsetupTurn mail for a domain on or off.
email_remove_domainsetup (deletes)Remove a domain from xstate.
email_create_mailboxsetupCreate a mailbox on a domain.
email_update_mailboxsetupChange a mailbox's display name or storage quota in bytes (null removes the limit).
email_delete_mailboxsetup (deletes)Permanently delete a mailbox with all its mail and addresses.
email_add_aliassetupAdd an extra address to a mailbox, on any domain of the organization.
email_remove_aliassetup (deletes)Remove an alias address from a mailbox.
email_list_accesssetupList the members who can open a mailbox, and their access (owner or full).

For developers

  • Transport: Streamable HTTP at https://mcp.xstate.com/mcp. Stateless: no session is kept between requests.
  • Sign-in: OAuth 2.1 with PKCE (S256). xstate is its own authorization server. Discovery follows the MCP authorization spec: a request without a token gets 401 pointing to /.well-known/oauth-protected-resource/mcp, which names the authorization server, whose metadata is at /.well-known/oauth-authorization-server.
  • Client registration: Client ID Metadata Documents (preferred) or Dynamic Client Registration at /oauth/register.
  • Scopes: request none. The person picks them on the consent page, and the token carries what they chose.
  • Tokens: access tokens last one hour; refresh tokens rotate on use, and a connection ends 30 days after its last refresh.
  • Errors: a tool that fails returns isError with { "error": { "code", "message" } }, the same codes as the HTTP API. Over the rate limit the code is rate_limited.

On this page