Connect Malomo to Claude: Sync Shipment Tracking & Webhooks

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

Giving a Large Language Model (LLM) read and write access to a post-purchase fulfillment and shipment tracking platform like Malomo is an engineering challenge. When customer support relies on real-time visibility into shipping statuses, you cannot afford brittle point-to-point scripts. You need a standard, bidirectional interface between Claude's agentic reasoning and Malomo's REST API.

To build this, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's JSON-RPC tool calls and Malomo's specific endpoints. You can either spend weeks building, hosting, and maintaining this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

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

The Engineering Reality of the Malomo 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 Malomo's APIs requires dealing with domain-specific data structures and constraints.

If you decide to build a custom MCP server for Malomo, you own the entire API lifecycle. Here are the specific engineering challenges you will face:

Destructive Array Updates on Orders Malomo handles order shipments via deeply nested arrays. When updating a Malomo order, the shipments field must be passed as a complete list. Any existing carrier and tracking code pairs that are not included in the update payload are actively removed by the API. If you expose this raw schema directly to Claude, the LLM is highly likely to hallucinate a partial payload to "append" a tracking number, inadvertently deleting all historical shipments for that order. A managed MCP server helps mitigate this by surfacing clear, documentation-driven schema instructions directly to the model.

Complex Multi-Key Lookups Finding the right order in Malomo often requires querying against varied identifiers. You might be looking for an internal Malomo id, a merchant's alternate_id, a carrier's tracking_code, or a Shopify number. Building a custom connector means wiring up discrete search logic for every possible index and standardizing the pagination cursors across all of them.

Polling vs. Webhooks and Rate Limit Realities Tracking shipment states requires event-driven architecture. If an LLM attempts to aggressively poll order statuses to detect delivery changes, it will quickly exhaust Malomo's API quotas. Malomo's API prefers webhook subscriptions for state changes.

Furthermore, when you do hit a rate limit, Malomo returns an HTTP 429 Too Many Requests. Truto does not retry, throttle, or apply backoff on rate limit errors automatically. Instead, Truto passes that 429 error directly to the caller, normalizing the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller (your agent framework or Claude client) is strictly responsible for interpreting these headers and executing its own retry and backoff logic.

Instead of building this infrastructure from scratch, you can use Truto to generate an MCP server that normalizes authentication and pagination, exposing Malomo's endpoints as ready-to-use, documentation-gated tools.

Generating a Malomo MCP Server with Truto

Truto derives MCP tools dynamically from the underlying Malomo integration resources and documentation records. A tool only appears in the MCP server if it has a corresponding documentation entry - acting as a quality gate to ensure only well-documented endpoints are exposed to Claude.

You can generate an MCP server for Malomo through two methods: the Truto UI or the Truto REST API.

Method 1: Via the Truto UI

If you are setting up an agent for internal use, the UI is the fastest path.

1. Navigate to the Integrated Accounts page in your Truto dashboard and select your connected Malomo instance.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (e.g., restricting the server to read operations or specific tags).
5. Copy the generated MCP server URL. It will look like this: https://api.truto.one/mcp/a1b2c3d4e5f6...

Method 2: Via the Truto API

If you are building a multi-tenant B2B SaaS product and need to programmatically provision MCP servers for your customers, use the Truto API.

You make an authenticated POST request to the /integrated-account/:id/mcp endpoint. Truto will validate that the integration is AI-ready, generate a cryptographically hashed token, and return a ready-to-use endpoint.

curl -X POST https://api.truto.one/admin/integrated-accounts/YOUR_MALOMO_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Malomo Shipment Agent Server",
    "config": {
      "methods": ["read", "write"],
      "tags": ["orders", "webhooks"]
    }
  }'

The API returns a JSON response containing the persistent MCP token URL. This URL is fully self-contained - it holds the cryptographic token needed to route Claude's requests to the specific Malomo tenant.

