Connect Roserocket to Claude: Manage Shipping Boards & External IDs

If you are orchestrating logistics, your Transportation Management System (TMS) is the source of truth for every order, dispatch event, and shipping manifest. Connecting Roserocket to Claude allows your internal AI agents to look up external ERP IDs, read shipping board states, and append real-time dispatch events to active loads. You can either build and maintain a custom translation layer to expose these APIs to Claude, or use a managed integration platform like Truto to dynamically generate a secure, authenticated Model Context Protocol (MCP) server. If your team uses ChatGPT, check out our guide on connecting Roserocket to ChatGPT or explore our broader architectural overview on connecting Roserocket to AI Agents.

Giving a Large Language Model (LLM) raw API access to a sprawling logistics platform is an engineering challenge. You must handle OAuth lifecycles, parse deeply nested generic object models, and manage the vendor's specific rate limits. Every time an endpoint drifts, your integration code breaks. This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Roserocket, connect it natively to Claude, and execute complex shipping workflows using natural language.

The Engineering Reality of the Roserocket API

A custom MCP server is a self-hosted API gateway that translates an LLM's JSON-RPC tool calls into vendor-specific HTTP requests. While the MCP standard handles the model-facing interface, the backend engineering requires wrangling the vendor's specific architecture. Roserocket's API presents three distinct challenges for AI integration.

Polymorphic Object Architecture Unlike standard REST APIs with distinct endpoints for /orders, /customers, or /invoices, Roserocket heavily utilizes a platform model object architecture. You interact with a generic /objects endpoint and must filter by object_key (e.g., Customer, Order, Task). If you expose this raw architecture to Claude, the model will struggle to construct the correct nested JSON payloads and will frequently hallucinate object keys. A managed MCP server abstracts this, dynamically injecting the correct context and required fields into the schemas the LLM receives, ensuring requests are properly formed before they hit the upstream API.

Board and Widget View States Roserocket is highly visual. Its data is often organized into "boards" and "widgets" which dictate what a dispatcher sees on their screen. Extracting operational data often requires interacting with these view state representations rather than just raw database rows. Fetching a board returns a complex schema of widgets, widgetToOpen, and locations. Your MCP server must properly map these nested UI-driven structures so Claude can interpret the dispatcher's current view.

External ID Resolution and ERP Syncing Roserocket operates in a multi-system ecosystem, syncing heavily with ERPs and accounting platforms. Resolving an order often involves searching not by Roserocket's internal UUID, but by an external system ID. This requires specific endpoints to upsert or fetch records via their external ID. If your MCP server cannot differentiate between internal ID mutations and external ID resolutions, Claude will fail to sync data across your tech stack.

Strict Rate Limiting Behavior When making high-frequency calls - common in agentic loops where Claude is cross-referencing multiple orders - you will encounter HTTP 429 Too Many Requests errors. Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Roserocket API returns a 429, Truto passes that error directly to the caller. However, Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). The caller (or your multi-agent framework) is entirely responsible for reading these headers and implementing its own retry and backoff logic. Truto will not absorb rate limits on your behalf.

Instead of building out all this normalization and state management from scratch, you can use Truto to generate an MCP server that exposes Roserocket's platform objects and events as ready-to-use LLM tools.

How to Generate a Roserocket MCP Server with Truto

Truto creates MCP tools dynamically based on your integration's configured resources and schemas. The system verifies your OAuth or API key credentials, provisions a secure token, and generates an MCP server URL. You can provision this server via the Truto dashboard or programmatically via the API.

Method 1: Via the Truto UI

For internal tooling and quick prototyping, the Truto dashboard provides a one-click server generation flow:

1. Log into your Truto environment and navigate to the integrated account page for your Roserocket connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Configure the server parameters (name, allowed methods, allowed tags, and expiration date).
5. Click Save and copy the generated MCP Server URL (e.g., https://api.truto.one/mcp/abc123def456).

Method 2: Via the API

If you are provisioning MCP access dynamically for your users, you should use the Truto API. The API validates that the Roserocket integration has documented tools available, generates a cryptographically hashed token, and provisions the server URL.

Make an authenticated POST request to /integrated-account/:id/mcp:

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": "Roserocket Dispatch Server",
    "config": {
      "methods": ["read", "write"],
      "tags": ["logistics", "events"]
    }
  }'

Response:

