# 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](#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

```bash
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

```bash
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):

```json
{
  "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](#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:

| Choice | Options | Starts on |
| - | - | - |
| Organization | Any you belong to | The first |
| Mailboxes | Mailboxes you can read | Your own mailbox |
| Email | Read only · Draft only · Draft and send | Draft only |
| Calendar, Storage, Contacts | Off · Read · Read and change | Read |
| Manage domains and mailboxes | Off or on, for owners and admins | Off |

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.

<!-- mcp-tools:start (generated by apps/api/scripts/mcp-tools-doc.ts; do not edit) -->

### Always

Every connection has these.

| Tool | Needs | What it does |
| - | - | - |
| `auth_me` | always | The signed-in user and the organizations they belong to, with their role and member id in each. |
| `members_list` | always | Everyone in the organization: name, email, role (owner, admin or member) and status (invited or active). |
| `storage_list_members` | always | People in the organization, with their member id, to share files with. |

### Email

Read only, Draft only or Draft and send.

| Tool | Needs | What it does |
| - | - | - |
| `email_list_mailboxes` | read only | List the mailboxes in the organization that you can see, optionally only one domain or kind. |
| `email_get_mailbox` | read only | Get one mailbox: its address, aliases, kind, display name and quota. |
| `email_list_folders` | read only | List 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_messages` | read only | List 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_search` | read only | Find 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_thread` | read only | Get every message in a conversation, oldest first, with plain-text and HTML bodies and attachment details (blobId, name, type, size). |
| `email_update_message` | draft only | Change 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_send` | draft and send | Send a message from a mailbox's address. |
| `email_create_draft` | draft only | Save a message to a mailbox's Drafts without sending it, so a person can review and send it. |
| `email_update_draft` | draft only | Replace a draft in a mailbox's Drafts with a new version. |
| `email_get_sending_status` | read only | The 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_attachments` | read only | Attachments of the mail you can read, newest first, optionally for one mailbox, only "received" or "sent", or matching a name. |
| `storage_get_attachment` | read only | Get one mail attachment: name, type, size, received or sent, its message and thread, and the mailbox. |
| `storage_read_attachment_text` | read only | Read 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_url` | read only | A link that downloads a mail attachment for the next 5 minutes. |

### Calendar

Read, or Read and change.

| Tool | Needs | What it does |
| - | - | - |
| `calendar_list_calendars` | read | List a mailbox's calendars (id, name, isDefault, color), default first. |
| `calendar_list_events` | read | List the events in a mailbox calendar between from and to (ISO date-times; at most 365 days apart), sorted by start. |
| `calendar_get_event` | read | Get one event, or one occurrence of a repeating event, by the id from calendar_list_events. |
| `calendar_create_event` | read and change | Create an event in a mailbox calendar (the default calendar unless calendarId is given). |
| `calendar_update_event` | read and change | Change an event you organize. |
| `calendar_delete_event` | read and change (deletes) | Delete an event, or with occurrence only that occurrence of a repeating event. |
| `calendar_respond_to_event` | read and change | Answer an invitation in a mailbox calendar: accepted, tentative (maybe) or declined. |
| `calendar_get_invite` | read | Read 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_invite` | read and change | Act on the calendar invitation in an email. |

### Storage

Read, or Read and change.

| Tool | Needs | What it does |
| - | - | - |
| `storage_list` | read | List the top of a Storage view. |
| `storage_get_folder` | read | List a folder's contents (folders first), with the folder itself and the path to it. |
| `storage_get_item` | read | Get one file or folder: name, type, size, current version, owner, your role, and the path to it. |
| `storage_create_folder` | read and change | Create 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_item` | read and change | Rename 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_item` | read and change (deletes) | Move a file or folder (with everything inside) to the trash. |
| `storage_restore_item` | read and change | Take a file or folder out of the trash, back where it was. |
| `storage_delete_item` | read and change (deletes) | Delete a trashed file or folder for good, with everything inside it. |
| `storage_download_url` | read | A link that downloads the file (or an earlier version) for the next 5 minutes. |
| `storage_read_text` | read | Read a text file (CSV, Markdown, plain text, JSON) up to 1 MB, or the text of a PDF up to 25 MB. |
| `storage_search` | read | Find 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_text` | read and change | Replace a text file's contents, saved as a new version. |
| `storage_create_text_file` | read and change | Create a text file (e.g. |
| `storage_list_versions` | read | A file's current version and the earlier ones still kept (the last 5, each for 30 days). |
| `storage_restore_version` | read and change | Make an earlier version current again. |
| `storage_list_access` | read | Who 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_access` | read and change | Share a file or folder (managers only). |
| `storage_get_usage` | read | Size 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_attachment` | read and change | Copy 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.

| Tool | Needs | What it does |
| - | - | - |
| `audience_overview` | read | Summary 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_schema` | read | The custom attribute names (with type) and event names seen so far, for building segment filters. |
| `audience_suggest_contacts` | read | Contacts whose name or email contains q, for addressing mail: your own and shared contacts first, then auto-saved "Other contacts". |
| `audience_list_people` | read | List people (users and leads, including anonymous visitors), most recently seen first. |
| `audience_get_person` | read | One 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_person` | read and change | Add 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_person` | read and change | Change a person's name, email or phone, or set custom attributes (null removes one). |
| `audience_delete_people` | read and change (deletes) | Delete people and all their events for good (for example on a data deletion request). |
| `audience_count` | read | Count how many people a segment filter matches, without saving it. |
| `audience_create_segment` | read and change | Save a segment: a name and a filter (see audience_count for the filter shape). |
| `audience_update_segment` | read and change | Rename a segment or replace its filter. |
| `audience_delete_segment` | read and change (deletes) | Delete a saved segment. |

### Setup

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

| Tool | Needs | What it does |
| - | - | - |
| `email_add_domain` | setup | Add a domain the organization owns (e.g. |
| `email_check_domain` | setup | Check 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_domains` | setup | List the organization's domains that you can see. |
| `email_get_domain` | setup | Get one domain: its name, verification status and whether mail is enabled. |
| `email_get_dns_records` | setup | Get the DNS records (MX, SPF, DKIM, DMARC, SRV, MTA-STS, autoconfig) the domain owner must add, as a zone file. |
| `email_verify_domain` | setup | Look up the essential mail records (MX, SPF, DKIM, DMARC) in public DNS and report each as found or not. |
| `email_domain_connect_url` | setup | Get a one-click setup link (Domain Connect) that adds the domain's mail records at its DNS provider, e.g. |
| `email_set_domain_enabled` | setup | Turn mail for a domain on or off. |
| `email_remove_domain` | setup (deletes) | Remove a domain from xstate. |
| `email_create_mailbox` | setup | Create a mailbox on a domain. |
| `email_update_mailbox` | setup | Change a mailbox's display name or storage quota in bytes (null removes the limit). |
| `email_delete_mailbox` | setup (deletes) | Permanently delete a mailbox with all its mail and addresses. |
| `email_add_alias` | setup | Add an extra address to a mailbox, on any domain of the organization. |
| `email_remove_alias` | setup (deletes) | Remove an alias address from a mailbox. |
| `email_list_access` | setup | List the members who can open a mailbox, and their access (owner or full). |

<!-- mcp-tools:end -->


## 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`.
