# Public MCP Documentation

> Connect your AI assistant to Virtual Mail via MCP — authentication, capabilities, and limitations.

Web page: https://reference.earthclassmail.com/v2/mcp/

Connect your AI assistant to Virtual Mail and manage your virtual mailbox just
by asking — find mail, organize your inbox, scan or shred items, and more —
directly from Claude, Cursor, and other MCP-compatible apps.

If any difficulties arise, please email
[api@earthclassmail.com](mailto:api@earthclassmail.com) with your questions.

## What it does

Virtual Mail's MCP server connects your AI assistant directly to your virtual
mailbox, so it can find, read, and act on your mail on your behalf — all within
your own Virtual Mail account and permissions. Instead of logging in and clicking
through the app, you just ask.

For example, you can ask your assistant to "find the letter from the IRS and
tell me what it says," and it will locate the item, pull its scanned text, and
summarize it for you. You can also have it take real actions on your behalf: scan
or shred a piece of mail, apply tags or move it to a different folder. And it
can simply tell you what needs your attention this week, without changing
anything.

## What you can do

**Find and read your mail** — ask what arrived this week, search for a specific
sender, or have the assistant read and summarize a scanned letter for you.

**Check your inbox at a glance** — get a quick overview of how many items are
waiting, what's unread, whether anything needs attention, and how your account
is doing.

**Organize your mailbox** — mark items as read, move mail to folders or the
archive, apply tags, or reassign a piece to a different recipient on a shared
inbox.

**Scan and shred** — request that physical mail be opened and scanned so you can
read it digitally, then optionally shred the original. Cancel a pending scan if
you change your mind, or a pending shred within the 7-day grace period.

**Track shipments and deposits** — check whether a forwarded package has shipped,
see its tracking info, or find out the status of a check deposit.

**Look up references** — ask what a status code or flag means (e.g. what
"SCAN_THRESHOLD_EXCEEDED" means) without leaving your conversation.

## Authentication

You can connect in one of two ways: sign in with OAuth (recommended, if your
client supports it), or use an API key you generate yourself. Both reach every
mailbox your user account is authorized for; they add no new access.

### OAuth Dynamic Client Registration

If your AI client supports OAuth, you can connect by signing in to LegalZoom in
your browser instead of managing an API key. The client obtains a short-lived
access token and refreshes it for you, so there's no long-lived key to store or
leak. This is the more secure option; use it whenever your client supports
OAuth. If it doesn't, use an API key below.

You don't register an application or manage a client ID or secret. The server
publishes its OAuth configuration, and a compliant client discovers it and
registers itself automatically (Dynamic Client Registration). You only add the
server URL, without an API key, and approve the sign-in prompt.

**How to connect:**

1. Add the server to your client (see [Other MCP clients](https://reference.earthclassmail.com/_llms_txt/v2/mcp/connect.md)), using the
   OAuth option and leaving out the API key.
2. The first time you use it, your client opens a LegalZoom sign-in page in your
   browser.
3. Sign in and approve the access your client is requesting.
4. That's it. Your client is connected and refreshes your session on its own.

**Token expiration:** you'll need to sign in again at least every 30 days, even
if you use the MCP server daily, and whenever you revoke access or reset your
client. API keys don't expire this way.

### API key

The MCP server can use an **API key** that you generate yourself. You only need
one key: the same key works for the MCP server and the Public API.

Your API key is tied to your user account, so it can reach every mailbox you
have access to. Keep it private, treat it like a password, and don't commit it
to source control. Regenerating the key invalidates the existing one.

**Generate your API key in the Virtual Mail web application:**

1. Sign in and go to **Settings** → **Integrations**.
2. Find the **Custom API integration** section.
3. In the **API Key** card, click **Generate Key** (invalidates any previously
   generated key).
4. Your key appears — click **Copy**.

You can also generate your API key in the Virtual Mail mobile app.

## Capabilities and limitations

### What the assistant can access

Scoped to your Virtual Mail account, the assistant can access and use available
account information and tools to help manage mail, inbox, shipment, deposit, and
related account activity. It can only reach mailboxes and data your own user
account is authorized to access. The MCP server reuses Virtual Mail's existing
authorization, adding no new access.

### Read and write tools

The toolset includes both read-only tools and write tools that take real action:
marking mail read/unread, moving/archiving/trashing, tagging, transferring
recipients, requesting scans, shredding (irreversible once carried out; a pending shred can
be cancelled within the 7-day grace period). Every tool the server
exposes carries a standard MCP annotation (`readOnlyHint` / `destructiveHint`)
that your AI client reads to tell read-only tools apart from ones that change
your mailbox.

> **Caution**
>
> The server does not add its own confirmation step; it executes any authorized
> request your AI client sends. Reviewing and approving an action (especially
> shred) is the responsibility of your MCP client/agent. Use a
> client that prompts before write actions, and review before approving.

### What the assistant cannot do

- **No shipping or deposits** — it can track existing shipments and check
  deposits, but it cannot ship mail, get shipping rates, or request a check
  deposit. To ship mail or deposit checks programmatically, use the
  [Public API](https://reference.earthclassmail.com/_llms_txt/v1/rest-api.md), or use the Virtual Mail app.
- **No entity management** — it cannot create, modify, or delete shipping
  addresses, bank accounts, recipients, or folders. It can only reference ones
  that already exist (e.g. move mail to an existing folder, transfer it to an
  existing recipient).
- **No billing or payment changes** — it cannot edit payment methods or plans.
  (Account standing and usage counts are read-only, and usage summaries are
  limited to account admins.)
- **No access beyond your permissions** — it cannot reach mailboxes, accounts,
  or actions your user isn't authorized for in Virtual Mail.

### Authentication & key scope

If you connect with an API key, access uses a single personal key tied to your
user account, so it can reach every mailbox you have access to. Treat it like a
password. To revoke a key, regenerate it at any time from **Settings** →
**Integrations**, which invalidates the old key. (This does not apply to OAuth
connections, which use a browser sign-in instead of a key.)

### Usage limits

Requests are rate-limited per client IP — **300 requests/minute** (subject to
change). Exceeding the limit results in throttled requests.