Connect Onfleet to Claude: Orchestrate Delivery and Fleet Logistics

If you need to connect Onfleet to Claude to automate route optimization, manage active driver schedules, or oversee complex dispatch operations, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and Onfleet's specialized 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 connecting Onfleet to ChatGPT or explore our broader architectural overview on connecting Onfleet to AI Agents.

Giving a Large Language Model (LLM) read and write access to a live delivery logistics engine is an engineering challenge. You must handle complex state machines for routing math, deal with strict concurrency limits on task assignment arrays, and map massive JSON payloads to valid tool definitions. Every time Onfleet updates a resource or introduces new batching constraints, you have to update your server code.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Onfleet, connect it natively to Claude Desktop, and execute complex dispatch and fleet management workflows using natural language.

The Engineering Reality of the Onfleet 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 over JSON-RPC 2.0, the reality of implementing it against a logistics platform like Onfleet requires deep domain knowledge. Onfleet is built to manage real-time worker locations, complex routing algorithms, and split-second dispatch changes.

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

The Container Assignment Pattern and Concurrency Limits In Onfleet, you do not simply PATCH a task to assign it to a driver. Task assignments are managed via "Containers" (which represent the ordered task queue for an organization, team, or worker). To assign or reorder a task, you must update the worker's container by supplying the complete, ordered array of task IDs. If you send an incomplete array, existing tasks are removed from the driver's queue. Furthermore, containers hold a hard limit of 10,000 assigned tasks. Because multiple dispatchers or automated systems might attempt to modify a container simultaneously, Onfleet strictly enforces concurrency control; concurrent mutations will return 412 Precondition Failed errors. An LLM must be explicitly instructed on this pattern, and your server must handle the array state correctly.

Asynchronous Route Optimization State Machines Generating routes in Onfleet is not a synchronous CRUD operation. Route math is computationally heavy. You must initialize an optimization task (POST /optimizations), capture the returned optimizationId, poll the status endpoint until the math is complete, and then explicitly apply the results to commit the assignments to drivers. If an LLM attempts to fire-and-forget an optimization, your drivers will never receive their routes. An MCP server must expose these discrete lifecycle steps as separate, logically chained tools.

Rate Limits and 70-Second Synchronous Timeouts Onfleet enforces strict rate limits depending on your tier. It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors. When Onfleet returns an HTTP 429, Truto passes that error directly to the caller. However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The caller (or the LLM agent framework) is fully responsible for reading these headers and executing the retry/backoff logic. Additionally, large synchronous operations (like massive bulk task creation or querying an entire organization's workforce without filters) can hit a 70-second internal Onfleet timeout. For large datasets, your tools must guide the LLM to use the async batch endpoints.

Creating the Onfleet MCP Server

Truto eliminates the need to build a custom Express or fastMCP server. It dynamically generates tools by reading the Onfleet API documentation and OpenAPI-equivalent schemas, applying filters, and wrapping the operations in an MCP-compliant JSON-RPC endpoint.

You can generate an Onfleet MCP server in two ways: via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

This is the fastest method for internal operational setups.

1. Navigate to your Truto dashboard and locate the Onfleet integrated account.
2. Click into the integrated account and select the MCP Servers tab.
3. Click Create MCP Server.
4. Define your configuration. You can optionally filter tools by selecting specific HTTP methods (e.g., read, write) or selecting specific integration tags (e.g., dispatch, routing).
5. Click Create.
6. Copy the generated MCP Server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...). Keep this secure; this URL acts as the authentication boundary for the connection.

Method 2: Via the Truto API

For platform teams building automated provisioning pipelines, you can generate MCP servers programmatically.

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

curl -X POST https://api.truto.one/integrated-account/<ONFLEET_ACCOUNT_ID>/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Claude Dispatch Agent MCP",
    "config": {
      "methods": ["read", "write", "custom"],
      "tags": []
    }
  }'

The Truto API will validate that tools exist for your configuration, hash a secure token into a distributed key-value store, and return a payload containing your server URL:

