Connect Shippo to Claude: Track Packages and Manage Order Fulfillment

If you need to connect Shippo to Claude to automate order fulfillment, track global shipments, manage multi-carrier rate shopping, or streamline customs declarations, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and Shippo's REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

If your team uses ChatGPT, check out our guide on /connect-shippo-to-chatgpt-compare-rates-and-create-shipping-labels/ or explore our broader architectural overview on /connect-shippo-to-ai-agents-automate-logistics-and-customs-workflow/.

Giving a Large Language Model (LLM) read and write access to a sprawling logistics ecosystem like Shippo is an engineering challenge. You have to handle API token lifecycles, map massive JSON schemas to MCP tool definitions, and deal with Shippo's strict data validation requirements. Every time Shippo updates an endpoint or introduces a new carrier requirement, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Shippo, connect it natively to Claude Desktop, and execute complex fulfillment workflows using natural language.

The Engineering Reality of the Shippo API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against specialized B2B logistics APIs is painful. Shippo normalizes communication across dozens of carriers (USPS, FedEx, UPS, DHL), but its underlying object models are highly relational and strict.

If you decide to build a custom Shippo MCP server, here are the specific integration challenges you will face:

Mutually Exclusive Transaction Payloads Shippo provides two completely different ways to purchase a shipping label (a Transaction). You can either generate a Rate object first and purchase it by passing the rate ID, or you can create a label instantly by passing an instant payload containing full shipment details, a carrier_account, and a servicelevel_token. These two payload shapes are mutually exclusive. If you blindly expose the raw OpenAPI spec to an LLM, it will frequently attempt to mix parameters from both methods, resulting in 400 Bad Request errors. A well-designed MCP tool layer must explicitly guide the LLM on which payload structure to use.

Asynchronous Batch Processing Lifecycles When you need to purchase labels for 500 orders at once, you use Shippo's Batch endpoints. However, batch operations are highly asynchronous. When you create a batch, it enters a VALIDATING state. You cannot purchase it until it becomes VALID. Once you issue the purchase command, it moves to PURCHASING, and eventually PURCHASED. An LLM running in a synchronous chat context cannot simply "fire and forget" a batch creation command and immediately download the labels. The MCP tools must support polling the batch status so the LLM knows when to proceed to the next step.

Strict Rate Limits and Headers Shippo enforces rate limits on its API. Unlike a traditional webhook integration where you might queue events, an LLM operates in real-time. It is crucial to note that Truto does not retry, throttle, or apply backoff on rate limit errors. When Shippo returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The MCP client or agent framework must read these headers and implement its own retry and backoff logic. Do not expect the integration layer to magically absorb rate limits.

Complex Customs Declarations International shipments require a CustomsDeclaration object, which in turn requires an array of CustomsItem objects. The validation rules here are unforgiving. You must provide specific incoterms, certify signers, and ensure weights and currencies match across the items and the parent parcel. A custom MCP server must heavily annotate these schemas so Claude knows exactly what strings are accepted for fields like contents_type (e.g., MERCHANDISE, DOCUMENTS, GIFT).

How to Generate the Shippo MCP Server

Instead of building a Node.js or Python server from scratch to handle these edge cases, you can use Truto to dynamically generate an MCP server for your Shippo account. Truto handles the API authentication, translates the underlying REST endpoints into JSON-RPC 2.0 tools, and derives the necessary schemas directly from the documentation.

You can create a Shippo MCP server using either the Truto UI or the API.

Method 1: Via the Truto UI

For internal automation or one-off agent setups, the UI is the fastest path.

1. Log into your Truto dashboard and navigate to the Integrated Accounts page.
2. Select your connected Shippo integration.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., name the server "Fulfillment Agent", restrict it to specific tags or read-only methods if needed).
6. Copy the generated MCP server URL (it will look like https://api.truto.one/mcp/abc123def456...).

Method 2: Via the Truto API

If you are building an AI product and need to programmatically provision MCP servers for your customers' Shippo accounts, you can use the Truto API.

Make a POST request to /integrated-account/:id/mcp using your Truto API key:

curl -X POST "https://api.truto.one/integrated-account/YOUR_INTEGRATED_ACCOUNT_ID/mcp" \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Shippo Fulfillment Agent",
    "config": {
      "methods": ["read", "write"],
      "tags": ["shipping", "tracking"]
    }
  }'

