Connect Mailstep to Claude: Manage Inventory and Warehouse Receipts

If you need to connect Mailstep to Claude to automate e-commerce fulfillment, track warehouse receipts, manage product stock, or resolve shipping issues, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's function-calling capabilities and Mailstep'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 connecting Mailstep to ChatGPT or explore our broader architectural overview on connecting Mailstep to AI Agents.

Giving a Large Language Model (LLM) read and write access to a complex logistics and Warehouse Management System (WMS) like Mailstep is a significant engineering challenge. You have to handle API authentication lifecycles, map strictly-typed JSON schemas for fulfillment operations to MCP tool definitions, and deal with Mailstep's specific state machine rules. Every time a warehouse resource changes or a new shipping parameter is required, you must 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 Mailstep, connect it natively to Claude Desktop, and execute complex warehouse management workflows using natural language.

The Engineering Reality of the Mailstep API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable JSON-RPC 2.0 interface for models to discover tools, the reality of implementing it against Mailstep's APIs is painful. Mailstep is an advanced 3PL (Third-Party Logistics) platform, and its data model reflects the physical reality of moving freight, tracking inventory, and communicating with warehouse floor staff.

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

The WMS State Machine and Expedition Locking In Mailstep, an "Expedition" (shipment/order) isn't simply a CRUD record you can freely update. It follows a strict lifecycle as it moves to the Warehouse Management System (WMS). Expeditions transition through states: assign, send, execute, cancel, and revert. If you attempt to update an expedition that is already in fulfillment with an open issue, the API strictly rejects changes to core items. It only accepts updates to the order note, billing/delivery addresses, and carrier-related fields. If your MCP tool definition doesn't enforce this schema dynamically, the LLM will hallucinate invalid updates, resulting in constant 400 Bad Request errors.

Asynchronous Issue Resolution Workflows When problems occur on the warehouse floor—such as missing stock or damaged inbound goods—Mailstep utilizes InboundIssue and OutboundIssue entities. Communication is stateful and asynchronous. If an inbound issue requires information, you must submit a proposed solution, which transitions the issue to "awaiting reaction" while warehouse staff review it. Your MCP server must expose specific resolution endpoints (e.g., mailstep_outbound_issues_resolve with strictly enumerated resolutions like WAIT_FOR_RESTOCK or SHIP_INCOMPLETE) rather than generic PATCH operations.

Handling Volatile E-Commerce Rate Limits Logistics platforms experience massive traffic spikes during sales events (Black Friday, Cyber Monday). The Mailstep API enforces strict rate limits to protect infrastructure. Truto does not retry, throttle, or apply automatic backoff on rate limit errors. Instead, when the upstream Mailstep API returns an HTTP 429, Truto passes that error directly to the caller and normalizes the upstream rate limit info into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The caller (your AI agent framework) is entirely responsible for detecting the 429 and implementing appropriate retry and exponential backoff logic.

Generating a Mailstep MCP Server with Truto

Instead of building a Node.js or Python server from scratch to handle the schema mapping, authentication, and HTTP transport, you can use Truto to spin up an MCP server instantly. Tools are dynamically generated from Mailstep's documentation and API schemas.

You can generate the MCP server in two ways: via the Truto UI for rapid prototyping, or programmatically via the REST API for scalable infrastructure.

Method 1: Via the Truto UI

If you are setting up an internal tool or testing Claude Desktop locally, the UI is the fastest route:

1. Log into your Truto dashboard and navigate to your Integrated Accounts.
2. Select your connected Mailstep account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Configure your server (assign a name, select allowed methods like read or write, and set an optional expiration date).
6. Click Save and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4...).

Method 2: Via the Truto REST API

For DevOps teams and platform engineers embedding AI agents into production applications, you can provision MCP servers programmatically. This generates a secure, hashed token stored in distributed KV infrastructure.

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

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

The response will return your server configuration and the critical url required for Claude to connect:

{
  "id": "mcp_8f7e6d5c",
  "name": "Claude Mailstep WMS Agent",
  "config": {
    "methods": ["read", "write", "custom"],
    "tags": ["inventory", "expeditions", "issues"]
  },
  "expires_at": "2026-12-31T23:59:59.000Z",
  "url": "https://api.truto.one/mcp/1234567890abcdef"
}

Connecting the MCP Server to Claude

Once you have your Truto MCP URL, connecting it to Claude requires zero additional coding. You can connect it via the Claude UI (for web/enterprise users) or via a local configuration file (for Claude Desktop developers).

