Approval-Gated Flexport Rate to Booking

Overview

Separate discovery from commitment. MCP rate tools can search, evaluate, request, and book; a booking must never be inferred from a search result or performed before a named approver accepts the final normalized terms.

Prerequisites

• Validated origin, destination, cargo, dates, mode, and incoterm
• Authenticated connection to https://mcp.flexport.com/mcp
• Named approver, spend boundary, and duplicate-prevention store

Instructions

Step 1: Normalize the lane

Resolve addresses, company entities, ports, addresses, and commodity inputs with read-only network tools. Preserve opaque Flexport identifiers.

Step 2: Search without commitment

Call rates_search_instant_price with approved inputs and store the search/result identifiers plus a redacted input digest.

Step 3: Evaluate the candidate

Use rates_evaluate_total_price_from_instant_price_search for the selected result. Present currency, charge breakdown, timing, assumptions, and expiry exactly as returned.

Step 4: Choose the branch

If instant booking is unavailable, use rates_request_rate and reconcile the quote request. Do not substitute rates_book_without_rate unless that supplier flow was explicitly approved.

Step 5: Require human approval

Bind the approver, exact evaluated result, cargo digest, and approval expiry. Re-evaluate when any material input or provider term changes.

Step 6: Book once and reconcile

Persist an operation key before rates_instant_book; store the returned booking reference and reconcile ambiguous outcomes before any retry.

Authentication

REST calls authenticate with a cached OAuth 2.0 client-credentials Bearer token using audience https://api.flexport.com, or an explicitly accepted broad API key. Use distinct credentials per workload and never log credentials or tokens. MCP calls use the authenticated connection to https://mcp.flexport.com/mcp and remain subject to each tool's documented account permissions.

Tool Discipline

Use Read and Grep for discovery and evidence. Use Write or Edit only for the approved artifact, code, configuration, test, or receipt described by this workflow; do not make an unapproved Flexport-side change.

Output

• Scoped decision or implementation artifact
• Redacted operation and validation receipt
• Failure, rollback, and follow-up ownership record

Return a machine-reviewable receipt in this shape; adapt the operation values, but never place credentials or provider payloads in it:

surface: rest-v3
operation: shipment-read
decision: approved
outcome: verified
evidence:
  release_sha: recorded-out-of-band
  provider_reference: redacted
rollback_owner: logistics-platform

Examples

An operator searches an ocean lane, evaluates one returned rate, and receives a review card. Only after the logistics owner approves that exact result does the service make one booking call and record the returned reference.

Error Handling

Failure	Response
No instant rate	Create a quote request or stop; never fabricate a price.
Permission denied	Route to an authorized role instead of escalating credentials.
Terms changed after approval	Invalidate approval and present a fresh evaluation.
Booking outcome ambiguous	Reconcile by known references before considering another mutation.

Resources

• First-party source notes
• Flexport MCP tools
• Booking tutorial
• Flexport API reference