MCP server

Let a coding agent manage a US Global Mail mailbox on the customer's behalf.

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 public 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 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.

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).

1{
2  "mcpServers": {
3    "usgm": {
4      "type": "http",
5      "url": "https://mcp.usglobalmail.com/mcp",
6      "headers": { "Authorization": "Bearer usgmk_live_…" }
7    }
8  }
9}

For Claude Code you can also run:

$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 }; pass next_cursor back as cursor to page.

ToolWhat it does
mails_list, mails_getList / fetch mail items (filters: folder, search, status, scan status)
mails_mark_readMark a mail item read / unread
mails_move_to_folderMove a mail item into a folder
mails_archive, mails_unarchiveArchive / restore mail
mails_discard, mails_undiscardRequest discard (shred) / undo — discard is destructive
folders_list, folders_getList / fetch folders
folders_create, folders_updateCreate / rename-recolor a folder
folders_deleteDelete a folder (mail inside is unfiled, not deleted) — destructive
scans_list, scans_getList / fetch scan (and open-and-scan) requests
scans_get_fileGet a short-lived signed download URL for a completed scan
scans_createRequest a scan of a mail item — billable
scans_cancelCancel a pending scan request
scans_deleteDelete a scan request — destructive
addresses_list, addresses_get, addresses_get_defaultList / fetch addresses; default per category
addresses_create, addresses_update, addresses_set_defaultCreate / update / set default (shipping, deposit)
addresses_deleteDelete an address — destructive
bank_accounts_list, bank_accounts_getList / fetch bank accounts (account number shown as last 4 only)
bank_accounts_create, bank_accounts_updateAdd / update a bank account (for check deposits)
bank_accounts_deleteDelete a bank account — destructive
shipments_list, shipments_getList / fetch shipment requests (read-only)
account_get, account_get_mailing_addressRead 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.