AI Agents (MCP)

RocketShipIt includes a Model Context Protocol (MCP) server. With it an AI agent such as Claude, Cursor or your own agent can rate, ship, track and void with every carrier RocketShipIt supports. The agent uses the same request format as the RocketShipIt API.

You can run the MCP server in two ways:

On your own computer or server: rocketshipit -mcp speaks MCP over stdio. Your carrier credentials stay on your machine.
Over HTTP: a self-hosted server (rocketshipit -s) serves MCP at /mcp. The Cloud API serves it at https://api.rocketship.it/v1/mcp.

Tools#

Tool	What it does
`list_carriers`	Lists the carriers, the actions each one has examples for, and which carriers have credentials configured.
`get_examples`	Returns working example params for a carrier and action. It also lists the credentials the carrier needs and the environment variable or header that supplies each one.
`shipping_request`	Runs one action on one carrier, for example `getallrates`, `submitshipment`, `track` or `voidshipment`.

Credentials#

Carrier credentials never go through the AI model. The model leaves them out of its requests, and RocketShipIt adds them before it calls the carrier.

stdio reads the same RS_<CARRIER>_<PARAM> environment variables as the rest of RocketShipIt, for example RS_ESTES_KEY or RS_FEDEX_REST_CLIENT_ID. See Command line options.
HTTP reads X-RS-<CARRIER>-<PARAM> request headers, for example X-RS-ESTES-KEY. A self-hosted server also falls back to its own environment variables.

Ask the agent "which credentials does Estes need?" and it will call get_examples to tell you the exact names.

Purchases need approval#

Some actions buy postage or change a live shipment: submitshipment, purchasepostage, createpickup, cancelpickup, voidshipment, createmanifest and deliveryintercept. The agent must send confirm: true with these actions, and it is told to get your approval first. Requests with "test": true go to the carrier's test environment and do not need confirm.

Labels#

Labels and other documents are not returned as base64 text, because that would fill the model's context.

stdio saves them to a folder and gives the agent the file path. The default folder is rocketshipit-labels in the system temp directory. Change it with -mcp-label-dir. Use -mcp-label-dir="" to attach the documents to the tool result instead.
HTTP attaches them to the tool result. PNG and GIF labels come back as images, and PDF and ZPL labels as embedded resources.

Claude Code#

Run on your own machine:

claude mcp add rocketshipit \
  -e RS_ESTES_KEY=your-key \
  -e RS_ESTES_USERNAME=your-username \
  -e RS_ESTES_PASSWORD=your-password \
  -e RS_ESTES_ACCOUNT_NUMBER=your-account \
  -- /path/to/rocketshipit -mcp

Use the Cloud API:

claude mcp add --transport http rocketshipit https://api.rocketship.it/v1/mcp \
  --header "x-api-key: YOUR_RS_API_KEY" \
  --header "X-RS-ESTES-KEY: your-key"

Claude Desktop#

Add RocketShipIt to claude_desktop_config.json. The license.lic file must be in the same folder as the rocketshipit binary.

{
  "mcpServers": {
    "rocketshipit": {
      "command": "/path/to/rocketshipit",
      "args": ["-mcp"],
      "env": {
        "RS_FEDEX_REST_CLIENT_ID": "your-client-id",
        "RS_FEDEX_REST_CLIENT_SECRET": "your-client-secret",
        "RS_FEDEX_REST_ACCOUNT_NUMBER": "your-account"
      }
    }
  }
}

Cursor and other HTTP clients#

Point the client at the MCP URL and send your RocketShipIt API key and carrier credentials as headers:

{
  "mcpServers": {
    "rocketshipit": {
      "url": "https://api.rocketship.it/v1/mcp",
      "headers": {
        "x-api-key": "YOUR_RS_API_KEY",
        "X-RS-FEDEX-REST-CLIENT-ID": "your-client-id",
        "X-RS-FEDEX-REST-CLIENT-SECRET": "your-client-secret",
        "X-RS-FEDEX-REST-ACCOUNT-NUMBER": "your-account"
      }
    }
  }
}

For a self-hosted server, use http://your-server:8080/mcp and the RS_API_KEY you started the server with.

What to ask#

"Get UPS rates for a 5 lb box from 72601 to 44333 and tell me which services arrive by Friday."
"Get an Estes LTL quote for one 400 lb pallet, class 70."
"Track 1Z12345E0205271688 and tell me why it is late."
"Ship this order with UPS Ground." The agent shows you the rate and asks before it buys the label.

Notes#

The MCP server is stateless. Each request stands alone, so it runs the same way on a server or on AWS Lambda.
debug is turned off for MCP requests because its output contains your credentials. Use the API explorer to debug carrier requests.