Overview

This article shows you how to connect Claude, Cursor, VS Code, or another AI app to your US Global Mail mailbox, what your assistant can do once it is connected, and how to keep that access safe. It is written for account owners on a plan that includes API access.

The US Global Mail MCP server connects AI apps to your mailbox. Model Context Protocol (MCP) is an open standard that lets AI apps use outside tools. Once connected, you ask about your mail in plain language and your assistant reads it, files it, requests scans, and keeps your addresses up to date for you.

The server address is https://mcp.usglobalmail.com/mcp. It requires an API key from your US Global Mail account. An API key is a code, like a password, that lets one app act on your account. Everything your assistant does runs through the US Global Mail API under your account, with the same permissions, rate limits, and audit log.

Who can use it. Your plan must include API access. Plans that include it list API & webhooks on their plan card. On other plans, Settings → Developer → API Keys shows an upgrade banner instead.

What your assistant can do

The table below lists what your assistant can do in each part of your mailbox once it is connected.

Your mailbox	What your assistant can do
Mail	List and search your mail, see who sent it and who it is for, mark it read or unread, move it into folders, archive it, and request shredding
Scans	See your scan requests, request a scan of a letter, cancel a pending request, read the AI summary of a completed scan, and get a download link for the PDF
Folders	Create, rename, recolor, and delete folders
Addresses	Add and update your shipping and check-deposit addresses, and choose the defaults
Bank accounts	Add and update the accounts you deposit checks into. Your assistant only ever sees the last four digits
Shipments	See your shipment requests and their status. Creating a shipment is not available through the assistant yet
Account	Read your account details and your US mailing address

AI summaries of scans are available on plans that include them.

It asks before it acts. Actions that are hard to undo or that cost money are marked for the assistant, so your assistant asks you to confirm before it requests shredding, deletes a folder, address, bank account, or scan request, or orders a scan that is billed to your plan.

See the example prompts below for ideas on what to ask.

Get your API key

To get your API key, create one on the API Keys page in your account settings. You will paste this key into your AI app in the next section.

Sign in to US Global Mail and go to Settings → Developer → API Keys.
Click Add API Key, name it after the app you are connecting, such as Claude, and click Add.
In the Your New API Key window, click the copy button and store the key somewhere safe. It starts with usgmk_live_ and is shown only once. If you lose it, choose Rotate key to get a new one.

Keep your key safe. The key can do everything you can do in your account. Treat it like a password, and never paste it into a chat message. Use one key per app so you can revoke one without affecting the others.

Connect your AI app

To connect your AI app, find it below and follow its steps. In every example, replace YOUR_API_KEY with the key you copied.

Claude on the web and Claude Desktop

Claude connects through a custom connector. You add it once in your Claude account, and it is then available in Claude on the web and in Claude Desktop. Custom connectors are available on every Claude plan, and the Free plan allows one.

In Claude, go to Customize → Connectors, click Add, and choose Add custom connector.
Enter US Global Mail as the name and https://mcp.usglobalmail.com/mcp as the remote MCP server URL, then click Continue.
Claude checks the server and preselects No sign-in, marked Detected. Leave it selected.
Under Request headers, click Add header. Enter Authorization as the name and Bearer YOUR_API_KEY as the value, with the word Bearer and a space before the key.
Click Add.

In a chat, click the + button at the lower left of the message box and switch on US Global Mail. On a Team or Enterprise plan an Owner adds the connector under Organization settings → Connectors, and each member then opens Customize → Connectors and clicks Connect.

Claude Desktop, local setup

If you added the connector above, it is already available in Claude Desktop. Use this local setup instead only if you prefer to keep the key on your own computer. It runs mcp-remote, a small open-source bridge, so you need Node.js installed.

Open the Claude Desktop config file. In Claude Desktop, Settings → Developer → Edit Config opens the folder that contains it:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add US Global Mail to the mcpServers block:

{
  "mcpServers": {
    "usgm": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.usglobalmail.com/mcp",
        "--header",
        "Authorization:${USGM_AUTH}"
      ],
      "env": { "USGM_AUTH": "Bearer YOUR_API_KEY" }
    }
  }
}

Save the file, then quit and reopen Claude Desktop. US Global Mail now appears in the tools menu of the chat box. The first start can take up to a minute while the bridge downloads.

Claude Code

Claude Code connects with one command. Run this in your terminal:

claude mcp add --transport http usgm \
  https://mcp.usglobalmail.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

On Windows PowerShell, type the command on one line without the backslashes.

Inside Claude Code, type /mcp. The list shows usgm as connected.

Cursor

Cursor reads its MCP servers from a JSON file. Add this to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for all projects:

