# USA Logistics MCP 🇺🇸 — How can my AI agent buy a USPS / UPS / FedEx shipping label?

<!-- install-cta -->
## Use it in 60 seconds

Paste this into your MCP client config (Claude Desktop, Cursor, Windsurf, or any MCP-capable agent):

```json
{
  "mcpServers": {
    "usa-logistics": {
      "type": "http",
      "url": "https://logi-us.wishpool.app/mcp"
    }
  }
}
```

Nothing to install. Credentials, when you need them, travel as HTTP headers on each request and are never stored — see the [threat model](https://mcp.wishpool.app/trust).

### Or run it yourself

Would you rather not send production credentials to a server you do not control? Deploy this identical code to your own account and point your agent at your own URL:

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/junter1989k-ai/usa-logistics-mcp)

```bash
git clone https://github.com/junter1989k-ai/usa-logistics-mcp && cd usa-logistics-mcp && npx vercel --prod
```

MIT-licensed. Self-hosting removes us from the picture entirely, at no cost and with no loss of function.

---

Remote MCP server that lets any AI agent buy **US shipping labels** — USPS, UPS, FedEx and more — with automatic **cheapest-rate selection**, track parcels, and refund unused labels via the [EasyPost](https://www.easypost.com/) shipping API. Stateless, bring-your-own API key, never stores anything. **Free EasyPost test keys** give zero-cost end-to-end labels.

**Live endpoint:** `https://logi-us.wishpool.app/mcp` · Registry: `app.wishpool/usa-logistics-mcp`

## Quick start

```json
{
  "mcpServers": {
    "usa-logistics": {
      "type": "http",
      "url": "https://logi-us.wishpool.app/mcp",
      "headers": {
        "x-easypost-api-key": "EZTK_your_test_or_EZAK_prod_key"
      }
    }
  }
}
```

**No shared demo — but test keys are free.** EasyPost issues free **TEST** keys (prefix `EZTK…`) that buy real USPS test labels end-to-end at no cost: sign up at [easypost.com](https://www.easypost.com/) → API Keys. Production keys (prefix `EZAK…`) buy real postage. The same server auto-selects the environment from the key prefix.

## Tools

| Tool | What it does |
|---|---|
| `create_shipment` | Buy a US label. `to_*` + `from_*` address fields, parcel `weight` (ounces, required) and either `length`/`width`/`height` (inches) or `predefined_package`. Optional `carrier`/`service` restrict the choice — default is the **cheapest** rate across all enabled carriers. Fetches rates, buys the chosen rate, returns `shipment_id`, `tracking_code`, printable `label_url`, `carrier`, `service` and the `rate` (USD). |
| `query_tracking` | Track by `tracking_code` (+ optional `carrier` hint). Returns `status` from the EasyPost enum — `unknown` / `pre_transit` / `in_transit` / `out_for_delivery` / `delivered` / `available_for_pickup` / `return_to_sender` / `failure` / `cancelled` / `error` — plus a plain-English hint; non-terminal statuses carry `next_steps`. Raw carrier scans always included. |
| `refund_label` | Refund an **unused** label by `shipment_id` (preferred) or `tracking_code` (+`carrier`, default USPS). Returns `refund_status`: `submitted` / `refunded` / `rejected` / `not_applicable`. USPS: within 30 days of creation **and only if never scanned** — an already-shipped label cannot be refunded. |

Owner policy guardrails ride optional headers (`x-agentpay-max-amount`, `x-agentpay-approval-above`, `x-agentpay-allowed-tools`) — set by the human owner in client config; the agent cannot relax them. The **label price is gated before any purchase**: `approval-above` returns an unsigned draft with the shipment/rates prepared but no label bought.

## Develop

```bash
node test/serve.js   # local server on :3236 (/mcp)
node test/e2e.js     # protocol + validation + policy/easypost units + fake-key live probe to api.easypost.com (expects native 401)
```

## How it talks to EasyPost

`create_shipment` is two server-to-server REST calls: `POST /v2/shipments` (to/from address + parcel → `rates[]`) then `POST /v2/shipments/{id}/buy` (chosen rate → `postage_label.label_url` + `tracking_code`). `query_tracking` is `POST /v2/trackers` (by `tracking_code`). `refund_label` is `POST /v2/shipments/{id}/refund` (or `POST /v2/refunds` by `carrier` + `tracking_codes`). Auth is HTTP Basic with the API key as username and an empty password; the key prefix (`EZTK…` / `EZAK…`) selects test vs production on the same base URL `https://api.easypost.com`.

## Safety

Pure stateless translation layer. The label is generated and served by EasyPost/the carrier; the EasyPost API key travels per-request in a header, nothing is stored. Parcels flow sender ↔ carrier ↔ recipient directly. [Privacy policy](https://logi-us.wishpool.app/privacy).

## Sister servers

Taiwan CVS pickup + home delivery live in [taiwan-logistics-mcp](https://logi-tw.wishpool.app). One family of stateless BYO local-commerce MCP servers: local payments in 81 countries at [mcp.wishpool.app](https://mcp.wishpool.app), plus electronic-invoice servers across nine countries including Mexico CFDI, Brazil NF-e, Chile DTE, Peru CPE and India GST.

MIT licensed.