{
  "id": "mcp_abc123",
  "name": "Roserocket Dispatch Server",
  "config": { 
    "methods": ["read", "write"], 
    "tags": ["logistics", "events"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

This URL acts as the single connection string required to interact with your specific Roserocket instance.

How to Connect the MCP Server to Claude

Once you have the Truto MCP server URL, connecting it to Claude requires zero additional coding. You can plug it into Claude Desktop for local AI workflows, or configure it via the CLI for custom application development.

Via the Claude UI (Desktop or Web)

Anthropic natively supports MCP custom connectors in the Claude application:

1. Copy the MCP server URL generated by Truto.
2. Open Claude and navigate to Settings -> Integrations -> Add MCP Server (or Settings -> Connectors -> Add custom connector depending on your plan tier).
3. Paste the Truto MCP URL into the configuration field and click Add.

Claude will immediately execute an MCP initialize handshake, request the tools/list array, and make all Roserocket tools available for your next prompt.

Via Manual Config File (Claude CLI / Custom Clients)

If you are running Claude Desktop locally or testing via an MCP client inspector, you can configure the server using standard Server-Sent Events (SSE) architecture. Modify your claude_desktop_config.json file to include the Truto endpoint:

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

Restart Claude Desktop. The connection will establish via HTTP POST, relying purely on the URL token for routing and authentication.

Hero Tools for Roserocket

Truto automatically maps the Roserocket API surface into discrete MCP tools. Instead of exposing one massive, complex generic endpoint, the schema parsing separates capabilities logically. Here are the core tools you should focus on for logistics workflows.

list_all_roserocket_boards

This tool allows Claude to retrieve the exact board views configured in Roserocket. It returns the structural layout, including widget types and the locations where items reside, essentially letting the LLM "see" the UI configuration.

"Fetch the active 'Outbound Freight' board in Roserocket and tell me which widgets are currently configured on it for the 'order' object type."

list_all_roserocket_objects

The primary search tool for Roserocket's platform model. Because Roserocket uses polymorphic objects, this tool requires the LLM to specify the objectKey (e.g., Customer, Order, Task) in the request body to scope the results. It is the workhorse for querying operational data.

"Search for all open records in Roserocket with the object key 'Task' that were created today, and summarize their current statuses."

get_single_roserocket_objects_external_by_id

Essential for multi-system architectures. When your CRM or ERP references a shipping record via its own internal ID, Claude can use this tool to fetch the corresponding Roserocket object without needing the internal Roserocket UUID.

"Lookup the Roserocket shipment details for the order that has the external ERP ID 'SAP-10992'."

create_a_roserocket_event

Use this tool to log activities, updates, or status changes against a specific record. It requires the recordId, the boardId the event is tied to, and the event type.

"Create a new status event on Roserocket order 99281 marking it as 'Delayed at border'. Attach this to the main dispatch board."

roserocket_user_groups_search

Allows the LLM to look up organizational units, dispatch teams, or driver groups. It returns the ID, name, and description of the user groups, which is required before updating group memberships or routing tasks.

"Search for the Roserocket user group named 'LTL Dispatchers' and retrieve its group ID."

list_all_roserocket_objects_autocomplete

A highly optimized search endpoint for quickly resolving text to specific platform records. It is much faster than the standard object list for loose text matches, allowing Claude to find records based on partial string inputs.

"Run an autocomplete search in Roserocket for any 'Customer' object matching the name 'Acme Corp' and return the primary IDs."

For a complete list of all supported endpoints and their underlying JSON schemas, review the Roserocket integration page.

Workflows in Action

When Claude is equipped with Roserocket MCP tools, it can orchestrate complex, multi-step logistics operations autonomously.

Resolving an External ERP Order to a Board View

Often, a customer success agent only has an ERP order number, but needs to know what the dispatch team sees on their Roserocket board.

"Find the Roserocket order linked to external ERP ID 'ERP-992' and check its recent events."

1. Claude calls get_single_roserocket_objects_external_by_id passing object_key: "Order" and id: "ERP-992".
2. The Truto MCP server translates this into the Roserocket external lookup endpoint and returns the internal Roserocket object UUID.
3. Claude parses the UUID and calls list_all_roserocket_events using the newly retrieved record_id.
4. Claude summarizes the timeline of dispatch events and presents it to the user.

sequenceDiagram
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant Roserocket as Roserocket API
    Claude->>MCP: call get_single_roserocket_objects_external_by_id<br>{"id": "ERP-992"}
    MCP->>Roserocket: GET /objects/external/Order/ERP-992
    Roserocket-->>MCP: 200 OK<br>{"id": "rr-uuid-773"}
    MCP-->>Claude: Returns Object ID
    Claude->>MCP: call list_all_roserocket_events<br>{"record_id": "rr-uuid-773"}
    MCP->>Roserocket: GET /events?record_id=rr-uuid-773
    Roserocket-->>MCP: 200 OK<br>[Array of Events]
    MCP-->>Claude: Returns Event History

Dispatcher Group Audit & Notification

IT and Operations teams frequently need to audit group access and leave an audit trail on operational boards.

"Find the 'Night Dispatch' user group, list its members, and log an event on the active shift board that the roster was audited today."

1. Claude calls roserocket_user_groups_search with the search term 'Night Dispatch'.
2. Claude extracts the group_id from the result and calls list_all_roserocket_user_group_members.
3. After reviewing the members, Claude calls list_all_roserocket_boards to find the ID of the 'active shift' board.
4. Finally, Claude calls create_a_roserocket_event, passing the board ID and a JSON payload documenting the audit results.

Security and Access Control

Exposing an enterprise TMS to an LLM requires strict boundary controls. Truto enforces security at the token layer, allowing you to heavily restrict what the MCP server can do.

• Method Filtering: By defining config.methods: ["read"] during server creation, you completely disable mutation capabilities. The LLM will only see list and get operations, guaranteeing it cannot accidentally update dispatch statuses.
• Tag Filtering: You can restrict tools by functional area. Setting config.tags: ["events"] ensures the server only exposes event-related tools, hiding user administration and billing objects entirely.
• Require API Token Auth: By setting config.require_api_token_auth: true, possession of the MCP URL is no longer sufficient. The connecting client must also pass a valid Truto API token in the Authorization header, preventing unauthorized access if the URL is leaked.
• Expiring Access: Setting an expires_at ISO datetime attaches a strict Time-To-Live (TTL) to the server. Once expired, edge storage records are purged, and the URL immediately returns a 401 Unauthorized.

Connecting Claude to Roserocket transforms how your logistics teams operate. Instead of clicking through dozens of nested board widgets or manually cross-referencing ERP IDs in external systems, operators can ask their AI agent for immediate answers. By utilizing a managed MCP infrastructure layer, your engineering team avoids the maintenance burden of tracking API deprecations, fighting complex polymorphic schemas, and building rate limit handling. You focus entirely on building high-value dispatch orchestration flows, while the protocol layer handles the rest.