Shippo Clawhub Skill

MCP server: standalone @shippo/shippo-mcp (npm package, Speakeasy-generated, stdio transport). The MCP client launches it locally via npx — no hosted URL is involved. Requires Node.js 18+.

Configure your MCP client with:

{
  "mcpServers": {
    "shippo": {
      "command": "npx",
      "args": [
        "-y",
        "@shippo/shippo-mcp",
        "start",
        "--api-key-header",
        "ShippoToken ${SHIPPO_API_KEY}",
        "--shippo-api-version",
        "2018-02-08"
      ]
    }
  }
}

If your MCP client does not interpolate ${SHIPPO_API_KEY} inside args[], substitute the literal ShippoToken shippo_{test|live}_xxxxx value into the --api-key-header string.

Prerequisites: A valid Shippo API key and at least one carrier account (Shippo provides managed accounts for USPS, UPS, FedEx, DHL Express by default). See references/tool-reference.md for the full tool catalog.

Test vs live mode -- check the API key prefix before any purchase workflow:

Test and live mode have completely separate data and object IDs.

Response envelope: The MCP wraps most API responses in a Speakeasy envelope shaped like {"ContentType": "application/json", "StatusCode": , "RawResponse": {}, "": {...actual response...}}. The payload field is named after the response schema on success (e.g. ParsedAddress, AddressPaginatedList, AddressValidationResultV2, AddressWithMetadataResponse, Shipment, CarrierAccountPaginatedList) and after the HTTP status code on some errors (e.g. fourHundredAndNineApplicationJsonObject for a 409 — the body may be {}). To extract the payload, find the field whose key is not ContentType, StatusCode, or RawResponse, and branch on StatusCode for success vs error.

Non-envelope errors: Some failures bypass the envelope entirely and surface as an MCP-level error instead — the tool response has isError: true with a single text block containing a plaintext message like Unexpected API response status or content-type: Status 404 Content-Type application/json Body: {"detail":"Not found."}. Argument-validation failures come back as JSON-RPC error code -32602. Handle both paths when reporting errors to the user.