Connect ShipBob to Claude: Manage Shipping Logistics & Returns

If your supply chain or customer experience team needs to connect ShipBob to Claude to automate order triage, process returns, or audit inventory levels across fulfillment centers, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's LLM function calls and ShipBob's native REST APIs. You can either build, host, and patch this middleware yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL on the fly.

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

Giving a Large Language Model read and write access to a physical logistics engine is high stakes. You have to map highly nested fulfillment JSON schemas to MCP tool definitions, manage API authentication securely, and handle complex asynchronous states. When ShipBob updates its Warehouse Receiving Order (WRO) logic or introduces new tracking parameters, custom server code breaks.

This guide details how to bypass the custom build by using Truto to generate a managed MCP server for ShipBob, connect it securely to Claude, and execute complex fulfillment workflows via natural language.

The Engineering Reality of the ShipBob API

A custom MCP server is essentially a self-hosted integration layer. While the open MCP standard provides a predictable interface for Claude to discover tools, the reality of implementing it against ShipBob's specialized logistics APIs is complex.

If you choose to build a custom MCP server, you own the entire API lifecycle. Here are the specific ShipBob integration challenges you will face:

Misleading 200 OK Responses on Bulk Operations ShipBob offers several bulk endpoints - such as ship_bob_shipments_bulk_place_on_hold or ship_bob_shipment_line_items_bulk_update. A standard REST integration assumes a 200 HTTP status code means the operation succeeded. In ShipBob, a bulk update endpoint will return HTTP 200 even if the underlying updates fail for specific line items. The response payload contains a per-shipment or per-item is_success flag and an array of granular error codes. If you do not explicitly code your MCP server to parse the internal result arrays and feed failures back into the LLM context, Claude will hallucinate that a critical shipment hold was applied when it actually failed.

Asynchronous Inventory and Location Assignments Operations in ShipBob do not always execute synchronously. When you call ship_bob_shipments_assign_fulfillment_center to manually route an order to a specific warehouse, the API returns success immediately. However, the actual inventory re-evaluation and reallocation process runs asynchronously in the background. If Claude queries the shipment status immediately after assigning the center, it may read stale data. The MCP server or the agent orchestration layer must be aware of this delay and utilize timeline logging endpoints to verify state changes.

Opaque Rate Limit Visibility ShipBob enforces specific rate limits based on token and endpoint tiers. Truto simplifies this by passing rate limit realities directly to the caller. Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream ShipBob API returns an HTTP 429, Truto passes that error to the caller immediately. Truto normalizes the upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. This means your Claude client or LangChain framework retains full control and responsibility over retry and backoff logic, without requests timing out silently in a black-box middleware queue.

Creating the ShipBob MCP Server

Truto dynamically generates MCP tools based on the actual ShipBob API documentation records. Tools only appear in the MCP server if they have a corresponding schema definition. This acts as a strict quality gate, ensuring Claude only sees tools with clear descriptions and typed query/body parameters.

You can instantiate an MCP server for a connected ShipBob account via the Truto UI or via the API.

Method 1: Via the Truto UI

For administrators setting up an internal tool, the UI provides a one-click generation path:

1. Navigate to the Integrated Accounts page in your Truto dashboard.
2. Select the connected ShipBob account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., restrict to read methods only, or filter by specific tags).
6. Copy the generated MCP server URL. (Store this securely; the token is a hashed cryptographic secret).

Method 2: Via the API

