Connect Linnworks to Claude: Sync Stocks and Sales Channel Listings

If you need to connect Linnworks to Claude to automate e-commerce operations, sync complex inventory catalogs, or oversee multi-channel order fulfillment, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's LLM function calling and the Linnworks REST API.

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-linnworks-to-chatgpt-manage-inventory-orders-and-shipping/ or explore our broader architectural overview on /connect-linnworks-to-ai-agents-automate-returns-fba-and-logistics/.

Giving a Large Language Model (LLM) read and write access to an enterprise resource planning and inventory management ecosystem like Linnworks is an engineering challenge. You must handle token lifecycles, map massive e-commerce JSON schemas to MCP tool definitions, and deal with strict API quotas. Every time Linnworks updates an endpoint, 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 Linnworks, connect it natively to Claude Desktop, and execute complex e-commerce workflows using natural language.

The Engineering Reality of the Linnworks 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 highly specific e-commerce APIs is difficult. Linnworks manages physical inventory across warehouses, virtual stock levels across sales channels, and complex picking workflows. Its API reflects that domain complexity.

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

Dynamic Field Updates and Nested Object Payloads Updating inventory in Linnworks is not a simple matter of sending a flat JSON payload. Endpoints like the one used to update an inventory item field expect dynamic keys mapping updated field names to updated field value objects. An LLM has no inherent context on how to construct these dynamic objects. A managed MCP server exposes these endpoints as tightly scoped tools with explicitly defined body_schemas derived from the vendor's documentation, guiding the model to generate the exact payload structure Linnworks demands.

Strict UUID Enforcement Across Domains Linnworks relies heavily on internally generated UUIDs rather than human-readable IDs. An order is identified by a pkOrderId, a stock item by a pkStockItemId, and a warehouse transfer by a pkTransferId. An LLM cannot guess these. You must provide tools that allow the model to search for human-readable references (like an order number or SKU), extract the UUID from the response, and chain it into the next tool call.

Rate Limits and 429 Handling Linnworks enforces strict rate limits on heavy operations, such as creating or modifying orders (often capped at 150 requests per minute). When building an LLM agent, it is critical to understand how these limits are handled.

Important factual note: Truto does not retry, throttle, or apply backoff on rate limit errors. When Linnworks returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The caller - whether that is Claude Desktop or your own agent orchestration framework - is strictly responsible for implementing retry and exponential backoff logic.

Generating the Linnworks MCP Server

Truto's MCP server feature turns any connected Linnworks integration into an MCP-compatible tool server. Tool generation is dynamic and documentation-driven. Rather than hand-coding tool definitions, Truto derives them from Linnworks' API resource definitions and JSON Schema descriptions.

You can create an MCP server for Linnworks using either the Truto UI or the API.

Method 1: Via the Truto UI

For teams managing agents manually, the UI provides a quick configuration flow:

1. Navigate to the Integrated Accounts page in your Truto dashboard and select your connected Linnworks account.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (e.g., restrict to read methods only, or filter by specific tool tags like inventory).
5. Copy the generated MCP server URL. This URL contains a cryptographic token that securely maps to the integrated account.

Method 2: Via the API

For automated workflows or multi-tenant agent platforms, you can programmatically provision MCP servers.

Make a POST request to /integrated-account/:id/mcp with your desired configuration:

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

The API returns a secure, ready-to-use URL:

{
  "id": "mcp-7f8a9b2c",
  "name": "Linnworks Inventory Assistant",
  "config": { "methods": ["read", "write"], "tags": ["inventory", "orders"] },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67g8h..."
}

Connecting the MCP Server to Claude

Once you have the generated URL, connecting it to Claude requires zero additional coding. The server fully complies with the JSON-RPC 2.0 specification for MCP.

Method A: Via the Claude UI

If you are using an MCP-enabled interface (like Claude for Enterprise or similar UI wrappers):

