Connect Shippo to ChatGPT: Compare Rates and Create Shipping Labels

If your AI agents need to orchestrate physical logistics - creating shipping labels, comparing carrier rates, declaring international customs, and tracking packages - you must give them read and write access to the Shippo API. To do this securely without hardcoding custom HTTP request logic into your agent's prompt, you need a Model Context Protocol (MCP) server.

If your team uses Claude, check out our guide on connecting Shippo to Claude or explore our broader architectural overview on connecting Shippo to AI Agents.

Building an MCP server from scratch means writing complex translation layers between your LLM's JSON outputs and Shippo's specific nested data structures. It also means managing OAuth flows, securely storing API keys, and dealing with authentication state. Instead of building and maintaining this infrastructure, you can use Truto to dynamically generate a secure, authenticated MCP server URL that wraps the Shippo API in standardized LLM tools.

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

The Engineering Reality of the Shippo API

When exposing an API to an LLM, the model assumes standard RESTful CRUD patterns. Shippo's API is powerful but highly opinionated, requiring specific sequences of operations and strictly formatted payloads. If you build a custom MCP server, you must explicitly code guardrails for these behaviors. Truto handles the schema translation, but it helps to understand exactly what makes the Shippo API unique.

Mutually Exclusive Transaction Shapes

Creating a shipping label in Shippo is called creating a "Transaction". The POST /transactions endpoint has a severe architectural quirk: it accepts two completely different, mutually exclusive JSON bodies.

You can either pass a rate string (the ID of a previously calculated shipping rate), OR you can pass an entire shipment object with embedded carrier and service level tokens for an "instant" transaction. If an LLM attempts to pass both a rate ID and a shipment object, the API will reject the request. When using Truto's generated schemas, the required properties clearly delineate these paths, preventing the LLM from hallucinating merged payloads.

Asynchronous Rate Queuing vs Synchronous Execution

When you create a shipment via POST /shipments, Shippo calculates rates across your connected carrier accounts. By default, Shippo does this asynchronously. If you do not explicitly pass async=false, the immediate response will contain an empty rates array, forcing you to poll the /rates endpoint later. LLMs are terrible at unguided polling. By providing clear schema descriptions, the Truto MCP server instructs the LLM to pass async=false when immediate rate comparison is required.

Nested Customs Dependencies

International shipments require a customs declaration. In Shippo, a customs declaration is not just a flat object attached to a shipment. It is an independent resource that requires an array of customs_items. Each item requires specific mass units, net weights, value amounts, and origin countries. The LLM must first create the customs items, then attach them to a customs declaration, and finally link that declaration to the outbound shipment.

Rate Limits and 429 Handling

Truto does not retry, throttle, or apply backoff on rate limit errors. When the Shippo API returns an HTTP 429 (Too Many Requests), Truto passes that error directly to the caller. Truto normalizes upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller - whether that is ChatGPT's internal execution loop or your own agent orchestrator - is entirely responsible for reading the reset window and managing backoff logic. Do not assume the infrastructure will silently absorb rate limits.

How to Generate a Shippo MCP Server

To connect ChatGPT to Shippo, we first need to scope an MCP server to a specific, authenticated Shippo account.

Step 1: Connect the Integrated Account

Before generating an MCP server, you need a valid connection to Shippo. In Truto, this is called an Integrated Account.

Navigate to your Truto dashboard, select Integrated Accounts, and click New Integrated Account. Select Shippo and complete the OAuth flow or token injection. Once connected, Truto securely stores the credentials and handles background token refreshes automatically. Note the integrated_account_id generated upon successful connection.

Step 2: Create the MCP Server

Truto derives MCP tools directly from the underlying API schemas. You can generate the server URL via the Truto UI or programmatically via the API.

Method A: Via the Truto UI

1. Navigate to the integrated account page for your Shippo connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration. For example, you might want to restrict the agent to only read operations, or only allow access to specific resources like "shipments" and "tracking".
5. Click Create and copy the generated MCP server URL (it will look like https://api.truto.one/mcp/<token>).

Method B: Via the API If you are building an application that provisions AI agents dynamically, you can generate the MCP server programmatically using the Truto API.

curl -X POST https://api.truto.one/integrated-account/<INTEGRATED_ACCOUNT_ID>/mcp \
  -H "Authorization: Bearer $TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Shippo Fulfillment Agent",
    "config": {
      "methods": ["read", "write"],
      "tags": ["shipments", "rates", "transactions"]
    }
  }'

