> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.usglobalmail.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.usglobalmail.com/_mcp/server.

# MCP server

The USGM MCP server lets an AI coding agent (Claude Code, Cursor, VS Code, Windsurf, Cline, …) manage
a mailbox for you: read and organize scanned mail, manage folders, request scans, manage shipping and
deposit addresses and bank accounts, view shipment requests, and read the account profile and virtual
mailing address.

It's a thin, **stateless HTTP** wrapper around the US Global Mail API gateway — every tool call is forwarded to
the gateway with your API key, so the gateway enforces auth, rate limits, and audit exactly as it does
for direct REST calls. Nothing new to trust.

## Connecting

* **Endpoint:** `POST https://mcp.usglobalmail.com/mcp` — a
  [Streamable HTTP](https://modelcontextprotocol.io) MCP server.
* **Auth:** send your API key as a bearer token — `Authorization: Bearer usgmk_live_…` (use a
  `usgmk_test_…` key against the sandbox). It's the same key you use for direct REST calls.

> **Warning**
>
> Treat the key like a password — anything the agent can do, the key can do. Use a dedicated key per
> agent and rotate it if it leaks.

## Example agent configs

Replace `usgmk_live_…` with your key (use a `usgmk_test_…` key against the sandbox).

**`Claude Code (.mcp.json)`**

```json title="Claude Code (.mcp.json)"
{
  "mcpServers": {
    "usgm": {
      "type": "http",
      "url": "https://mcp.usglobalmail.com/mcp",
      "headers": { "Authorization": "Bearer usgmk_live_…" }
    }
  }
}
```

**`Cursor (.cursor/mcp.json)`**

```json title="Cursor (.cursor/mcp.json)"
{
  "mcpServers": {
    "usgm": {
      "url": "https://mcp.usglobalmail.com/mcp",
      "headers": { "Authorization": "Bearer usgmk_live_…" }
    }
  }
}
```

**`VS Code (.vscode/mcp.json)`**

```json title="VS Code (.vscode/mcp.json)"
{
  "inputs": [
    { "id": "usgm_key", "type": "promptString", "description": "USGM API key", "password": true }
  ],
  "servers": {
    "usgm": {
      "type": "http",
      "url": "https://mcp.usglobalmail.com/mcp",
      "headers": { "Authorization": "Bearer ${input:usgm_key}" }
    }
  }
}
```

For Claude Code you can also run:

```bash
claude mcp add --transport http usgm https://mcp.usglobalmail.com/mcp --header "Authorization: Bearer usgmk_live_…"
```

Windsurf, Cline, and other MCP clients follow the same shape: a remote HTTP server with a `url` and an
`Authorization` header.

## Tools

All list tools return `{ data, next_cursor, total_count }`; pass `next_cursor` back as `cursor` to page.

| Tool                                                            | What it does                                                            |
| --------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `mails_list`, `mails_get`                                       | List / fetch mail items (filters: folder, search, status, scan status)  |
| `mails_mark_read`                                               | Mark a mail item read / unread                                          |
| `mails_move_to_folder`                                          | Move a mail item into a folder                                          |
| `mails_archive`, `mails_unarchive`                              | Archive / restore mail                                                  |
| `mails_discard`, `mails_undiscard`                              | Request discard (shred) / undo — **discard is destructive**             |
| `folders_list`, `folders_get`                                   | List / fetch folders                                                    |
| `folders_create`, `folders_update`                              | Create / rename-recolor a folder                                        |
| `folders_delete`                                                | Delete a folder (mail inside is unfiled, not deleted) — **destructive** |
| `scans_list`, `scans_get`                                       | List / fetch scan (and open-and-scan) requests                          |
| `scans_get_file`                                                | Get a short-lived signed download URL for a completed scan              |
| `scans_create`                                                  | Request a scan of a mail item — **billable**                            |
| `scans_cancel`                                                  | Cancel a pending scan request                                           |
| `scans_delete`                                                  | Delete a scan request — **destructive**                                 |
| `addresses_list`, `addresses_get`, `addresses_get_default`      | List / fetch addresses; default per category                            |
| `addresses_create`, `addresses_update`, `addresses_set_default` | Create / update / set default (shipping, deposit)                       |
| `addresses_delete`                                              | Delete an address — **destructive**                                     |
| `bank_accounts_list`, `bank_accounts_get`                       | List / fetch bank accounts (account number shown as last 4 only)        |
| `bank_accounts_create`, `bank_accounts_update`                  | Add / update a bank account (for check deposits)                        |
| `bank_accounts_delete`                                          | Delete a bank account — **destructive**                                 |
| `shipments_list`, `shipments_get`                               | List / fetch shipment requests (read-only)                              |
| `account_get`, `account_get_mailing_address`                    | Read the account profile / virtual mailing address                      |

Destructive tools are annotated (`destructiveHint`) so agents ask before shredding mail or deleting a
folder, address, or bank account. Read-only tools are annotated `readOnlyHint`.

## Notes

* **Stateless:** no session affinity — any instance serves any request.
* **Auth today is API-key passthrough.** OAuth 2.1 (browser consent instead of a pasted key) and scoped
  keys are planned; until then, use a dedicated key per agent and rotate it if leaked.