{
  "mcpServers": {
    "usgm": {
      "url": "https://mcp.usglobalmail.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Cursor's MCP settings now list usgm with its tools.

VS Code

VS Code asks for the key the first time you start the server and stores it for you, so the key never sits in the file. Add this to .vscode/mcp.json:

{
  "inputs": [
    {
      "id": "usgm_key",
      "type": "promptString",
      "description": "US Global Mail API key",
      "password": true
    }
  ],
  "servers": {
    "usgm": {
      "type": "http",
      "url": "https://mcp.usglobalmail.com/mcp",
      "headers": { "Authorization": "Bearer ${input:usgm_key}" }
    }
  }
}

When you start the server, VS Code prompts for the key, then lists the US Global Mail tools in agent mode.

Other AI apps

Any app that supports remote MCP servers over Streamable HTTP can connect with these details:

URL: https://mcp.usglobalmail.com/mcp
Transport: Streamable HTTP
Header: Authorization: Bearer YOUR_API_KEY

These tools accept that shape in their own config file: Codex CLI (http_headers in config.toml), Gemini CLI (httpUrl plus headers), Cline (url, type set to streamableHttp, plus headers), and Windsurf (serverUrl plus headers). An app that cannot send a custom header cannot connect yet.

Example prompts

Once connected, ask about your mail the way you would ask an assistant. The prompts below all work with the connection described above.

"What mail arrived this week, and who sent it?"
"Which of my mail is still unread?"
"Show me everything from the IRS."
"Which scans are ready, and what do they say?"
"Request a scan of the letter from Chase." Your assistant asks you to confirm before it orders the scan.
"Move the letters from the IRS into my Taxes folder."
"Mark the mail from Amazon as read."
"What is the status of my latest shipment?"
"Which shipping addresses do I have on file?"
"What is my US mailing address? Format it for a bank form."

Keys and safety

Every key has the same access as you do. You manage your keys on the API Keys page, and the Audit Logs page shows everything your assistant did.

One key per app. Name each key after the app that uses it. You can then see which apps are active and revoke one without breaking the others.
Revoke or rotate. Go to Settings → Developer → API Keys, open the menu next to the key, and choose Revoke key or Rotate key. A revoked or rotated key stops working immediately.
See what your assistant did. Settings → Developer → Audit Logs lists every change made through the API, with the key that made it.
Keep tool approval on. Most AI apps can ask you before each tool runs. Leave that on for US Global Mail, at least until you trust the assistant with your mail.
Know where your mail goes. Whatever your assistant reads, including scan summaries, is sent to the AI app you connected and handled under that app's privacy terms.

Try it in the sandbox first

To try the connection without touching your real mail, use the sandbox. It is a separate test account with its own key, and nothing in it is billed or physically mailed. Go to Settings → Developer → API Keys, scroll to Sandbox, and click Activate Sandbox. You get a test key that starts with usgmk_test_.

Connect your AI app exactly as described above, with the test key in place of your live key. The server address stays the same; the key decides which mailbox your assistant sees. The sandbox starts empty, and the Sandbox guide in the developer docs shows how to add sample mail.

Troubleshooting

The table below lists the problems people run into when connecting, and what fixes each one.

Problem	Fix
Your assistant connects, but every action fails with "Gateway error 401"	The key is missing or mistyped. Check that the header value starts with `Bearer` and a space, and that the key has not been revoked.
Actions fail with "Gateway error 403"	Your plan does not include API access, or your subscription is not active. The error message says which. Settings → Developer → API Keys shows an upgrade banner when the plan is the reason.
US Global Mail does not appear in your app	In Claude, click the + button in the message box and switch the connector on. In Claude Code run `/mcp`. For the local Claude Desktop setup, restart the app after editing the config file, check that Node.js is installed, and give the first start up to 1 minute.
The connection fails on a work computer or office network	Some companies block outside MCP servers. Ask your IT team to allow `mcp.usglobalmail.com`.
Your assistant says it is being rate limited	It sent too many requests in a short time. Wait 1 minute and try again.
Your assistant sees an empty mailbox	Your app is using a sandbox key, which only sees the sandbox. Use your live key, the one that starts with `usgmk_live_`, for your real mail.
Your assistant keeps asking you to confirm	That is by design for shredding, deleting, and paid scans. Confirm or decline each time.

Frequently asked questions

Does using the MCP server cost extra?

No, using the MCP server costs nothing extra. API access is part of your plan. A scan your assistant requests is billed exactly as if you had requested it in the app.

Can my team members connect their own AI app?

Team members who see Developer in their Settings can create their own API key and connect an AI app. Team members who do not see it cannot, and should ask the account owner.

Can I limit what my assistant is allowed to do?

You cannot limit a key yet. A key has the same access as you do. What you can do today is keep tool approval on in your AI app, test in the sandbox, and revoke the key at any time.

Does my assistant see the contents of my scans?

Your assistant can read the AI summary of a completed scan and ask for a download link to the PDF. Whether it opens the PDF depends on the AI app you use. Whatever it reads is sent to that app.

Which AI apps work with US Global Mail?

The apps that work with US Global Mail are Claude on the web, Claude Desktop, Claude Code, Cursor, VS Code, Codex CLI, Gemini CLI, Cline, Windsurf, and any other app that supports remote MCP servers with a custom header. ChatGPT does not work yet, because its connectors cannot send an API key.

For developers

The MCP server is a thin layer over the US Global Mail API. The full tool list and the raw configuration live on the MCP server page in the developer docs. If you build on the API, the US Global Mail API article covers the SDKs and webhooks.

Connect US Global Mail to AI apps using MCP