The API validates that the integration has tools available, generates a secure cryptographic token, and provisions the endpoint at the edge. The response contains the url field. This single URL carries both the routing logic and the authentication state. Treat it like a sensitive credential.

Connecting the MCP Server to ChatGPT

Once you have the Truto MCP URL, connecting it to your LLM interface takes seconds.

Method A: Via the ChatGPT UI

1. Open ChatGPT (requires a Pro, Plus, Business, Enterprise, or Education account).
2. Navigate to Settings -> Apps -> Advanced settings.
3. Enable Developer mode.
4. Under MCP servers / Custom connectors, click Add new.
5. Give it a recognizable name like "Shippo Operations".
6. Paste the Truto MCP URL into the Server URL field.
7. Click Save.

ChatGPT will immediately ping the server, run the initialization handshake, and parse the available tool schemas.

Method B: Via Manual Config (SSE Transport) If you are running a local testing environment or using an orchestrator that requires a JSON configuration file (similar to Claude Desktop's claude_desktop_config.json), you can bridge the HTTP endpoint using the official MCP SSE proxy.

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

Shippo Hero Tools for AI Agents

Truto exposes the entirety of the Shippo API as dynamically generated tools. Here are the core tools your agent will use to handle logistics and fulfillment.

create_a_shippo_shipment

Creates a new shipment by passing origin and destination addresses along with package dimensions. This is the foundational step before purchasing a label.

Usage note: Ensure the agent sets async=false if it needs to immediately retrieve rates in the next step. Otherwise, the rates calculation enters a background queue.

"I need to ship a 10x10x10 inch box weighing 5 lbs from our warehouse to 123 Main St, Toronto. Create the shipment in Shippo and generate the rates synchronously."

list_all_shippo_shipment_rates

Retrieves the available carrier rates for a specific shipment ID.

Usage note: Rates older than 390 days are purged by Shippo and will not be returned. The agent must parse the amount and provider fields to compare costs.

"List all the shipping rates for shipment object ID shp_12345. Tell me which one is the cheapest and which one offers the fastest estimated delivery."

create_a_shippo_transaction

Purchases a shipping label. This tool accepts either a rate ID (for a previously calculated rate) or a complete shipment object for instant generation.

Usage note: Purchasing a label triggers actual billing against your connected carrier account.

"Purchase the shipping label for the cheapest UPS rate we just found. Confirm when the transaction is successful."

get_single_shippo_transaction_by_id

Retrieves the details of an existing shipping label, including tracking information and the URL to download the actual PDF or ZPL label file.

Usage note: The label_url field contains the link to the physical label document. The LLM cannot render PDFs directly but can output the link to the user.

"Get the details for transaction txn_98765 and give me the tracking number and the direct URL to print the label."

create_a_shippo_customs_declaration

Creates the necessary customs documentation for international shipments, detailing contents, value, and certification.

Usage note: The agent must strictly format the items array with precise weights and monetary values, matching the destination country's import requirements.

"Create a customs declaration for a commercial sample being shipped to Germany. It contains two cotton t-shirts valued at $15 USD each, originating from the US."

create_a_shippo_track

Registers a tracking webhook in Shippo to receive real-time HTTP notifications when a package's transit status changes.

Usage note: This is highly useful for proactive customer support workflows, allowing the system to update external databases when a package is marked "Delivered".

"Register tracking for FedEx package number 771234567890 so our system gets notified of its transit status."

create_a_shippo_refund

Initiates a refund request for an unused shipping label (transaction).

Usage note: Refunds are not always instant; carrier approval times vary. The agent must pass the original transaction ID.

"The customer canceled their order before it shipped. Void the label by creating a refund for transaction txn_112233."

To view the complete inventory of available tools, required payloads, and JSON schemas, visit the Shippo integration page.

Workflows in Action

With the MCP server connected to ChatGPT, the model can chain these tools together to execute complex, multi-step logistics workflows autonomously.

Workflow 1: End-to-End International Fulfillment

Shipping a package across borders requires multiple API calls in a strict sequence. An IT admin or fulfillment manager can ask ChatGPT to handle the entire process.

"We need to ship order #5521 to London, UK. It is a 2lb box measuring 8x8x6 inches. Create the customs declaration for $50 worth of electronics, build the shipment, find the fastest DHL rate, and purchase the label. Give me the tracking number and label URL when done."

Execution Steps:

1. create_a_shippo_customs_declaration: ChatGPT formats the items array, sets the incoterm, signs the certification, and retrieves the new customs object ID.
2. create_a_shippo_shipment: The agent creates the shipment using the origin and UK destination addresses, the box dimensions, and the customs object ID. It passes async=false to wait for pricing.
3. list_all_shippo_shipment_rates: The model queries the returned shipment ID to view the available rates from connected carriers.
4. create_a_shippo_transaction: The agent identifies the DHL Express rate ID from the list, submits it to the transaction endpoint, and purchases the label.

Result: The user receives a concise summary of the transaction cost, the DHL tracking number, and a direct hyperlink to print the customs-ready shipping label.

sequenceDiagram
    participant User
    participant ChatGPT
    participant Truto as Truto MCP Server
    participant Shippo as Shippo API

    User->>ChatGPT: "Ship order #5521 to London..."
    ChatGPT->>Truto: call create_a_shippo_customs_declaration
    Truto->>Shippo: POST /customs/declarations/
    Shippo-->>Truto: Customs ID
    Truto-->>ChatGPT: Customs ID
    ChatGPT->>Truto: call create_a_shippo_shipment
    Truto->>Shippo: POST /shipments/
    Shippo-->>Truto: Shipment ID
    Truto-->>ChatGPT: Shipment ID
    ChatGPT->>Truto: call list_all_shippo_shipment_rates
    Truto->>Shippo: GET /shipments/{id}/rates
    Shippo-->>Truto: Rates Array
    Truto-->>ChatGPT: Rates Array
    ChatGPT->>Truto: call create_a_shippo_transaction
    Truto->>Shippo: POST /transactions/
    Shippo-->>Truto: Label URL & Tracking
    Truto-->>ChatGPT: Label URL & Tracking
    ChatGPT-->>User: "DHL label generated. Here is the link."

Workflow 2: Customer Support Issue Resolution

Support agents frequently need to check where a package is, and if it is lost or canceled, void the label to recover costs.

"Check the tracking status of USPS package 9400123456789. If it hasn't entered the mail stream yet, please initiate a refund for the label."

Execution Steps:

1. list_all_shippo_tracks: The agent queries the tracking status using the carrier name (usps) and the tracking number.
2. Analysis: The model reads the tracking_status from the payload. If the status is UNKNOWN or PRE_TRANSIT, it knows the package has not been shipped.
3. create_a_shippo_refund: The agent extracts the underlying transaction ID from the tracking response and executes the refund request.

Result: The agent replies confirming that the package was unshipped and that the refund request has been submitted to USPS.

Security and Access Control

Exposing an e-commerce infrastructure API to an LLM requires strict boundary setting. A hallucination that bulk-purchases expensive overnight labels can incur significant financial damage. Truto provides edge-level access controls when provisioning the MCP server:

• Method Filtering: Constrain the agent to read-only access. By setting config.methods: ["read"], you allow the LLM to query tracking statuses and list existing addresses without granting it the ability to spend money via the POST /transactions endpoint.
• Tag Filtering: Limit the server's scope by functional area. Setting config.tags: ["tracking", "addresses"] ensures the agent only sees tools related to those specific integration resources, hiding sensitive administrative endpoints.
• Extra Authentication (require_api_token_auth): By default, the MCP URL acts as a bearer token. For higher security environments, setting this flag requires the caller to also pass a valid Truto API token in the Authorization header, preventing unauthorized network access if the MCP URL is leaked.
• Ephemeral Servers (expires_at): Provide temporary AI access for specific batch jobs or external contractors by setting an ISO datetime expiration. Truto will automatically clean up the underlying edge state when the time expires, permanently killing the server.

Unblock Your AI Logistics Engine

Connecting ChatGPT to Shippo using a custom-built integration requires maintaining OAuth states, mapping dense JSON schemas, writing API proxies, and keeping up with version changes.

By leveraging Truto's auto-generated MCP servers, you eliminate the integration boilerplate. You can instantly expose Shippo's powerful fulfillment and rating engine to your AI agents, allowing them to construct shipments, negotiate rates, and manage tracking lifecycles natively.

Stop fighting API documentation and start shipping automations. Let Truto handle the integration layer so your engineering team can focus on core product value.