For teams building multi-tenant AI products, you can generate MCP servers programmatically. This endpoint checks plan limits, validates that the requested filters match at least one documented tool, and provisions the server URL.

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ShipBob Logistics Agent",
    "config": {
      "methods": ["read", "write"],
      "tags": ["orders", "inventory"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The response returns the server metadata and the connection URL:

{
  "id": "mcp_abc123",
  "name": "ShipBob Logistics Agent",
  "config": {
    "methods": ["read", "write"],
    "tags": ["orders", "inventory"]
  },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/sk_live_12345abcdef..."
}

Connecting the MCP Server to Claude

Once you have the Truto MCP URL, you can plug it directly into Claude. No OAuth handshakes or custom middleware required on the client side.

Option A: Via the Claude UI

If you are using Claude Desktop or an enterprise Claude instance with connector support:

1. Open Claude Settings.
2. Navigate to Integrations or Connectors.
3. Click Add MCP Server.
4. Name the connection (e.g., "ShipBob Truto").
5. Paste the Truto MCP URL.
6. Click Add. Claude will immediately send an initialize JSON-RPC handshake to discover the available ShipBob tools.

Option B: Via Manual Config File

If you are configuring Claude Desktop locally via its configuration file, you can utilize the official MCP SSE client to bridge Claude to the remote Truto URL.

Edit your claude_desktop_config.json file:

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

Save the file and restart Claude Desktop. The application will boot the SSE transport layer and map the remote ShipBob tools into Claude's context window.

Hero Tools for ShipBob Workflows

Truto maps the entire ShipBob API into distinct MCP tools. Here are six high-leverage "hero" tools that AI agents frequently use to automate supply chain tasks.

1. View Detailed Order Status (get_single_ship_bob_order_by_id)

Retrieves a complete view of a single order, including its tracking details, assigned warehouse, packed line items, and recipient address. This is the foundational tool for order triage workflows.

"Claude, check the status of order ID 1098432. Has it left the facility yet, and what carrier is handling the final mile?"

2. Place Shipments on Hold (ship_bob_shipments_bulk_place_on_hold)

Manually pauses processing on one or more shipments. This is critical for intercepting orders before they are picked and packed if a customer requests a cancellation or address change.

"A customer just requested a cancellation for their order. Immediately place shipment ID 55432 on hold so the warehouse stops processing it."

3. Initiate Returns (create_a_ship_bob_return)

Generates an RMA (Return Merchandise Authorization) in ShipBob. This tool dictates which inventory items are coming back, which fulfillment center is expecting them, and the requested return actions (restock, dispose, or quarantine).

"The customer for order reference WEB-993 is returning their defective espresso machine. Create a return order routing it back to the Dallas fulfillment center for quarantine and inspection."

4. Search Live Shipping Rates (ship_bob_logistics_rates_search)

Rate-shops a shipment across ShipBob's available carriers based on physical dimensions, weight, destination, and fulfillment center origin.

"Estimate the shipping cost for a 12x12x8 inch box weighing 4 lbs, shipping from the Chicago facility to zip code 90210. Do not include signature requirements."

5. Check Aggregated Inventory Levels (get_single_ship_bob_inventory_level_by_id)

Fetches current stock levels aggregated across all ShipBob fulfillment centers for a specific inventory ID, showing quantities that are on-hand, committed, fulfillable, and backordered.

"Check our total fulfillable stock for inventory ID 8847 (the blue medium t-shirts) across the network to see if we have enough to cover a 50-unit B2B wholesale order."

6. Mark WRO External Sync (ship_bob_receiving_orders_set_external_sync)

Updates a Warehouse Receiving Order (WRO) to mark it as externally synced. This helps orchestration engines track which inbound receiving records have already been written back to the primary ERP or accounting system.

"Mark WRO ID 7762 as externally synced so the accounting agent knows the inventory receipt has already been logged in NetSuite."

To view the complete inventory of ShipBob tools and detailed JSON schema requirements, visit the Truto ShipBob Integration Page.

Workflows in Action

AI agents provide the most value when they chain multiple specialized API endpoints together to resolve complex intents. Here are two real-world workflows demonstrating how Claude orchestrates ShipBob tools.

Scenario 1: Customer Support Triage

A customer emails support asking, "Where is my order? The tracking link in my email is broken."

"Claude, the customer for order reference 'SHOPIFY-10293' is asking for their tracking link. Find their order, pull the active tracking URL, and draft a response."

Agent Execution Steps:

1. list_all_ship_bob_orders: Claude calls this tool passing reference_id=SHOPIFY-10293 to locate the ShipBob internal order ID.
2. list_all_ship_bob_order_shipments: Claude uses the returned order_id to fetch the shipments associated with the order.
3. list_all_ship_bob_shipments_tracking: Claude passes the shipment_id to retrieve the active carrier tracking number and URL.

sequenceDiagram
  participant User as Customer Support
  participant Claude as Claude Agent
  participant Truto as Truto MCP
  participant ShipBob as ShipBob API

  User->>Claude: "Find tracking for SHOPIFY-10293."
  Claude->>Truto: call list_all_ship_bob_orders<br>{"reference_id":"SHOPIFY-10293"}
  Truto->>ShipBob: GET /orders?reference_id=...
  ShipBob-->>Truto: Order ID 9942
  Truto-->>Claude: Result Object
  Claude->>Truto: call list_all_ship_bob_order_shipments<br>{"order_id":9942}
  Truto->>ShipBob: GET /orders/9942/shipments
  ShipBob-->>Truto: Shipment Array
  Truto-->>Claude: Result Object
  Claude-->>User: "Your order shipped via UPS. Here is the link..."

Scenario 2: Canceling an Order in Processing

A customer realizes they ordered the wrong size and asks to cancel their order 30 minutes after checkout.

"Claude, intercept order 55923. Put its shipments on manual hold, verify the hold was successful, and then cancel the order completely."

Agent Execution Steps:

1. get_single_ship_bob_order_by_id: Claude inspects the order to ensure it hasn't already been picked or packed. It notes the attached shipment_id.
2. ship_bob_shipments_bulk_place_on_hold: Claude executes a manual hold on the shipment to freeze warehouse activity.
3. Claude inspects the is_success array in the response to ensure the hold didn't fail due to an invalid state.
4. ship_bob_orders_cancel: Claude cancels the root order, releasing the reserved inventory back to the fulfillable pool.

Security and Access Control

Giving an AI agent raw API access requires strict boundaries. Truto MCP servers implement governance at the server URL level, meaning Claude cannot override your security constraints.

• Method Filtering: Set methods: ["read"] during server creation to ensure the server only derives GET and LIST tools. Write operations like create_a_ship_bob_order are entirely stripped from the schema, making unauthorized modifications impossible.
• Tag Filtering: Use tags: ["inventory"] to restrict the toolset to specific domains. The agent will only see inventory-related operations, hiding sensitive financial or billing endpoints.
• Mandatory API Auth Layer: By enabling require_api_token_auth: true, the token URL alone is insufficient. The client must also pass a valid Truto session token or API key in the authorization header, enforcing identity validation on every tool call.
• Automated Token Expiration: By passing an expires_at timestamp, Truto will automatically destroy the server record and its associated KV cache via a scheduled Durable Object alarm. This is ideal for provisioning temporary, ephemeral agents that clean up after themselves.

Summary

Connecting ShipBob to Claude via a managed MCP server removes the burden of writing, maintaining, and debugging integration middleware. Instead of parsing ShipBob's bulk success flags or wrestling with custom error handlers, your engineering team can focus on orchestrating complex agentic workflows.

Truto's dynamically generated MCP tools ensure your LLM operates against accurate schemas, while method filtering and expiration controls guarantee the environment remains secure.