# EasyPost MCP Guide

EasyPost MCP connects AI assistants and agents to your EasyPost account. It is a hosted
[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server, so a client such as Claude Code, Cursor, or
VS Code can answer shipping questions in plain language using live account data. There is no integration code to write
and nothing to install.

Ask where a package is, what a shipment cost, or which carriers are connected, and the assistant reads the answer from
your shipments, trackers, carrier accounts, pickups, refunds, insurance, and claims.

**Server URL:** `https://app-api.easypost.com/mcp`

  **Production mode:** EasyPost MCP currently sends all EasyPost requests in production mode. Connect with a production
  API key; test API keys are not supported.

EasyPost MCP is an early release. Send setup issues, tool requests, or concerns to
[ai@easypost.com](mailto:ai@easypost.com).

---

## What You Can Do

Support and operations teams can answer shipping questions without opening the dashboard, and developers can inspect an
account without writing a script. These work on any EasyPost account with shipping history. Paste one into your
assistant after you connect:

- "Which carrier accounts are connected to my EasyPost account?"
- "List my shipments from the last seven days with carrier, service, and cost."
- "Which of my shipments from the past week are still in transit?"
- "Which USPS services can carry a package over 50 pounds?"
- "Do I have any open insurance claims, and what is the status of each?"
- "Show postage refund requests from the last 30 days."
- "Do I have any carrier pickups scheduled?"

You can also ask about one record: "Where is tracking number 9405511899223197428490?" or "Show me shipment
`shp_...`."

---

## Prerequisites

- An EasyPost account with production shipping data.
- A production API key.
- An MCP client that supports remote servers over Streamable HTTP with custom request headers.

---

## Step 1: Set a Production API Key

Sign in to the [EasyPost API Keys page](https://app.easypost.com/account/settings?tab=api-keys) and copy a production
key. Set it as `EASYPOST_API_KEY` in the environment that launches your MCP client.

[Content omitted: interactive code examples. Review the rendered documentation for request and response examples.]

[Content omitted: interactive code examples. Review the rendered documentation for request and response examples.]

Do not put the key in the server URL, source control, or an agent prompt.

---

## Step 2: Configure Your MCP Client

Choose the configuration for your client. Each example reads `EASYPOST_API_KEY` from the environment.

### Cursor

[Install EasyPost MCP in Cursor](https://cursor.com/en/install-mcp?name=easypost&config=eyJ1cmwiOiJodHRwczovL2FwcC1hcGkuZWFzeXBvc3QuY29tL21jcCIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciAke2VudjpFQVNZUE9TVF9BUElfS0VZfSJ9fQ%3D%3D),
or add the server manually to `~/.cursor/mcp.json` for all projects or `.cursor/mcp.json` for one project:

[Content omitted: interactive code examples. Review the rendered documentation for request and response examples.]

Restart Cursor after saving the file.

### Claude Code

Add the server with one command:

[Content omitted: interactive code examples. Review the rendered documentation for request and response examples.]

Use `--scope user` instead of `--scope project` to make the server available in every project.

The command writes `.mcp.json` in the project root. To add it by hand, the equivalent entry is:

[Content omitted: interactive code examples. Review the rendered documentation for request and response examples.]

Restart Claude Code, then run `claude mcp list` to check the connection.

### Codex

Add the server with the Codex CLI:

[Content omitted: interactive code examples. Review the rendered documentation for request and response examples.]

The equivalent `~/.codex/config.toml` entry is:

[Content omitted: interactive code examples. Review the rendered documentation for request and response examples.]

### VS Code

Add the server to your user or workspace MCP settings. VS Code prompts for the key and stores it outside the
configuration file:

[Content omitted: interactive code examples. Review the rendered documentation for request and response examples.]

### OpenAI Responses API

Pass the server and header on the `mcp` tool. The Responses API does not store the header, so send it with every
request:

[Content omitted: interactive code examples. Review the rendered documentation for request and response examples.]

### Other MCP Clients

Use these connection settings in any client that supports remote Streamable HTTP servers, including workflow
automation tools with a native MCP client step such as n8n:

| Setting | Value |
|---|---|
| Name | easypost |
| URL | https://app-api.easypost.com/mcp |
| Request header | Authorization: Bearer YOUR_EASYPOST_PRODUCTION_API_KEY |