Method A: Via the Claude UI

If you are using Claude's web interface (Enterprise/Team plans with custom connector support enabled):

1. In Claude, navigate to Settings → Integrations (or Connectors depending on your plan tier).
2. Click Add MCP Server or Add custom connector.
3. Paste the Truto MCP URL (https://api.truto.one/mcp/...).
4. Click Add. Claude will instantly perform a handshake, fetch the Mailstep tool schemas, and make them available to your AI assistant.

Method B: Via Manual Configuration File (Claude Desktop)

If you are running Claude Desktop locally or orchestrating a custom agent environment, you must configure the MCP client to use Server-Sent Events (SSE) to talk to Truto's remote endpoint.

Open 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) and add the following:

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

Restart Claude Desktop. The npx command acts as a local proxy, wrapping Truto's remote HTTP JSON-RPC endpoint into a standard stdio/SSE stream that Claude Desktop natively understands.

Security and Access Control

Giving an AI agent unconstrained access to a WMS can lead to disastrous physical consequences (e.g., hallucinating a cancellation for a pallet that is already on a truck). Truto's MCP architecture enforces strict security controls at the server level:

• Method Filtering (config.methods): Restrict the MCP server to only perform specific operations. By passing ["read"], the LLM can query stock levels and track shipments but cannot create orders or resolve issues. Pass ["custom"] to allow state machine transitions like send or resolve.
• Tag Filtering (config.tags): Scope the server to specific resource domains. A server tagged only with ["inventory"] will expose stock tools but hide partner, eshop, and webhooks endpoints from the LLM.
• Require API Token Auth (require_api_token_auth): By default, the cryptographically secure MCP URL acts as a bearer token. For zero-trust environments, enable this flag to force the MCP client to also pass a valid Truto API token in the Authorization header during execution.
• Auto-Expiration (expires_at): Generate ephemeral MCP servers for temporary debugging or short-lived agent sessions. Once the ISO timestamp is reached, the server is automatically destroyed from the distributed KV store, instantly revoking access.

High-Leverage Mailstep Tools for Claude

Truto derives MCP tools directly from the Mailstep API documentation, injecting crucial context (like pagination instructions) directly into the JSON schemas so Claude knows exactly how to use them.

Here are 6 high-leverage hero tools for automating Mailstep workflows:

1. list_all_mailstep_product_stocks

Description: Find and return a set of Product in stock based on search criteria. Truto automatically handles cursor pagination up to 1,000 results per page, ensuring the LLM can navigate large inventory catalogs without parsing raw link headers.

Contextual usage notes: Highly useful for checking availability before attempting to create an expedition. Always instruct the agent to use specific product SKUs or IDs when searching to minimize token bloat.

"Claude, check the Mailstep product stocks and tell me how many units of SKU-8891 are currently available across all warehouses."

2. create_a_mailstep_expedition

Description: Create and insert a new Expedition entity into the database.

Contextual usage notes: This tool simply creates the record. It does not automatically dispatch it to the warehouse floor. Required fields include eshop, warehouse, wms, orderNumber, carrier, and carrierService.

"Create a new Mailstep expedition for Eshop ID 'es-402' to Warehouse 'wh-main'. The order number is ORD-5541. Use carrier 'DHL' and service 'EXPRESS'."

3. update_a_mailstep_expedition_by_id

Description: Update a specific Expedition entity by its ID.

Contextual usage notes: This tool is strictly gated by the WMS state. If the expedition is in fulfillment and has an open issue, the LLM can only update the order note, billing/delivery addresses, and carrier fields. Attempting to change line items will fail.

"Update Mailstep expedition 'exp-8812'. Change the delivery address street to '123 Logistics Way' and update the carrier note to 'Leave at loading dock 4'."

4. mailstep_expeditions_send

Description: Send Expedition to WMS for processing by ID.

Contextual usage notes: This is a custom action method. It transitions the expedition from a draft/created state into the active WMS queue. Once sent, the expedition locks down physical inventory via reservations.

"Now that expedition 'exp-8812' is fully configured, execute the mailstep_expeditions_send tool to push it to the WMS for immediate fulfillment."

5. list_all_mailstep_inbound_issues

Description: Find and return a set of InboundIssue entities based on search criteria.

Contextual usage notes: Inbound issues occur when warehouse staff encounter problems receiving a shipment (e.g., damaged goods, missing manifests). This tool allows Claude to triage warehouse alerts in real-time.

"List all active Mailstep inbound issues created today. Summarize the comments from the warehouse staff regarding damaged freight."