The API will return a JSON response containing the secure url. This URL encodes the specific integrated account and configurations, meaning no further authentication setup is required on the client side.

{
  "id": "mcp_srv_987654",
  "name": "Shippo Fulfillment Agent",
  "config": { "methods": ["read", "write"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

Connecting the MCP Server to Claude

Once you have the Truto MCP URL, you need to connect it to your LLM client. We will cover both the Claude Desktop UI and the manual configuration file method.

Method 1: Via the Claude UI (or ChatGPT)

If you are using an Enterprise or Pro tier of Claude or ChatGPT, you can add custom connectors directly through the interface.

For Claude Desktop/Web:

1. Open Claude and navigate to Settings.
2. Click on Integrations (or Connectors, depending on your version).
3. Select Add MCP Server.
4. Paste the Truto MCP URL into the Server URL field.
5. Click Add.

For ChatGPT (Developer Mode):

1. Go to Settings -> Apps -> Advanced settings.
2. Enable Developer mode.
3. Under MCP servers / Custom connectors, click add.
4. Name it "Shippo (Truto)" and paste the Truto MCP URL.
5. Save and connect.

Method 2: Via Manual Config File (SSE)

If you are running Claude Desktop locally or orchestrating agents via a framework like Cursor or LangChain, you can configure the MCP connection manually using the Server-Sent Events (SSE) transport.

Edit your claude_desktop_config.json file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "shippo-truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f67890"
      ]
    }
  }
}

Restart Claude Desktop. The application will execute the npx command, establish an SSE connection to the Truto server, and request the tools/list. Claude will now have native access to your Shippo environment.

Hero Tools for Shippo Automation

Truto dynamically generates tools based on the resources available in the Shippo API. Rather than overwhelming the LLM with generic CRUD operations, you can leverage high-value "hero tools" to execute core logistics tasks.

create_a_shippo_shipment

This tool is the foundation of the Shippo API. It calculates rates across multiple carriers synchronously. You pass the origin address, destination address, and parcel dimensions. Claude can use this to shop for the best shipping rates before committing to a purchase.

"I need to ship a 5lb box (12x10x8 inches) from our NY warehouse to 123 Main St, Austin, TX. Can you generate the shipment object and show me the cheapest available rate?"

create_a_shippo_transaction

Once a shipment is created and a specific rate is selected, this tool is used to actually purchase the shipping label. It returns the tracking number, the ETA, and the URLs for the printable PDF or ZPL label.

"Go ahead and purchase the label for the cheapest USPS Priority Mail rate we just found. Give me the tracking number and the label URL."

list_all_shippo_tracks

This tool queries the real-time tracking status of a specific package using the carrier name and tracking number. It returns the current status (e.g., TRANSIT, DELIVERED, RETURNED) along with the full tracking history.

"Can you check the status of FedEx tracking number 789123456789? If it's delayed, draft an email to the customer explaining the situation."

create_a_shippo_batch

For high-volume e-commerce workflows, this tool creates an asynchronous batch job to purchase labels for dozens or hundreds of shipments at once. Claude must supply a default carrier account and service level, along with an array of shipment payloads.

"I have a list of 50 orders in my CSV. Create a Shippo batch using our default USPS account and the Priority Mail service level for all of them."

create_a_shippo_customs_declaration

International shipping requires customs paperwork. This tool generates the necessary documentation, requiring strict inputs like certify_signer, contents_type, and an array of items with their respective weights and values.

"We are shipping a $150 cotton t-shirt to London. Create the customs declaration marking it as MERCHANDISE, sign it as 'John Doe', and link it to the shipment."

create_a_shippo_pickup

This tool schedules a carrier (currently limited to USPS and DHL Express) to come to a specified location to collect packages. It requires the carrier account, the location details, and a time window.

"Schedule a USPS pickup for tomorrow between 9 AM and 5 PM at our main warehouse location. The transaction ID for the packages is abc123xyz."

For the complete tool inventory and detailed JSON schemas, visit the Shippo integration page.

Workflows in Action

Exposing individual tools is useful, but the real power of MCP emerges when Claude chains these tools together to solve complex logistics problems autonomously. Here are two real-world scenarios.

Scenario 1: Cross-Border Fulfillment

When a customer places an international order, several dependent API calls must occur in a specific sequence. An LLM connected via MCP can orchestrate this entire flow.