{
  "id": "abc-123",
  "name": "Claude Dispatch Agent MCP",
  "config": { "methods": ["read", "write", "custom"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

Connecting the MCP Server to Claude

Once you have your Truto MCP URL, providing Claude with access to Onfleet takes less than a minute.

Method A: Via the Claude UI

If you are using Claude Desktop or an enterprise workspace that supports visual connector management:

1. Open Claude Settings.
2. Navigate to Integrations or Connectors.
3. Click Add MCP Server or Add Custom Connector.
4. Paste the Truto MCP URL and provide a name (e.g., "Onfleet Logistics").
5. Save. Claude will immediately send an initialize request and map the available Onfleet tools.

Method B: Via the claude_desktop_config.json File

For local development or standard Claude Desktop installations, you must configure the MCP server via the JSON configuration file. Because Truto provides a standard SSE (Server-Sent Events) endpoint, you will use the official @modelcontextprotocol/server-sse wrapper to connect.

Open your claude_desktop_config.json file (typically located in ~/Library/Application Support/Claude/ on macOS or %APPDATA%\Claude\ on Windows) and add the following:

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

Restart Claude Desktop. The "hammer" icon will appear, indicating that the Onfleet tools are successfully loaded.

Hero Tools for Onfleet Logistics

Truto automatically generates tools for the entire Onfleet API surface area. Rather than generic CRUD operations, these tools are highly specialized for fleet logistics.

Here are 6 high-leverage hero tools your agents can use immediately.

1. create_a_onfleet_task

Creates a task in Onfleet. You can pass either existing destination/recipient IDs or provide inline objects (parsed address strings, phone numbers) which Onfleet will automatically convert into persistent records during task creation. Timestamps must be Unix time in milliseconds.

"Create a new dropoff task for John Doe at 123 Main St, San Francisco. Note that the gate code is 4321. The task must be completed after tomorrow at 9 AM PST."

2. update_a_onfleet_container_by_id

Updates an Onfleet container to assign or reorder tasks for a worker, team, or organization. You must provide the container_type (e.g., WORKER) and the id, along with the full ordered array of task IDs.

"Reassign task ID 98765abcde to worker ID 12345xyz by prepending it to their current container task array."

3. create_a_onfleet_optimization

Initializes a standard Onfleet route optimization job that calculates the most efficient paths for a team of workers. Requires parameters like tasks, teams, date, mode, and maxTasksPerRoute.

"Initialize a route optimization for team ID team_beta for tomorrow. Maximize efficiency for driving mode, limit it to 40 tasks per route, and respect the drivers' default schedules."

4. onfleet_optimizations_apply_results

Applies the results of a previously initialized route optimization, locking in the calculated routes and committing the assignments to the drivers' containers.

"Apply the route optimization results for optimization ID opt_888999."

5. list_all_onfleet_worker_locations

Retrieves the real-time, last known locations of your active workers. Crucial for dynamic dispatching and finding the closest driver to an urgent pickup.

"Fetch the current locations of all active workers so I can find who is closest to coordinates [37.7749, -122.4194]."

6. list_all_onfleet_search_tasks

Searches Onfleet tasks by specific metadata criteria. Accepts an array of exact-match query objects (name, type, value). Useful for finding tasks tied to internal order IDs or CRM reference numbers.

"Search for the Onfleet task where the metadata key 'internal_order_id' exactly matches 'ORD-99120'."

To view the complete inventory of available Onfleet tools and their full JSON schema definitions, visit the Onfleet integration page.

Workflows in Action

Providing Claude with isolated tools is just the foundation. The real value of MCP is allowing the LLM to string these operations together to autonomously manage complex logistics scenarios.

Scenario 1: Autonomous Fleet Dispatch and Optimization

User Prompt:

"Get all unassigned tasks for the 'Downtown' team created today. If there are more than 10, initialize a route optimization for the team for tomorrow morning. Monitor the optimization, and once it is complete, apply the results to dispatch the drivers."

How the Agent Executes This:

1. list_all_onfleet_team_tasks: Claude fetches the unassigned tasks for the specific team ID to determine the volume.
2. create_a_onfleet_optimization: Seeing sufficient volume, Claude initializes the routing math, passing the team ID, task list, and configuration constraints. It captures the returned optimizationId.
3. get_single_onfleet_optimization_by_id: Claude polls the status of the optimization until the routing engine returns a success state.
4. onfleet_optimizations_apply_results: Claude executes the final step, assigning the optimized routes to the drivers' containers.

sequenceDiagram
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Onfleet as Onfleet API
    
    Claude->>Truto: Call create_a_onfleet_optimization
    Truto->>Onfleet: POST /optimizations
    Onfleet-->>Truto: 201 Created (ID: opt_123)
    Truto-->>Claude: Return optimization ID
    
    loop Poll Status
        Claude->>Truto: Call get_single_onfleet_optimization_by_id
        Truto->>Onfleet: GET /optimizations/opt_123
        Onfleet-->>Truto: 200 OK (Status: processing/complete)
        Truto-->>Claude: Return status
    end
    
    Claude->>Truto: Call onfleet_optimizations_apply_results
    Truto->>Onfleet: POST /optimizations/opt_123/apply
    Onfleet-->>Truto: 204 No Content
    Truto-->>Claude: Optimization applied

Scenario 2: Real-Time Exception Handling

User Prompt:

"A customer just called saying they put the wrong delivery address for order ID 'ECOM-554'. Find the active task, check which worker has it, get the worker's current location, and if they haven't completed it yet, update the task destination to 999 Market St."

How the Agent Executes This:

1. list_all_onfleet_search_tasks: Claude queries Onfleet metadata for ECOM-554 to locate the task ID.
2. get_single_onfleet_task_by_id: Claude inspects the task state to ensure it is still active and extracts the assigned workerId.
3. get_single_onfleet_worker_by_id: Claude fetches the worker's current details and active status.
4. create_a_onfleet_destination: Because addresses in Onfleet are distinct entities, Claude must first create a new destination record for 999 Market St.
5. update_a_onfleet_task_by_id: Finally, Claude patches the active task, replacing the old destination ID with the newly generated destination ID.

Security and Access Control

Exposing an operational logistics platform like Onfleet to an AI agent requires strict security boundaries. Truto MCP servers provide robust controls natively:

• Method Filtering: Limit an MCP server to read-only operations by passing config.methods: ["read"]. The LLM will be able to query tasks and track drivers, but cannot create, modify, or delete tasks.
• Tag Filtering: Restrict tools to specific resource boundaries (e.g., config.tags: ["dispatch"]) to keep the agent focused purely on assigning work rather than managing webhooks or API keys.
• Expiration Timers: Generate temporary servers by setting an expires_at ISO datetime. The platform handles token validation and automatic expiration cleanup, ensuring temporary agents lose access exactly when intended.
• Enforced API Token Auth: Set require_api_token_auth: true to force the client to pass a valid Truto API token in addition to the standard MCP URL token. This guarantees that possession of the URL alone is useless without authorized infrastructure access.

Automate Dispatch Operations at Scale

Building a custom integration layer for Onfleet requires navigating complex array concurrency, async routing engines, and rate limit architectures. Truto abstracts these lifecycle and protocol challenges, providing a dynamic, documentation-driven MCP server that maps natively to Claude.

Stop writing custom Python or TypeScript glue code to orchestrate your delivery fleets. Focus on the AI prompts and agent logic, and let the infrastructure handle the protocol.