6. mailstep_outbound_issues_resolve

Description: Resolve an OutboundIssue with the chosen resolution.

Contextual usage notes: Essential for unblocking stalled shipments. The LLM must pass a specific resolution string. SHORT_PICK issues accept CANCEL, WAIT_FOR_RESTOCK, or SHIP_INCOMPLETE. CARRIER_ISSUES accept EXPEDITION_UPDATED.

"Resolve the outbound issue on order ORD-5541. The issue is a short pick, so apply the SHIP_INCOMPLETE resolution to dispatch the available items immediately."

For the complete schema definitions and the full inventory of over 100 Mailstep tools—covering transfers, eshop management, partner routing, and stock advices—visit the Mailstep integration page.

Workflows in Action

To understand how an AI agent strings these tools together to orchestrate physical logistics, let's look at two real-world persona scenarios.

Scenario 1: WMS Dispatch & Expedition Troubleshooting

Persona: Logistics Coordinator
Goal: Create a B2B freight order and push it directly to the warehouse floor.

"Claude, create a new expedition in Mailstep for Eshop ID 12 to Warehouse B with order number B2B-991 using carrier code FEDEX. Once created, immediately send it to the WMS for processing. Let me know if it succeeds."

Execution Steps:

1. create_a_mailstep_expedition: Claude constructs the JSON payload with eshop, warehouse, orderNumber, and carrier parameters. It executes the tool and receives the newly generated expedition ID (e.g., exp-991).
2. mailstep_expeditions_send: Claude immediately chains the second tool, passing expedition_id: "exp-991" to trigger the state machine transition.

Result: The user gets a confirmation that the shipment is out of draft mode and is currently in the active warehouse picking queue, entirely bypassing the need to log into the Mailstep UI.

Scenario 2: Resolving Outbound Issues & Reallocating Stock

Persona: E-Commerce Fulfillment Manager
Goal: Unblock an order that the warehouse flagged for missing inventory.

"Check our Mailstep outbound issues for order #4992. If it's stuck because of short picking, resolve it by shipping incomplete, then pull the remaining product stock for the affected SKU so I can alert purchasing."

sequenceDiagram
    participant User as User
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant API as Mailstep API

    User->>Claude: "Check outbound issues for #4992..."
    Claude->>Truto: Call `list_all_mailstep_outbound_issues`<br>(query: order_number=4992)
    Truto->>API: GET /outbound-issues?order=4992
    API-->>Truto: Returns issue ID "iss-771" (SHORT_PICK on SKU-A)
    Truto-->>Claude: Tool result: Issue details

    Claude->>Truto: Call `mailstep_outbound_issues_resolve`<br>(id: "iss-771", resolution: "SHIP_INCOMPLETE")
    Truto->>API: POST /outbound-issues/iss-771/resolve
    API-->>Truto: 200 OK (Status Updated)
    Truto-->>Claude: Tool result: Success

    Claude->>Truto: Call `list_all_mailstep_product_stocks`<br>(query: sku=SKU-A)
    Truto->>API: GET /product-stocks?sku=SKU-A
    API-->>Truto: Returns available stock count (0 units)
    Truto-->>Claude: Tool result: 0 units available

    Claude-->>User: "I've unblocked order #4992 by shipping incomplete. You currently have 0 units of SKU-A left in stock."

Execution Steps:

1. list_all_mailstep_outbound_issues: Claude searches for active issues tied to the specific order string.
2. mailstep_outbound_issues_resolve: Identifying the short pick status, Claude injects the strict string SHIP_INCOMPLETE into the resolution payload to satisfy the Mailstep state machine.
3. list_all_mailstep_product_stocks: Claude queries the remaining inventory for the specific SKU flagged in the issue data.

Result: The warehouse floor is instantly unblocked, the partial order ships, and the manager is alerted to the exact inventory deficit without writing a line of code or searching through fulfillment dashboards.

Final Thoughts: The Reality of B2B Logistics Integrations

Connecting LLMs to supply chain APIs requires ruthless adherence to schema validation and state machines. If an LLM hallucinates an endpoint, invents an invalid enum for an outbound issue, or tries to alter line items on a locked expedition, the physical logistics chain breaks.

Building a custom MCP server means you own the ongoing maintenance of those strict schemas. By utilizing a managed integration architecture like Truto, your engineering team can focus on designing better agentic workflows, while the MCP server dynamically translates LLM intent into valid, authenticated, and secure Mailstep WMS operations.