"We received an order going to Toronto, Canada. The customer bought two pairs of shoes. Validate their address, create the customs declaration for the shoes ($50 each, 1lb each), generate the shipment, and buy the cheapest DHL Express label."

Tool Execution Sequence:

1. shippo_addresses_validate: Claude first checks the destination address. If Shippo returns validation errors (e.g., missing postal code), Claude asks the user for clarification before proceeding.
2. create_a_shippo_customs_item: Claude creates two customs item records for the shoes, specifying the mass unit and value currency.
3. create_a_shippo_customs_declaration: Claude bundles the items into a declaration, setting contents_type to MERCHANDISE.
4. create_a_shippo_shipment: Claude posts the origin address, validated destination address, parcel dimensions, and the newly created customs declaration ID.
5. create_a_shippo_transaction: Claude filters the returned rates for the cheapest DHL Express option, passes that rate ID to the transaction endpoint, and returns the final tracking number and label URL to the user.

sequenceDiagram
    participant User as End User
    participant Claude as Claude (LLM)
    participant Truto as Truto MCP Server
    participant Shippo as Shippo API

    User->>Claude: "Ship 2 pairs of shoes to Toronto..."
    Claude->>Truto: call shippo_addresses_validate
    Truto->>Shippo: POST /addresses/{id}/validate
    Shippo-->>Truto: Valid Address Data
    Claude->>Truto: call create_a_shippo_customs_declaration
    Truto->>Shippo: POST /customs/declarations/
    Shippo-->>Truto: 201 Created (Declaration ID)
    Claude->>Truto: call create_a_shippo_shipment
    Truto->>Shippo: POST /shipments/
    Shippo-->>Truto: Rates Array
    Claude->>Truto: call create_a_shippo_transaction
    Truto->>Shippo: POST /transactions/
    Shippo-->>Truto: Label URL & Tracking Number
    Truto-->>Claude: Final Output Data
    Claude-->>User: "Label generated successfully. Tracking: DHL-12345"

Scenario 2: Proactive Tracking Audits

Customer support teams waste hours manually checking tracking numbers for delayed packages. Claude can automate this auditing process entirely.

"Audit all of our FedEx shipments from the last 7 days. Check their tracking statuses. If any are marked as 'EXCEPTION' or 'RETURNED', compile a list with the tracking numbers and the last known location."

Tool Execution Sequence:

1. list_all_shippo_shipments: Claude queries the shipments list, using the object_created_gte filter to limit the scope to the last 7 days.
2. list_all_shippo_transactions: Claude iterates over the shipments to extract the associated transaction IDs and tracking numbers.
3. list_all_shippo_tracks: For every FedEx tracking number found, Claude calls the tracking endpoint to get real-time status updates.
4. Analysis: Claude processes the tracking_status field. It filters out anything marked DELIVERED or TRANSIT.
5. Output: Claude synthesizes the data into a clean markdown table showing the problematic shipments, the exact exception reason, and the last known scan location.

Security and Access Control

Giving an AI agent write access to your shipping budget requires strict governance. Truto MCP servers include built-in access controls to minimize risk:

• Method Filtering: You can restrict the MCP server configuration to methods: ["read"]. This allows an agent to audit tracking numbers and calculate rates, but strictly prevents it from executing a create_a_shippo_transaction (buying a label).
• Tag Filtering: You can limit the server to specific resource tags. For instance, you can expose tracking tools while hiding billing or carrier_accounts tools.
• Require API Token Auth: For internal enterprise deployments, you can set require_api_token_auth: true. This forces the client to pass a valid Truto API token in the Authorization header, ensuring that possession of the MCP URL alone is not enough to execute tools.
• Time-to-Live (TTL): You can set an expires_at timestamp when creating the server. Once the timestamp passes, the server URL becomes permanently invalid, which is ideal for temporary contractor access or ephemeral agent workflows.

Unlocking Autonomous Logistics

Connecting Shippo to Claude via a managed MCP server removes the friction of maintaining complex integration code. You don't have to write custom polling logic for batch processing, you don't have to maintain TypeScript definitions for customs declarations, and you don't have to worry about OAuth token refreshes.

By leveraging Truto's dynamic tool generation, you give your AI agents instant, strictly-typed access to one of the most powerful logistics APIs available, allowing your team to focus on building intelligent fulfillment workflows rather than fighting API boilerplate.