1. Open Settings -> Integrations (or Connectors).
2. Click Add MCP Server.
3. Paste the Truto MCP URL generated in the previous step.
4. Click Add. Claude will automatically execute the initialize and tools/list handshake to discover the Linnworks tools.

Method B: Via the Manual Configuration File

If you are using Claude Desktop locally, you configure the server via the claude_desktop_config.json file. Because Truto's managed MCP runs over HTTP POST (SSE), you use the official MCP SSE transport utility to proxy the connection.

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

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

Restart Claude Desktop. The model will immediately have access to the specific Linnworks API operations you permitted.

Linnworks Hero Tools for AI Agents

Linnworks has hundreds of endpoints. Exposing all of them to an LLM without curation can lead to context window bloat and hallucinations. Truto dynamically maps Linnworks API resources into targeted, snake_case tools with strictly typed schemas.

Here are the highest-leverage tools available for your Claude agent. For the complete list of generated tools and their required schemas, check the Linnworks Integration Page.

list_all_linnworks_inventory_get_stock_levels

Retrieves the core stock level report from Linnworks. It returns arrays of stock item levels including ItemId, SKU, Level, MinimumLevel, InOrderBook, and AvailableStock. This is the fundamental tool for any agent doing inventory auditing.

"Claude, pull the current stock levels for all inventory items. Identify any items where the AvailableStock has dropped below the MinimumLevel and format them into a markdown table."

list_all_linnworks_orders_get_orders

Lists open orders in Linnworks based on filters. It returns full open-order objects including OrderId (UUID), NumOrderId, CustomerInfo, TotalsInfo, and the nested Items array. The model must use this tool to find an order's UUID before attempting to process or refund it.

"Find all open orders placed in the last 24 hours that are currently stuck in UNPAID status. Give me the customer names and the total order values."

create_a_linnworks_orders_process_order

Advances an order through the processing workflow, moving it out of open status. It requires the pkOrderId and returns a ProcessOrderResult object describing the outcome.

"Process the order with ID '550e8400-e29b-41d4-a716-446655440000'. If it fails, report the exact error message from the response."

update_a_linnworks_inventory_update_inventory_item_level_by_id

Updates stock level records for a stock item and any related composite items. This is a critical write operation for making manual inventory adjustments or reconciling discrepancies found during a warehouse audit.

"Update the stock level for item ID '123e4567-e89b-12d3-a456-426614174000'. The new level found during the cycle count is 45 units."

create_a_linnworks_returns_refunds_create_refund

Initiates a refund in Linnworks for approval. This tool creates the record using a JSON refund request body, pushing it into the actionable refunds queue. It is heavily utilized in automated customer support workflows.

"The customer for order '999e8400-e29b-41d4-a716-446655441111' requested a return. Initiate a refund for the full item amount, leaving the shipping cost intact."

create_a_linnworks_warehouse_transfer_create_transfer

Creates a new warehouse transfer request with a system-generated default reference number. It returns the created WarehouseTransfer object. Use this to automatically route stock between fulfillment centers when an LLM detects regional imbalances.

"We have excess stock in Location A and a shortage in Location B. Create a draft warehouse transfer to move 100 units of SKU 'WIDGET-01' from Location A to Location B."

Workflows in Action

Exposing individual tools is only the first step. The real power of MCP is enabling Claude to autonomously sequence multiple API calls to solve complex supply chain and customer service problems.

Scenario 1: Automated Low Stock Detection and Warehouse Rebalancing

Imagine a supply chain manager asking Claude to audit regional inventory and fix imbalances.

"Check our stock levels. If any SKU is below its minimum level in the East Coast warehouse, check if the West Coast warehouse has excess stock. If it does, create a draft warehouse transfer to balance the inventory."

Execution Steps:

