# Other MCP clients

> Connect your AI client to the Virtual Mail MCP server — setup snippets for Claude Code, Codex, Cursor, and VS Code.

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

> **Tip**
>
> Using the ChatGPT or Claude app? Install Virtual Mail from their directory
> instead — see
> [ChatGPT](https://reference.earthclassmail.com/_llms_txt/v2/mcp/chatgpt.md) or [Claude](https://reference.earthclassmail.com/_llms_txt/v2/mcp/claude.md).

Add the server to your AI client using the snippet for your app below. Each app
has two options — pick one:

- **OAuth** (recommended): leave the API key out. On first use your client opens
  a LegalZoom sign-in page in your browser (see
  [Authentication](https://reference.earthclassmail.com/_llms_txt/v2/mcp.md#authentication)). Use this if your client supports
  OAuth.
- **API key**: paste the key you generated wherever you see `[YOUR_API_KEY]`.
  Use this if your client doesn't support OAuth, or for unattended agents.

## Available servers

| Server | URL |
|---|---|
| All tools | `https://api.earthclassmail.com/v2/mcp` |
| Read-only tools | `https://api.earthclassmail.com/v2/mcp/readonly` |

## Tool catalog

Machine-readable descriptions of every tool the server exposes, useful for
agents and automated discovery:

| Format | URL |
|---|---|
| Plain text | [`mcp_catalog.txt`](https://api.earthclassmail.com/v2/mcp_catalog.txt) |
| JSON | [`mcp_catalog.json`](https://api.earthclassmail.com/v2/mcp_catalog.json) |

## Read-only access

Read-only access limits your connection to tools that can view mail — finding,
listing, and reading message text. Tools that take action (scanning, shredding,
moving, tagging, transferring) are not available.

You can enable read-only access in either of two ways:

- **Use the read-only URL** — connect to `.../v2/mcp/readonly`. Works if your
  client only lets you configure a URL, or if you want a connection that can
  never be switched to full access.
- **Use the read-only header** — keep the standard URL and add the header
  `X-MCP-ReadOnly: true`. Works if your client supports custom headers and you
  prefer a single URL.

## Client setup

### Claude Code

#### With OAuth

**All tools:**

```sh
claude mcp add --transport http virtual-mail https://api.earthclassmail.com/v2/mcp
```

**Read-only (via URL):**

```sh
claude mcp add --transport http virtual-mail https://api.earthclassmail.com/v2/mcp/readonly
```

**Read-only (via header):**

```sh
claude mcp add --transport http virtual-mail https://api.earthclassmail.com/v2/mcp --header "X-MCP-ReadOnly: true"
```

#### With an API key

**All tools:**

```sh
claude mcp add --transport http virtual-mail https://api.earthclassmail.com/v2/mcp --header "Authorization: Bearer [YOUR_API_KEY]"
```

**Read-only (via URL):**

```sh
claude mcp add --transport http virtual-mail https://api.earthclassmail.com/v2/mcp/readonly --header "Authorization: Bearer [YOUR_API_KEY]"
```

**Read-only (via header):**

```sh
claude mcp add --transport http virtual-mail https://api.earthclassmail.com/v2/mcp --header "Authorization: Bearer [YOUR_API_KEY]" --header "X-MCP-ReadOnly: true"
```

### Codex

#### With OAuth

**All tools:**

```sh
codex mcp add virtual-mail --url https://api.earthclassmail.com/v2/mcp
```

**Read-only (via URL):**

```sh
codex mcp add virtual-mail --url https://api.earthclassmail.com/v2/mcp/readonly
```

**Read-only (via header)** — add to `~/.codex/config.toml`:

```toml
[mcp_servers.virtual-mail]
enabled = true
transport = "streamable_http"
url = "https://api.earthclassmail.com/v2/mcp"
http_headers = { "X-MCP-ReadOnly" = "true" }
```

Then authenticate:

```sh
codex mcp login virtual-mail
```

#### With an API key

**All tools:**

```sh
export VIRTUAL_MAIL_API_KEY="[YOUR_API_KEY]"
codex mcp add virtual-mail \
  --url https://api.earthclassmail.com/v2/mcp \
  --bearer-token-env-var VIRTUAL_MAIL_API_KEY
```

**Read-only (via URL):**

```sh
export VIRTUAL_MAIL_API_KEY="[YOUR_API_KEY]"
codex mcp add virtual-mail \
  --url https://api.earthclassmail.com/v2/mcp/readonly \
  --bearer-token-env-var VIRTUAL_MAIL_API_KEY
```

**Read-only (via header)** — add to `~/.codex/config.toml`:

```toml
[mcp_servers.virtual-mail]
enabled = true
transport = "streamable_http"
url = "https://api.earthclassmail.com/v2/mcp"
bearer_token_env_var = "VIRTUAL_MAIL_API_KEY"
http_headers = { "X-MCP-ReadOnly" = "true" }
```

Then set the environment variable:

```sh
export VIRTUAL_MAIL_API_KEY="[YOUR_API_KEY]"
```

### Cursor

Add to `~/.cursor/mcp.json`.

#### With OAuth

**All tools:**

```json
{
  "mcpServers": {
    "virtual-mail": {
      "url": "https://api.earthclassmail.com/v2/mcp"
    }
  }
}
```

**Read-only (via URL):**

```json
{
  "mcpServers": {
    "virtual-mail": {
      "url": "https://api.earthclassmail.com/v2/mcp/readonly"
    }
  }
}
```

**Read-only (via header):**

```json
{
  "mcpServers": {
    "virtual-mail": {
      "url": "https://api.earthclassmail.com/v2/mcp",
      "headers": { "X-MCP-ReadOnly": "true" }
    }
  }
}
```

#### With an API key

**All tools:**

```json
{
  "mcpServers": {
    "virtual-mail": {
      "url": "https://api.earthclassmail.com/v2/mcp",
      "headers": { "Authorization": "Bearer [YOUR_API_KEY]" }
    }
  }
}
```

**Read-only (via URL):**

```json
{
  "mcpServers": {
    "virtual-mail": {
      "url": "https://api.earthclassmail.com/v2/mcp/readonly",
      "headers": { "Authorization": "Bearer [YOUR_API_KEY]" }
    }
  }
}
```

**Read-only (via header):**

```json
{
  "mcpServers": {
    "virtual-mail": {
      "url": "https://api.earthclassmail.com/v2/mcp",
      "headers": {
        "Authorization": "Bearer [YOUR_API_KEY]",
        "X-MCP-ReadOnly": "true"
      }
    }
  }
}
```

### VS Code

Add to `.vscode/mcp.json`.

#### With OAuth

**All tools:**

```json
{
  "servers": {
    "virtual-mail": {
      "type": "http",
      "url": "https://api.earthclassmail.com/v2/mcp"
    }
  }
}
```

**Read-only (via URL):**

```json
{
  "servers": {
    "virtual-mail": {
      "type": "http",
      "url": "https://api.earthclassmail.com/v2/mcp/readonly"
    }
  }
}
```

**Read-only (via header):**

```json
{
  "servers": {
    "virtual-mail": {
      "type": "http",
      "url": "https://api.earthclassmail.com/v2/mcp",
      "headers": { "X-MCP-ReadOnly": "true" }
    }
  }
}
```

#### With an API key

**All tools:**

```json
{
  "servers": {
    "virtual-mail": {
      "type": "http",
      "url": "https://api.earthclassmail.com/v2/mcp",
      "headers": { "Authorization": "Bearer [YOUR_API_KEY]" }
    }
  }
}
```

**Read-only (via URL):**

```json
{
  "servers": {
    "virtual-mail": {
      "type": "http",
      "url": "https://api.earthclassmail.com/v2/mcp/readonly",
      "headers": { "Authorization": "Bearer [YOUR_API_KEY]" }
    }
  }
}
```

**Read-only (via header):**

```json
{
  "servers": {
    "virtual-mail": {
      "type": "http",
      "url": "https://api.earthclassmail.com/v2/mcp",
      "headers": {
        "Authorization": "Bearer [YOUR_API_KEY]",
        "X-MCP-ReadOnly": "true"
      }
    }
  }
}
```