{
  "id": "mcp_srv_892nf92",
  "name": "Malomo Shipment Agent Server",
  "config": {
    "methods": ["read", "write"],
    "tags": ["orders", "webhooks"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Connecting the Malomo MCP Server to Claude

Once you have your Truto MCP URL, you need to register it with your Claude environment. Truto exposes a JSON-RPC 2.0 endpoint that any MCP client can connect to.

Method A: Via the Claude UI (Desktop/Web)

If you are using Claude Desktop or Claude Web for Enterprise:

1. Open Claude and navigate to Settings -> Integrations (or Connectors -> Add custom connector depending on your tier).
2. Click Add MCP Server.
3. Paste the Truto MCP URL (https://api.truto.one/mcp/...).
4. Click Add or Save.

Claude will immediately execute an initialize handshake, request the tools/list, and populate its context window with the available Malomo operations.

Method B: Via Manual Config File

If you are running custom agent frameworks, headless Claude implementations, or utilizing the Claude Desktop local configuration, you can inject the server via your claude_desktop_config.json file.

Because Truto provides an SSE (Server-Sent Events) endpoint, you utilize the official @modelcontextprotocol/server-sse transport.

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

Restart Claude to apply the changes. The model now has direct, authenticated access to your Malomo instance.

Core Malomo MCP Tools for AI Agents

Truto automatically translates Malomo's endpoints into descriptive, snake_case tools. Query parameters and body payloads share a flat input namespace, which Truto parses and routes based on JSON schema documentation.

Here are the critical tools you will use to automate shipment tracking and webhook management.

list_all_malomo_orders

Retrieves a paginated list of orders from Malomo. This is the primary discovery tool for your AI agents when beginning an investigation. It allows filtering by alternate_id, tracking_code, number, or customer_email. Truto automatically injects limit and next_cursor properties, explicitly instructing Claude to pass cursor values back unchanged to navigate pagination seamlessly.

"Find all Malomo orders associated with the customer email help@example.com and return their internal IDs and tracking codes."

update_a_malomo_order_by_id

Updates an existing Malomo order. Because the Malomo API treats the shipments array destructively, this tool requires strict attention. If an agent wants to add a new tracking code, it must first read the existing shipments, append the new data, and send the complete list back.

"Update Malomo order ID 89123. The customer needs a new shipment added. Keep the existing USPS shipment in the array, and add this new FedEx shipment with tracking code 123456789044."

get_single_malomo_orders_by_tracking_code_by_id

A specialized lookup tool that bypasses internal order IDs entirely, allowing an agent to query Malomo directly using a carrier tracking code. This is invaluable for support bots that only receive raw tracking numbers from frustrated customers.

"Look up the Malomo order linked to the tracking code 1Z9999999999999999 and tell me its current delivery status."

list_all_malomo_order_events

Retrieves the complete lifecycle history of a specific order. Agents use this tool to build a chronological timeline of an order - from fulfillment, to carrier pickup, to transit exceptions, to final delivery.

"Pull all the tracking events for order ID 89123. Summarize the timeline and identify if the package was delayed at any specific sorting facility."

create_a_malomo_webhook

Creates a new webhook subscription in Malomo to receive asynchronous event notifications. Instead of polling endpoints, agents can configure Malomo to push updates for specific topics (like shipment.delivered or order.created) directly to your internal ingestion URLs.

"Create a new active Malomo webhook. Set the topic to 'shipment.exception' and point the URL to https://api.mycompany.com/webhooks/malomo-alerts."

For the complete inventory of Malomo tools and detailed JSON Schema definitions, refer to the Malomo integration page.

Workflows in Action

Once connected, Claude can orchestrate multi-step API workflows that previously required custom code. Here is how specific personas utilize the Malomo MCP server.

Scenario 1: Customer Support Tracing a Lost Shipment

A support agent is dealing with a customer who claims their package never arrived, but the customer only provided their email address. The AI agent needs to locate the order, check the tracking history, and identify where the failure occurred.

"A customer emailed us from sarah.smith@example.com saying their recent order is missing. Find their latest Malomo order, check the tracking events, and tell me exactly where the package was last scanned."

Tool Sequence:

1. list_all_malomo_orders (Querying with customer_email: "sarah.smith@example.com" to retrieve the internal id).
2. list_all_malomo_order_events (Passing the retrieved order_id to pull the chronological scan data).

Outcome: Claude identifies the order, parses the event array, and reports back: "I found order #1042 for Sarah Smith. According to the events, the package was scanned at the local distribution center on Tuesday, but an 'Address Undeliverable' exception was logged today at 8:14 AM."

Scenario 2: DevOps Engineer Configuring Event Webhooks

A DevOps engineer needs to ensure that the internal alerting system receives real-time notifications whenever a shipment goes into a "Return to Sender" state.

sequenceDiagram
    participant User as DevOps Engineer
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Malomo as Malomo API
    
    User->>Claude: "Check our active Malomo webhooks..."
    Claude->>Truto: tools/call (list_all_malomo_webhooks)
    Truto->>Malomo: GET /webhooks
    Malomo-->>Truto: 200 OK (List of webhooks)
    Truto-->>Claude: JSON response
    Claude->>User: "You have two active webhooks..."
    
    User->>Claude: "Create a new one for shipment exceptions..."
    Claude->>Truto: tools/call (create_a_malomo_webhook)
    Truto->>Malomo: POST /webhooks {topic: "shipment.exception"}
    Malomo-->>Truto: 201 Created
    Truto-->>Claude: Webhook ID
    Claude->>User: "Webhook successfully configured."

"List all of our active Malomo webhooks. If we don't have one set up for the 'shipment.exception' topic, create one pointing to https://alerts.internal.com/malomo."

Tool Sequence:

1. list_all_malomo_webhooks (Claude inspects the active array of webhooks).
2. create_a_malomo_webhook (Claude determines the topic is missing and constructs the POST payload with the provided URL).

Outcome: Claude audits the existing infrastructure, identifies the gap, and dynamically provisions the new webhook without the engineer writing a single cURL request.

Security and Access Control

Exposing B2B SaaS data to an LLM requires strict governance. Truto's MCP architecture provides multiple layers of access control, enforced at the token level.

• Method Filtering: You can restrict a Malomo MCP server to specific operation types using the config.methods array. Setting this to ["read"] ensures the agent can query orders and events, but cannot perform destructive updates or create webhooks.
• Tag Filtering: Limit the server's scope by functional area. Using config.tags = ["orders"] hides all webhook and customer management tools, exposing only shipment and order operations to the LLM.
• Extra Authentication (require_api_token_auth): By default, possessing the MCP URL is enough to invoke tools. Setting require_api_token_auth: true forces the MCP client to also pass a valid Truto API token in the Authorization header, adding a mandatory secondary authentication layer.
• Automatic Expiration (expires_at): You can generate ephemeral MCP servers for temporary investigations. Setting an ISO datetime in the expires_at field schedules an automatic cleanup alarm. Once expired, the server endpoint is destroyed, terminating the model's access instantly.

Connecting Malomo to Claude via a managed MCP server removes the boilerplate of building API wrappers. Instead of dealing with destructive array structures, pagination cursors, and raw HTTP 429 errors manually, your engineering team can focus on writing better agent prompts and orchestrating complex support resolutions.