1. Tool Call: list_all_linnworks_inventory_get_stock_levels (Claude requests stock data for the East Coast location). It identifies that SKU-992 has an AvailableStock of 5, while its MinimumLevel is 20.
2. Tool Call: list_all_linnworks_inventory_get_stock_levels (Claude queries the West Coast location for SKU-992). It discovers 150 units in stock.
3. Tool Call: list_all_linnworks_locations_get_locations (Claude fetches the system IDs for both locations to construct the transfer payload).
4. Tool Call: create_a_linnworks_warehouse_transfer_create_transfer (Claude creates a transfer request from West Coast to East Coast for 50 units).

sequenceDiagram
    participant User as User
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant Upstream as "Upstream API (Linnworks)"

    User->>Claude: "Audit stock and rebalance East Coast..."
    Claude->>MCP: call list_all_linnworks_inventory_get_stock_levels
    MCP->>Upstream: GET /api/Inventory/GetStockLevel
    Upstream-->>MCP: [SKU-992 low in East]
    MCP-->>Claude: JSON Array
    Claude->>MCP: call list_all_linnworks_inventory_get_stock_levels
    MCP->>Upstream: GET /api/Inventory/GetStockLevel
    Upstream-->>MCP: [SKU-992 high in West]
    MCP-->>Claude: JSON Array
    Claude->>MCP: call create_a_linnworks_warehouse_transfer_create_transfer
    MCP->>Upstream: POST /api/WarehouseTransfer/CreateTransfer
    Upstream-->>MCP: 200 OK (TransferId: 12345)
    MCP-->>Claude: Transfer Created
    Claude-->>User: "Draft transfer #12345 created for 50 units."

Scenario 2: Autonomous Customer Return Processing

Customer service agents spend hours verifying order statuses and issuing manual refunds. Claude can automate this entirely.

"A customer emailed about order number #100452. They want to return their item. Check if the order is delivered, verify refund options, and if eligible, initiate a refund."

Execution Steps:

1. Tool Call: get_orders_get_open_order_id_by_order_or_reference_id_by_id (Claude converts the human-readable order number #100452 into a Linnworks UUID, e.g., 888a...).
2. Tool Call: list_all_linnworks_processed_orders_get_order_infos (Claude verifies the order is shipped and processed).
3. Tool Call: list_all_linnworks_processed_orders_get_refunds_options (Claude checks which automated refund types are possible for this specific channel).
4. Tool Call: create_a_linnworks_returns_refunds_create_refund (Claude submits the refund request to the Actionable Refunds screen).

Security and Access Control

Giving an LLM access to a live Linnworks environment requires strict governance. If an agent hallucinates a stock deletion payload, it could disrupt fulfillment operations. Truto provides several mechanisms to lock down the MCP server environment:

• Method Filtering (methods): When creating the MCP server, you can pass "methods": ["read"]. This physically filters out any create, update, or delete tools from the server. Claude will only be able to view inventory, not modify it.
• Tag Filtering (tags): You can restrict the MCP server to specific domains. Passing "tags": ["inventory"] ensures the agent cannot touch orders or picking endpoints.
• Expiration (expires_at): You can create ephemeral MCP servers for temporary contractor access or limited-time audit agents. The underlying Cloudflare KV infrastructure automatically purges the token upon expiration.
• Dual Authentication (require_api_token_auth): By default, possessing the MCP URL grants access. By setting require_api_token_auth: true, Truto enforces a secondary check requiring the caller to pass a valid Truto API bearer token. This ensures that even if the MCP URL leaks in a configuration file, the tools remain secure.

Architecting for Scale

Building an MCP server from scratch means building a translation layer, maintaining dynamic JSON Schema generation for every Linnworks endpoint, and managing token expiration infrastructure.

By leveraging a platform built to expose API resources dynamically, you eliminate the maintenance burden. Truto handles the translation of Linnworks' extensive e-commerce capabilities into standardized, LLM-ready tools, leaving your team free to focus on prompting and orchestration logic rather than plumbing.

Ready to put AI to work on your supply chain?