MCP Server

Overview

The Deftship MCP Server connects any AI assistant that speaks the Model Context Protocol — Claude Desktop, Claude Code, Cursor, Codex CLI and others — directly to your Deftship account. Your assistant can quote, ship, track, void and manage shipments in plain language, authenticating with the same sandbox or production token you generate on your API page.

It is published as a scoped npm package, so there is nothing to clone or build. Your MCP client runs it on demand with npx.

{info} The server uses your existing Deftship API token. Start with a sandbox token, test your flows against the isolated $10,000 dummy balance, then switch to a production token when you are ready to spend real money.

Install

Add one block to your client's MCP config, drop in a token, and restart the client. No global install is required — npx -y @deftship/mcp fetches and runs the latest version.

Claude Desktop / Claude Code (claude_desktop_config.json or .mcp.json):

{
    "mcpServers": {
        "deftship": {
            "command": "npx",
            "args": ["-y", "@deftship/mcp"],
            "env": {
                "DEFTSHIP_API_TOKEN": "bearer-your-token-here",
                "DEFTSHIP_ENV": "sandbox"
            }
        }
    }
}

Cursor (.cursor/mcp.json) uses the exact same shape as the Claude block above.

Codex CLI (~/.codex/config.toml):

[mcp_servers.deftship]
command = "npx"
args = ["-y", "@deftship/mcp"]
env = { DEFTSHIP_API_TOKEN = "bearer-your-token-here", DEFTSHIP_ENV = "sandbox" }

Environment Variables

Variable Required Default Description
DEFTSHIP_API_TOKEN Yes — Your Deftship API token, generated on the API page.
DEFTSHIP_ENV No sandbox Either sandbox or production. Selects the API environment. You never set a URL by hand.

{success} Sandbox Environment

Endpoint: https://sandbox.deftship.com/api

{success} Production Environment

Endpoint: https://api.deftship.com

Safety Guardrails

Because an AI agent can drive the whole lifecycle, spending is deliberately hard to do by accident:

  • Sandbox by default. With DEFTSHIP_ENV=sandbox (the default) every operation runs against the isolated sandbox and never touches production. Going live is a deliberate one-line change to production.
  • Explicit confirmation. Every tool that spends your balance or is irreversible — ship, void, book insurance, arrange pickup, ship batch — refuses to run unless it is called with "confirm": true, forcing the assistant to surface the action to you first.
  • Honest tool hints. Read-only tools are marked as read-only and spending tools as destructive, so clients can prompt for your approval before acting.

What It Can Do

The full shipping lifecycle is exposed as tools, mirroring the endpoints documented throughout these docs:

Domain Tools
Parcel Get rates, create draft, ship, void, get / track, merge labels, mark as shipped, list e-commerce orders
Freight Get rates, create draft, ship, void, get / track
Pickup Get rates, create, arrange, void, get
Insurance Get rate, book, void
Batch (beta) Create, add items, remove items, get, ship
Account Check balance, address book, validate address, service names, carrier status, create ticket

Typical Flow

The tools mirror the API, so shipping a parcel follows the same sequence you would use when calling the endpoints directly. The assistant selects and calls these tools on your behalf from a natural-language instruction.

Step Tool Description
1 deftship_get_parcel_rates Quote the shipment. Returns a list of rates, each with a rate_id. See Get Rates.
2 — Choose a rate_id from the returned rates.
3 deftship_ship_parcel Purchase the label for the chosen rate. Requires "confirm": true because it spends your balance.
4 deftship_get_parcel Fetch the label URL and tracking number. See Get Parcel Order.

Use deftship_void_parcel to void a shipment that is no longer needed. Freight, pickup, insurance and batch expose the same rate, ship, get and void pattern under their own tool names.

Troubleshooting

  • DEFTSHIP_API_TOKEN is not set — the env block is missing the token, or the client was not restarted after editing the config. Restart the client so it reloads the config.
  • 401 Unauthorized — the token is invalid or belongs to the wrong environment. A sandbox token only works with DEFTSHIP_ENV=sandbox, and a production token only with production.
  • A ship / void action does nothing — spending tools require "confirm": true. Tell the assistant to confirm the action and it will retry.