MCP Tools

Once connected, your assistant can call any of the tools below. Each is documented as a synthetic POST /tools/{name} operation with its complete input schema, output schema, and required permissions — see the note on each operation for how this maps to the real MCP transport. The same information is also available at connect time via the MCP tools/list method.

Get rates & book freight

Search rates, request pricing, and create bookings.

Track shipments

Find shipments and triage the ones that need action.

  • track_shipment — Find any shipment and see where it is in its lifecycle.
  • browse_shipments — Search shipments by status, mode, date range, task, or demurrage/detention risk, with combinable filters.

Network

Search Flexport's network of addresses, companies, ports, and commodity codes.

Account

Browse shipments

Browse Flexport-managed shipments matching status, mode, date range, task, or demurrage/detention filters, paginated. Returns up to 100 tenant-scoped shipments per page with the same tracking detail as track_shipment: route stops, containers with last-free-day info, customs entries, exceptions, open work item tasks, and metadata tags.

This operation is a synthetic representation of an MCP tools/call invocation, not a literal REST endpoint. The Flexport MCP server exposes a single JSON-RPC 2.0 endpoint at POST https://mcp.flexport.com/mcp (MCP Streamable HTTP transport) — the tool name and arguments below are carried in the JSON-RPC request body, not in the HTTP path.

Permissions (any of): Admin, Analyst, Billing, Member, Tracker

Request
Request Body schema: application/json
required
after
string

Pagination cursor. Pass the endCursor from the previous response to get the next page.

object

ETA range — filter by arrival at the first port of arrival for customs clearance. This is often NOT the same date as the shipment's final destination arrival — an inland leg after this port can add days to weeks. Either from or to may be omitted for an open-ended range.

from
string

Start of the range, ISO 8601 date.

to
string

End of the range, ISO 8601 date.

object

Filter by shipments that have at least one container whose demurrage last free day falls within this date range (inclusive). Both from and to are required.

from
string

Start of the range, ISO 8601 date.

to
string

End of the range, ISO 8601 date.

object

ETD range — filter by port-of-loading departure date. Either from or to may be omitted for an open-ended range.

from
string

Start of the range, ISO 8601 date.

to
string

End of the range, ISO 8601 date.

object

Filter by shipments that have at least one container whose detention last free day falls within this date range (inclusive). Both from and to are required.

from
string

Start of the range, ISO 8601 date.

to
string

End of the range, ISO 8601 date.

first
integer [ 1 .. 100 ]

Number of results to return. Defaults to 10, maximum 100.

flags
Array of strings

Filter to shipments matching ALL provided flags (AND, not OR): HAS_OPEN_TASK (at least one open, not yet completed/cancelled, client work item), HAS_ACTIVE_EXCEPTION (at least one open operational exception in a client-facing category), HAS_CUSTOMS_HOLD (at least one customs declaration currently under hold or exam).

Items Enum: "HAS_OPEN_TASK" "HAS_ACTIVE_EXCEPTION" "HAS_CUSTOMS_HOLD"
is_completed
boolean

Filter by whether the shipment is administratively complete. False restricts results to active, in-progress shipments; true returns finished/delivered shipments; omitting the field returns both. This is tracked separately from statuses, so it is combined with AND rather than implied: a shipment can sit at FINAL_DESTINATION and still not be complete.

modes
Array of strings

Filter by transportation mode. Values match track_shipment's mode field (OCEAN_FCL, OCEAN_LCL, AIR, TRUCK_FTL, TRUCK_LTL). Returns shipments matching any of the provided modes.

Items Enum: "OCEAN_FCL" "OCEAN_LCL" "AIR" "TRUCK_FTL" "TRUCK_LTL"
statuses
Array of strings

Filter by transportation status. Values match track_shipment's status field (e.g. SHIPPER_LOCATION, IN_TRANSIT_TO_ARRIVAL_PORT, ARRIVAL_PORT, GATED_OUT). Returns shipments matching any of the provided statuses.

Items Enum: "SHIPPER_LOCATION" "ORIGIN_STOP_OFF" "IN_TRANSIT_TO_DEPARTURE_PORT" "DEPARTURE_PORT" "IN_TRANSIT_TO_INTERMEDIARY_PORT" "INTERMEDIARY_PORT" "IN_TRANSIT_TO_ARRIVAL_PORT" "ARRIVAL_PORT" "DECONSOLIDATION" "DESTINATION_STOP_OFF" "IN_TRANSIT_TO_FINAL_DESTINATION" "FINAL_DESTINATION" "GATED_OUT"
Responses
200

Successful tool call.

Response Schema: application/json
end_cursor
string

Cursor for the next page. Null if there is no next page.

has_next_page
required
boolean

True if more results exist beyond this page.

required
Array of objects

Matching shipments for this page.

Array
required
Array of objects

Containers with demurrage and detention last-free-day info.

created_at
required
string

ISO-8601 timestamp when the shipment was created.

required
Array of objects

Customs declarations with filing status and PGA hold information.

required
Array of objects

Active and historical operational exceptions.

flex_id
required
string

Flexport FLEX-ID of the shipment.

incoterm
string

Incoterm from ExecutionOrder (e.g. FOB, CIF, DDP). Null when not set or INVALID.

is_completed
boolean

True when the shipment is administratively complete. Tracked separately from status — a shipment can be at FINAL_DESTINATION and still not be complete. Null when unknown.

required
Array of objects

Shipment lifecycle milestones with status and date. Mode-filtered: only milestones applicable to this shipment's transportation mode are included.

mode
string

Transportation mode from ExecutionOrder transit offering (OCEAN_FCL, OCEAN_LCL, AIR, TRUCK_FTL, TRUCK_LTL).

name
required
string

Shipment name.

priority
required
string

Shipment priority (HIGH or STANDARD).

required
Array of objects

Route stops: ORIGIN, PORT_OF_LOADING, PORT_OF_UNLOADING, DESTINATION.

status
string

Transportation status from itinerary (e.g. IN_TRANSIT_TO_ARRIVAL_PORT). Null when not yet set or INVALID.

required
Array of objects

Client-assigned metadata tags on this shipment.

required
Array of objects

Open client-facing work items (tasks requiring client action).

post/tools/browse_shipments
Request samples
application/json
{
  • "after": "string",
  • "arrival_range": {
    • "from": "string",
    • "to": "string"
    },
  • "demurrage_risk": {
    • "from": "string",
    • "to": "string"
    },
  • "departure_range": {
    • "from": "string",
    • "to": "string"
    },
  • "detention_risk": {
    • "from": "string",
    • "to": "string"
    },
  • "first": 1,
  • "flags": [
    • "HAS_OPEN_TASK"
    ],
  • "is_completed": true,
  • "modes": [
    • "OCEAN_FCL"
    ],
  • "statuses": [
    • "SHIPPER_LOCATION"
    ]
}
Response samples
application/json
{
  • "end_cursor": "string",
  • "has_next_page": true,
  • "shipments": [
    • {
      • "containers": [
        ],
      • "created_at": "string",
      • "customs": [
        ],
      • "exceptions": [
        ],
      • "flex_id": "string",
      • "incoterm": "string",
      • "is_completed": true,
      • "milestones": [
        ],
      • "mode": "string",
      • "name": "string",
      • "priority": "string",
      • "route": [
        ],
      • "status": "string",
      • "tags": [
        ],
      • "tasks": [
        ]
      }
    ]
}

List active company users

List or search active users in your company, including yourself. Useful for looking up a quote request submitter by name or email, or for browsing all active users to pick one from.

This operation is a synthetic representation of an MCP tools/call invocation, not a literal REST endpoint. The Flexport MCP server exposes a single JSON-RPC 2.0 endpoint at POST https://mcp.flexport.com/mcp (MCP Streamable HTTP transport) — the tool name and arguments below are carried in the JSON-RPC request body, not in the HTTP path.

Permissions (any of): Admin, Analyst, Billing, Member

Request
Request Body schema: application/json
required
after
string

Pagination cursor. Pass end_cursor from the previous response to get the next page.

first
integer [ 1 .. 100 ]

Number of users to return. Defaults to 100, maximum 100.

query
string

User name or email to search for. Omit to list all active users in the company.

Responses
200

Successful tool call.

Response Schema: application/json
end_cursor
string
has_next_page
required
boolean
total_count
required
integer
required
Array of objects
Array
email
required
string

Email address of the user.

name
required
string
user_id
required
integer

User ID to pass to requestor_ids in rates_browse_quote_requests.

post/tools/list_active_company_users
Request samples
application/json
{
  • "after": "string",
  • "first": 1,
  • "query": "string"
}
Response samples
application/json
{
  • "end_cursor": "string",
  • "has_next_page": true,
  • "total_count": 0,
  • "users": [
    • {
      • "email": "string",
      • "name": "string",
      • "user_id": 0
      }
    ]
}

Search addresses

Search addresses already onboarded in your Flexport network, by name, street, city, state, or company legal name. Returns address identifiers for use in other tools, such as rates_search_instant_price.

This operation is a synthetic representation of an MCP tools/call invocation, not a literal REST endpoint. The Flexport MCP server exposes a single JSON-RPC 2.0 endpoint at POST https://mcp.flexport.com/mcp (MCP Streamable HTTP transport) — the tool name and arguments below are carried in the JSON-RPC request body, not in the HTTP path.

Permissions (any of): Admin, Analyst, Billing, Member, Tracker

Request
Request Body schema: application/json
required
limit
integer

Maximum number of results to return. Must be between 1 and 50. Defaults to 10.

query
required
string

Address name, street, city, or state. The backend ANDs per-word prefix matches; postal/ZIP codes and country names or codes are not searched. Hyphens in street and unit identifiers, such as 1-7357 or Unit-321, are significant — searching for 7357 or 321 alone will not match those values.

Responses
200

Successful tool call.

Response Schema: application/json
required
Array of objects
Array
address
required
string
address_fid
required
string

Address FID to use in follow-up workflows such as rates_search_instant_price.

city
string
country_code
string
latitude
required
number
longitude
required
number
name
string
state
string
count
required
integer
has_more
required
boolean
post/tools/network_search_addresses
Request samples
application/json
{
  • "limit": 0,
  • "query": "string"
}
Response samples
application/json
{
  • "addresses": [
    • {
      • "address": "string",
      • "address_fid": "string",
      • "city": "string",
      • "country_code": "string",
      • "latitude": 0,
      • "longitude": 0,
      • "name": "string",
      • "state": "string"
      }
    ],
  • "count": 0,
  • "has_more": true
}

Search company entities

Search active Flexport company entities in your network by legal name. Matches on whole normalized legal-name similarity, not substrings — does not search DBA names or tax IDs. Returns company entity identifiers for use in other tools.

This operation is a synthetic representation of an MCP tools/call invocation, not a literal REST endpoint. The Flexport MCP server exposes a single JSON-RPC 2.0 endpoint at POST https://mcp.flexport.com/mcp (MCP Streamable HTTP transport) — the tool name and arguments below are carried in the JSON-RPC request body, not in the HTTP path.

Permissions (any of): Admin, Analyst, Billing, Member, Tracker

Request
Request Body schema: application/json
required
limit
integer

Number of results to return. Default 10, maximum 50.

query
required
string

Company entity legal name. The backend compares the complete normalized legal name using whole-string similarity rather than prefix matching. Corporate suffixes such as Inc, LLC, and Ltd are optional. Partial names, missing words, or typos may not match.

Responses
200

Successful tool call.

Response Schema: application/json
required
Array of objects
Array
business_registration_country_code
string
required
object
company_entity_id
required
integer

Flexport company entity ID — use this in follow-up workflows.

is_archived
required
boolean
is_primary
required
boolean

True if this is the primary entity for its parent company.

legal_name
required
string
shipment_roles
required
Array of strings

Roles this entity plays on shipments. Values: SHIPPER, CONSIGNEE.

count
required
integer

Number of company entities returned in this response (at most the requested limit).

errors
Array of strings
has_more
required
boolean

True if more results exist beyond the current limit than were returned.

post/tools/network_search_company_entities
Request samples
application/json
{
  • "limit": 0,
  • "query": "string"
}
Response samples
application/json
{
  • "company_entities": [
    • {
      • "business_registration_country_code": "string",
      • "company": {
        },
      • "company_entity_id": 0,
      • "is_archived": true,
      • "is_primary": true,
      • "legal_name": "string",
      • "shipment_roles": [
        ]
      }
    ],
  • "count": 0,
  • "errors": [
    • "string"
    ],
  • "has_more": true
}

Search fulfillment inbound addresses

Search eligible Flexport warehouse destinations for a booking that should automatically create a fulfillment inbound. Eligibility depends on your account and the booking's origin. Returns address identifiers for use as the destination in rates_book_without_rate.

This operation is a synthetic representation of an MCP tools/call invocation, not a literal REST endpoint. The Flexport MCP server exposes a single JSON-RPC 2.0 endpoint at POST https://mcp.flexport.com/mcp (MCP Streamable HTTP transport) — the tool name and arguments below are carried in the JSON-RPC request body, not in the HTTP path.

Permissions (any of): Admin, Billing, Member

Request
Request Body schema: application/json
required
cursor
string

Opaque cursor from a previous response. Omit for the first page.

limit
integer

Maximum number of results to return. Must be between 1 and 50. Defaults to 10.

origin_address_fid
required
string

Booking origin address FID used to determine eligible Flexport fulfillment warehouses.

query
string

Optional warehouse name, street, city, or state search text. Defaults to empty.

Responses
200

Successful tool call.

Response Schema: application/json
required
Array of objects
Array
address
required
string
address_fid
required
string

Eligible warehouse address FID to use as the booking's destination_address_fid.

city
string
country_code
string
latitude
required
number
longitude
required
number
name
string
state
string
count
required
integer
has_more
required
boolean
next_cursor
string
post/tools/network_search_fulfillment_inbound_addresses
Request samples
application/json
{
  • "cursor": "string",
  • "limit": 0,
  • "origin_address_fid": "string",
  • "query": "string"
}
Response samples
application/json
{
  • "addresses": [
    • {
      • "address": "string",
      • "address_fid": "string",
      • "city": "string",
      • "country_code": "string",
      • "latitude": 0,
      • "longitude": 0,
      • "name": "string",
      • "state": "string"
      }
    ],
  • "count": 0,
  • "has_more": true,
  • "next_cursor": "string"
}

Search Google addresses

Search Google Places for cities, postal codes, and general place matches not yet onboarded in your Flexport network. Returns address identifiers for use in other tools.

This operation is a synthetic representation of an MCP tools/call invocation, not a literal REST endpoint. The Flexport MCP server exposes a single JSON-RPC 2.0 endpoint at POST https://mcp.flexport.com/mcp (MCP Streamable HTTP transport) — the tool name and arguments below are carried in the JSON-RPC request body, not in the HTTP path.

Permissions (any of): Admin, Analyst, Billing, Member, Tracker

Request
Request Body schema: application/json
required
country_codes
Array of strings

Optional ISO-3166 alpha-2 country codes to restrict results, e.g. ["US", "CN"].

language_code
string

Optional BCP 47 language code for result text, e.g. en or zh-CN.

query
required
string

Address, city, or postal code to search for.

Responses
200

Successful tool call.

Response Schema: application/json
required
Array of objects

Google Places matches restricted to cities.

Array
city
string
commerce_address_fid
required
string

Flexport Commerce address FID to use in follow-up workflows.

object
country_code
string
formatted_address
string
name
string
postal_code
string
state
string
type
required
string

Normalized address type, such as CITY, POSTAL_CODE, or LOCATION.

count
required
integer

Total number of valid results across all categories.

errors
Array of strings
required
Array of objects

General Google Places matches, including addresses and points of interest.

Array
city
string
commerce_address_fid
required
string

Flexport Commerce address FID to use in follow-up workflows.

object
country_code
string
formatted_address
string
name
string
postal_code
string
state
string
type
required
string

Normalized address type, such as CITY, POSTAL_CODE, or LOCATION.

required
Array of objects
Array
city
string
commerce_address_fid
required
string

Flexport Commerce address FID to use in follow-up workflows.

object
country_code
string
formatted_address
string
name
string
postal_code
string
state
string
type
required
string

Normalized address type, such as CITY, POSTAL_CODE, or LOCATION.

post/tools/network_search_google_addresses
Request samples
application/json
{
  • "country_codes": [
    • "string"
    ],
  • "language_code": "string",
  • "query": "string"
}
Response samples
application/json
{
  • "cities": [
    • {
      • "city": "string",
      • "commerce_address_fid": "string",
      • "coordinates": {
        },
      • "country_code": "string",
      • "formatted_address": "string",
      • "name": "string",
      • "postal_code": "string",
      • "state": "string",
      • "type": "string"
      }
    ],
  • "count": 0,
  • "errors": [
    • "string"
    ],
  • "google_places": [
    • {
      • "city": "string",
      • "commerce_address_fid": "string",
      • "coordinates": {
        },
      • "country_code": "string",
      • "formatted_address": "string",
      • "name": "string",
      • "postal_code": "string",
      • "state": "string",
      • "type": "string"
      }
    ],
  • "postal_codes": [
    • {
      • "city": "string",
      • "commerce_address_fid": "string",
      • "coordinates": {
        },
      • "country_code": "string",
      • "formatted_address": "string",
      • "name": "string",
      • "postal_code": "string",
      • "state": "string",
      • "type": "string"
      }
    ]
}

Search HS codes

Search Flexport's six-digit international HS-code catalog by product description or code, for classifying goods when booking without a rate.

This operation is a synthetic representation of an MCP tools/call invocation, not a literal REST endpoint. The Flexport MCP server exposes a single JSON-RPC 2.0 endpoint at POST https://mcp.flexport.com/mcp (MCP Streamable HTTP transport) — the tool name and arguments below are carried in the JSON-RPC request body, not in the HTTP path.

Permissions (any of): Admin, Billing, Member

Request
Request Body schema: application/json
required
limit
integer

Number of results to return. Default 10, maximum 50.

query
required
string

Product description or HS code to search for, for example "shoes" or "1801.00".

Responses
200

Successful tool call.

Response Schema: application/json
count
required
integer

Number of HS codes returned in this response.

has_more
required
boolean

True if more results exist beyond the current limit. Refine the query or increase limit to retrieve them.

required
Array of objects

Candidate HS codes matching the search query.

Array
code
required
string
country_code
required
string
description
string
hs_code_dbid
required
integer

Database ID to use as hs_code_dbid in rates_book_without_rate.

post/tools/network_search_hs_codes
Request samples
application/json
{
  • "limit": 0,
  • "query": "string"
}
Response samples
application/json
{
  • "count": 0,
  • "has_more": true,
  • "hs_codes": [
    • {
      • "code": "string",
      • "country_code": "string",
      • "description": "string",
      • "hs_code_dbid": 0
      }
    ]
}

Search ports

Search Flexport's sea and air ports by name, city, UN/LOCODE, IATA code, ICAO code, or customs port code. Returns port identifiers for use in other tools.

This operation is a synthetic representation of an MCP tools/call invocation, not a literal REST endpoint. The Flexport MCP server exposes a single JSON-RPC 2.0 endpoint at POST https://mcp.flexport.com/mcp (MCP Streamable HTTP transport) — the tool name and arguments below are carried in the JSON-RPC request body, not in the HTTP path.

Permissions (any of): Admin, Analyst, Billing, Member, Tracker

Request
Request Body schema: application/json
required
country_codes
Array of strings

Filter by ISO-3166 alpha-2 country codes, e.g. ["US", "CN"]. Multiple codes are OR-combined.

limit
integer

Number of results to return. Default 10, maximum 50.

query
required
string

Search text — matches port name, city, UN/LOCODE, IATA code, ICAO code, or customs port code. Must contain at least one letter or digit.

transportation_mode
string

Filter by transportation mode.

Enum: "AIR" "OCEAN" "RAIL" "TRUCK"
Responses
200

Successful tool call.

Response Schema: application/json
count
required
integer

Number of ports returned in this response (at most the requested limit).

errors
Array of strings
has_more
required
boolean

True if more results exist beyond the current limit. Refine the query or increase limit to retrieve them.

required
Array of objects
Array
city
string
required
object
country_code
required
string
is_archived
required
boolean
port_id
required
integer

Flexport's internal identifier for the port, referenced in other API calls that accept a port ID.

port_name
required
string
port_types
required
Array of strings

Port facility types present at this port: airport, seaport, railport, roadport.

state
string
timezone
string
transportation_modes
required
Array of strings

Transportation modes supported: air, ocean, rail, truck.

post/tools/network_search_ports
Request samples
application/json
{
  • "country_codes": [
    • "string"
    ],
  • "limit": 0,
  • "query": "string",
  • "transportation_mode": "AIR"
}
Response samples
application/json
{
  • "count": 0,
  • "errors": [
    • "string"
    ],
  • "has_more": true,
  • "ports": [
    • {
      • "city": "string",
      • "codes": {
        },
      • "country_code": "string",
      • "is_archived": true,
      • "port_id": 0,
      • "port_name": "string",
      • "port_types": [
        ],
      • "state": "string",
      • "timezone": "string",
      • "transportation_modes": [
        ]
      }
    ]
}

Book without a rate

Create and submit an unrated supplier booking for consignee acceptance — for suppliers or shippers booking without a rate. Flexport prepares the quote for the consignee after submission. Dangerous-goods cargo and document uploads aren't supported through this tool; use the Flexport web app for those.

This operation is a synthetic representation of an MCP tools/call invocation, not a literal REST endpoint. The Flexport MCP server exposes a single JSON-RPC 2.0 endpoint at POST https://mcp.flexport.com/mcp (MCP Streamable HTTP transport) — the tool name and arguments below are carried in the JSON-RPC request body, not in the HTTP path.

Permissions (any of): Admin, Billing, Member

Request
Request Body schema: application/json
required
booking_confirmation_token
string

Payload fingerprint returned by a previous preflight of these exact booking details. Reuse the token unchanged on retry; any change to the booking details invalidates it.

required
Array of objects

HS commodity lines for the shipment. Codes can be found via network_search_hs_codes. Exact duplicate code/description pairs are rejected rather than merged. At least one complete entry is required for a non-trucking booking.

Array
description
required
string

Plain-language description of the goods covered by this HS code.

description_for_export_customs
string

Goods description to use specifically for export customs documentation. Required for every HS code when the shipment origin is China.

hs_code_dbid
required
integer

Database ID of the HS commodity classification. Obtained from network_search_hs_codes.

required
object

Total cargo measurements, packaging, piece counts, and dangerous-goods screening answers. This tool supports only false for every dangerous-goods field.

contains_hazmat
required
boolean

Whether any cargo is regulated as hazardous material or dangerous goods. This tool supports only false.

contains_li_ion
required
boolean

Whether the cargo contains lithium-ion batteries, including batteries inside equipment. This tool supports only false.

contains_magnets
required
boolean

Whether the cargo contains magnetized material that may require special handling. This tool supports only false.

contains_non_li_ion_battery
required
boolean

Whether the cargo contains batteries other than lithium-ion batteries. This tool supports only false.

contains_other_dangerous_goods
required
boolean

Whether the cargo contains other potentially dangerous goods, such as regulated liquids, powders, or chemicals. This tool supports only false.

marks_and_numbers
string

Shipping marks, reference numbers, or package identifiers printed on the cargo and used on transport documents.

metric_units
required
boolean

Whether cargo-level volume and weight use metric units: cubic meters and kilograms when true, cubic feet and pounds when false.

required
Array of objects

Breakdown of the cargo's packaging and handling units. An empty list is allowed only for an ocean booking when package details are unknown.

slac
required
integer

Shipper's Load and Count: total smallest package count declared by the shipper. The booking UI requires this to be a positive integer for every booking.

volume
required
number

Total volume of all cargo in cubic meters when metric_units is true, otherwise cubic feet. Must be greater than zero.

weight
required
number

Total gross weight of all cargo in kilograms when metric_units is true, otherwise pounds. Must be greater than zero.

cargo_ready_date
required
string

Date in YYYY-MM-DD format when the supplier expects the cargo to be packed and available for pickup or handoff.

consignee_entity_id
required
integer

Consignee company entity numeric ID. Obtained from an active entity with the CONSIGNEE role via network_search_company_entities, using its company_entity_id field.

declared_as_strategy
string

Whether the cargo contains strategic or export-controlled goods: yes, no, or notsure. Relevant when either the loading or unloading port is in Hong Kong. Provide eccn_codes when yes.

Enum: "yes" "no" "notsure"
delivery_date
string

Supplier's requested target arrival date at the final destination in YYYY-MM-DD format. This is a planning target, not a carrier-confirmed ETA or delivery appointment.

description_of_products
string

Plain-language description of the products being shipped.

eccn_codes
string

Comma-separated Export Control Classification Numbers for controlled goods, for example '3A001, 5A002'.

estimated_commercial_invoice_value
integer

Estimated total merchandise value that will appear on the commercial invoice, in whole USD. This is cargo value, not freight cost, customs duty, or insurance premium.

memo
string

Optional booking note or handling instruction for Flexport operations.

required
Array of objects

Optional booking shipment tags configured by the consignee. The tool validates supplied tags against the consignee's active booking metadata schema. Provide an empty list when no tags should be added.

Array
attribute
string

Consignee-defined shipment-tag attribute name.

values
required
Array of strings

Values selected for the consignee-defined shipment-tag attribute.

name
required
string

Supplier-facing reference name used to identify this booking or shipment.

notify_party
string

Party to notify when the cargo arrives. Required when notify_party_same_as_consignee is false.

notify_party_same_as_consignee
required
boolean

Whether the notify party is the consignee. When true, omit notify_party. When false, provide notify_party.

origin_address_fid
required
string

Cargo's origin location, normally the supplier facility where cargo is available for pickup — a Flexport FID string beginning 'flx::', NOT a numeric ID. Obtained from the address_fid field returned by network_search_addresses. If no matching address exists, it must be added in Flexport first.

origin_delivery_note
string

Optional pickup instructions or access details for the origin location. Provide only when pickup service is selected.

origin_localized_address
string

Localized-language pickup address, primarily the Chinese version of a China origin address. Provide only when pickup service is selected.

origin_needs_help_unloading
boolean

Whether additional labor is needed to help load or unload cargo at pickup. Provide only when pickup service is selected.

policy_violations_confirmed
boolean

Whether previously returned non-blocking Stoplight policy violations have been reviewed and confirmed. False on the initial attempt.

service_selection_confirmed
required
boolean

Whether the applicable service choices (pickup, delivery, export customs, and, where relevant, Hong Kong trade declaration) have been confirmed. Truck is always pickup and delivery door to door. For air and ocean, pickup defaults to true for EXW and FCA Factory and false for other incoterms; delivery defaults false. Export customs defaults true only for EXW.

shipper_entity_id
required
integer

Supplier company entity numeric ID. Obtained from an active entity with the SHIPPER role via network_search_company_entities, using its company_entity_id field.

required
object or object or object
Any of:

Transportation choices. Select exactly one freight_method branch. Air and ocean require incoterm; truck requires truck_type and payment_terms and is always door to door.

One of:

Transportation choices. Select exactly one freight_method branch. Air and ocean require incoterm; truck requires truck_type and payment_terms and is always door to door.

destination_address_fid
string

Requested final delivery location FID from network_search_addresses. Required when wants_delivery_service is true.

fca_subcategory
required
string

For FCA only, where the shipper hands over the cargo: port_cfs or factory.

Enum: "port_cfs" "factory"
incoterm
required
string

Incoterms are the terms of sale between a buyer and seller that define who arranges for the payment and handling of the goods during shipping. See the Flexport Help Center for more detailed information about Incoterms.

Enum: "CFR" "CIF" "CIP" "CPT" "DAP" "DAT" "DDP" "DPU" "EXW" "FAS" "FCA" "FOB"
Value: "FCA"
port_of_loading_id
integer

Origin Airport numeric ID from network_search_ports.

port_of_unloading_id
integer

Destination Airport numeric ID from network_search_ports.

wants_delivery_service
boolean

Whether Flexport should deliver cargo to the destination address.

wants_pickup_service
boolean

Whether Flexport should collect cargo from the origin address.

freight_method
required
any
Value: "air"
wants_create_fulfillment_inbound
boolean

Whether Flexport should automatically create a fulfillment inbound from the shipment's LPNs. Selecting this limits the destination to Flexport warehouses; candidate destinations can be found via network_search_fulfillment_inbound_addresses using this booking's origin_address_fid.

wants_export_customs_service
boolean

Whether Flexport should handle export customs clearance. Defaults to true for EXW and false for other incoterms.

wants_trade_declaration_service
boolean

Whether Flexport should handle Hong Kong trade declaration. Relevant when the origin is in Hong Kong; otherwise defaults to false.

Responses
200

Successful tool call.

Response Schema: application/json
booking_id
required
integer

Numeric database ID of the created and submitted booking.

flex_id
string

Created shipment FLEX-ID (e.g. "FLEX-1234567"), null if the booking failed.

next_action
required
string

Human-readable explanation of what happens next for the booking.

object

Consignee auto-approval cutoff settings when configured for this booking.

cutoff_days
required
integer

Number of days before the pending approval is resolved automatically.

default_action
required
string

Action automatically taken at the cutoff, such as APPROVE or REJECT.

required
Array of objects

Non-blocking consignee policy warnings or approval requirements returned by Stoplight.

Array
action
required
string

Required policy action, such as warning or approval required.

additional_data
string

Additional policy context when supplied by Stoplight.

key
required
string

Policy rule identifier returned by Stoplight.

type
required
string

Policy category returned by Stoplight.

shipment_id
integer

Numeric database ID of the shipment created when the booking was submitted, or null if not returned.

url
string

URL to view the created shipment in the Flexport app, null if the booking failed.

workflow_status
required
string

Current outcome of the booking workflow, such as submitted or pending_consignee_quote_acceptance.

post/tools/rates_book_without_rate
Request samples
application/json
{
  • "booking_confirmation_token": "string",
  • "booking_hs_codes": [
    • {
      • "description": "string",
      • "description_for_export_customs": "string",
      • "hs_code_dbid": 0
      }
    ],
  • "cargo": {
    • "contains_hazmat": true,
    • "contains_li_ion": true,
    • "contains_magnets": true,
    • "contains_non_li_ion_battery": true,
    • "contains_other_dangerous_goods": true,
    • "marks_and_numbers": "string",
    • "metric_units": true,
    • "shipping_units": [
      • {
        }
      ],
    • "slac": 0,
    • "volume": 0,
    • "weight": 0
    },
  • "cargo_ready_date": "string",
  • "consignee_entity_id": 0,
  • "declared_as_strategy": "yes",
  • "delivery_date": "string",
  • "description_of_products": "string",
  • "eccn_codes": "string",
  • "estimated_commercial_invoice_value": 0,
  • "memo": "string",
  • "metadatas": [
    • {
      • "attribute": "string",
      • "values": [
        ]
      }
    ],
  • "name": "string",
  • "notify_party": "string",
  • "notify_party_same_as_consignee": true,
  • "origin_address_fid": "string",
  • "origin_delivery_note": "string",
  • "origin_localized_address": "string",
  • "origin_needs_help_unloading": true,
  • "policy_violations_confirmed": true,
  • "service_selection_confirmed": true,
  • "shipper_entity_id": 0,
  • "transportation": {
    • "destination_address_fid": "string",
    • "fca_subcategory": "port_cfs",
    • "incoterm": "FCA",
    • "port_of_loading_id": 0,
    • "port_of_unloading_id": 0,
    • "wants_delivery_service": true,
    • "wants_pickup_service": true,
    • "freight_method": "air"
    },
  • "wants_create_fulfillment_inbound": true,
  • "wants_export_customs_service": true,
  • "wants_trade_declaration_service": true
}
Response samples
application/json
{
  • "booking_id": 0,
  • "flex_id": "string",
  • "next_action": "string",
  • "policy_approval_cutoff": {
    • "cutoff_days": 0,
    • "default_action": "string"
    },
  • "policy_violations": [
    • {
      • "action": "string",
      • "additional_data": "string",
      • "key": "string",
      • "type": "string"
      }
    ],
  • "shipment_id": 0,
  • "url": "string",
  • "workflow_status": "string"
}

Browse quote requests

Find or browse your organization's rate quote requests by name, FLEX-ID, status, freight mode, origin/destination, or submitter. Returns each request's status, route, cargo, submitter, and a link to it in the Flexport web app.

This operation is a synthetic representation of an MCP tools/call invocation, not a literal REST endpoint. The Flexport MCP server exposes a single JSON-RPC 2.0 endpoint at POST https://mcp.flexport.com/mcp (MCP Streamable HTTP transport) — the tool name and arguments below are carried in the JSON-RPC request body, not in the HTTP path.

Permissions (any of): Admin, Analyst, Billing, Member

Request
Request Body schema: application/json
required
address_fids
Array of strings

Network addresses to filter by — Flexport FID strings beginning 'flx::', NOT numeric IDs. Matches either origin or destination.

after
string

Pagination cursor. Pass end_cursor from the previous response to get the next page.

first
integer [ 1 .. 100 ]

Number of results to return. Defaults to 10, maximum 100.

modes
Array of strings

Freight modes to include: OCEAN, AIR, or TRUCK.

Items Enum: "OCEAN" "AIR" "TRUCK"
port_ids
Array of integers

Ports to filter by — numeric IDs. Matches either origin or destination.

query
string

Quote request name or FLEX-ID. Omit to list matching quote requests.

requestor_ids
Array of integers

User IDs of specific submitters to filter by. Omit to return requests from all visible submitters.

status
string

Quote status view. Defaults to ACTIVE, matching the web UI. Use ALL to include historical quote requests.

Enum: "ACTIVE" "READY" "ACCEPTED" "REQUOTED" "EXPIRED" "SAVED_QUOTE" "ALL"
Responses
200

Successful tool call.

Response Schema: application/json
end_cursor
string
has_next_page
required
boolean
required
Array of objects
Array
action_url
string
calculated_volume_cbm
required
number
calculated_weight_kg
required
number
cargo_description
string
cargo_ready_date
string
client_quote_status
required
string
required
Array of objects
flex_id
required
string
freight_type
required
string
name
required
string
quote_count
required
integer
quote_status
required
string
required
object
shipment_id
integer
required
object
transportation_mode
required
string
total_count
required
integer
post/tools/rates_browse_quote_requests
Request samples
application/json
{
  • "address_fids": [
    • "string"
    ],
  • "after": "string",
  • "first": 1,
  • "modes": [
    • "OCEAN"
    ],
  • "port_ids": [
    • 0
    ],
  • "query": "string",
  • "requestor_ids": [
    • 0
    ],
  • "status": "ACTIVE"
}
Response samples
application/json
{
  • "end_cursor": "string",
  • "has_next_page": true,
  • "quote_requests": [
    • {
      • "action_url": "string",
      • "calculated_volume_cbm": 0,
      • "calculated_weight_kg": 0,
      • "cargo_description": "string",
      • "cargo_ready_date": "string",
      • "client_quote_status": "string",
      • "containers": [
        ],
      • "flex_id": "string",
      • "freight_type": "string",
      • "name": "string",
      • "quote_count": 0,
      • "quote_status": "string",
      • "route": {
        },
      • "shipment_id": 0,
      • "submitted_by": {
        },
      • "transportation_mode": "string"
      }
    ],
  • "total_count": 0
}

Get quote details

Get one quote option's complete transit, route, and itemized rate detail, including charges, subtotals, total price, expiration, and a link to it in the Flexport web app.

This operation is a synthetic representation of an MCP tools/call invocation, not a literal REST endpoint. The Flexport MCP server exposes a single JSON-RPC 2.0 endpoint at POST https://mcp.flexport.com/mcp (MCP Streamable HTTP transport) — the tool name and arguments below are carried in the JSON-RPC request body, not in the HTTP path.

Permissions (any of): Admin, Analyst, Billing, Member, Tracker

Request
Request Body schema: application/json
required
quote_id
required
integer

Numeric database ID for the quote option.

Responses
200

Successful tool call.

Response Schema: application/json
action_url
required
string
carrier
string
carrier_transit_description
string
object
maximum
number
minimum
number
unit
string
object
maximum
number
minimum
number
unit
string
freight_service
string
main_service_type
string
quote_id
required
integer
quote_reference
required
string
rate_expiration
string
required
Array of objects
Array
category
required
string
required
Array of objects
object

Numeric subtotal in the quote's base currency.

subtotal_display
string

Preformatted display text for the subtotal. When present, it takes precedence over the numeric subtotal field for display purposes.

required
object
required
Array of objects
object
object
object
required
Array of objects
required
Array of objects
shipment_id
required
integer
status
required
string
required
object
amount
required
number
currency_code
required
string
required
object
destination_days
integer
destination_deconsolidation_days
integer
destination_dwell_days
integer
maximum_days
integer
maximum_p50_days
integer
minimum_days
integer
origin_consolidation_days
integer
origin_days
integer
origin_dwell_days
integer
port_to_port_days
integer
port_to_port_p50_days
integer
transportation_mode
required
string
post/tools/rates_get_quote_details
Request samples
application/json
{
  • "quote_id": 0
}
Response samples
application/json
{
  • "action_url": "string",
  • "carrier": "string",
  • "carrier_transit_description": "string",
  • "carrier_transit_estimate": {
    • "maximum": 0,
    • "minimum": 0,
    • "unit": "string"
    },
  • "flexport_transit_estimate": {
    • "maximum": 0,
    • "minimum": 0,
    • "unit": "string"
    },
  • "freight_service": "string",
  • "main_service_type": "string",
  • "quote_id": 0,
  • "quote_reference": "string",
  • "rate_expiration": "string",
  • "rate_groups": [
    • {
      • "category": "string",
      • "line_items": [
        ],
      • "subtotal": {
        },
      • "subtotal_display": "string"
      }
    ],
  • "route": {
    • "destination_addresses": [
      • {
        }
      ],
    • "destination_port": {
      • "country_code": "string",
      • "name": "string"
      },
    • "origin_address": {
      • "country_code": "string",
      • "name": "string"
      },
    • "origin_port": {
      • "country_code": "string",
      • "name": "string"
      },
    • "places_of_delivery": [
      • {
        }
      ],
    • "via_ports": [
      • {
        }
      ]
    },
  • "shipment_id": 0,
  • "status": "string",
  • "total_price": {
    • "amount": 0,
    • "currency_code": "string"
    },
  • "total_transit_time": {
    • "destination_days": 0,
    • "destination_deconsolidation_days": 0,
    • "destination_dwell_days": 0,
    • "maximum_days": 0,
    • "maximum_p50_days": 0,
    • "minimum_days": 0,
    • "origin_consolidation_days": 0,
    • "origin_days": 0,
    • "origin_dwell_days": 0,
    • "port_to_port_days": 0,
    • "port_to_port_p50_days": 0
    },
  • "transportation_mode": "string"
}

Get quote request details

Get a quote request's submission details and every priced quote option it received, including carrier, transit estimates, costs, total price, expiration, and a link to it in the Flexport web app.

This operation is a synthetic representation of an MCP tools/call invocation, not a literal REST endpoint. The Flexport MCP server exposes a single JSON-RPC 2.0 endpoint at POST https://mcp.flexport.com/mcp (MCP Streamable HTTP transport) — the tool name and arguments below are carried in the JSON-RPC request body, not in the HTTP path.

Permissions (any of): Admin, Analyst, Billing, Member, Tracker

Request
Request Body schema: application/json
required
shipment_id
required
integer

Numeric shipment database ID for the quote request.

Responses
200

Successful tool call.

Response Schema: application/json
client_quote_status
required
string
flex_id
required
string
name
required
string
required
Array of objects
Array
action_url
required
string
carrier
string
carrier_transit_description
string
object
object
object
freight_service
string
object
main_service_type
string
quote_id
required
integer
quote_reference
required
string
rate_expiration
string
status
required
string
required
object
transportation_mode
required
string
quote_status
required
string
shipment_id
required
integer
required
object
calculated_volume_cbm
required
number
calculated_weight_kg
required
number
cargo_ready_date
string
required
Array of objects
freight_type
required
string
incoterm
string
required
object
required
object
object
transportation_mode
required
string
post/tools/rates_get_quote_request_details
Request samples
application/json
{
  • "shipment_id": 0
}
Response samples
application/json
{
  • "client_quote_status": "string",
  • "flex_id": "string",
  • "name": "string",
  • "quote_options": [
    • {
      • "action_url": "string",
      • "carrier": "string",
      • "carrier_transit_description": "string",
      • "carrier_transit_estimate": {
        },
      • "flexport_transit_estimate": {
        },
      • "freight_cost": {
        },
      • "freight_service": "string",
      • "inclusive_cost": {
        },
      • "main_service_type": "string",
      • "quote_id": 0,
      • "quote_reference": "string",
      • "rate_expiration": "string",
      • "status": "string",
      • "total_price": {
        },
      • "transportation_mode": "string"
      }
    ],
  • "quote_status": "string",
  • "shipment_id": 0,
  • "submission_details": {
    • "calculated_volume_cbm": 0,
    • "calculated_weight_kg": 0,
    • "cargo_ready_date": "string",
    • "containers": [
      • {
        }
      ],
    • "freight_type": "string",
    • "incoterm": "string",
    • "route": {
      • "destination_address": {
        },
      • "destination_port": {
        },
      • "origin_address": {
        },
      • "origin_port": {
        }
      },
    • "services": {
      • "delivery": true,
      • "export_customs": true,
      • "import_customs": true,
      • "insurance": true,
      • "pickup": true
      },
    • "submitter": {
      • "id": 0,
      • "name": "string"
      },
    • "transportation_mode": "string"
    }
}

Book an instant price

Instantly create a real, binding booking, either against a prior rates_search_instant_price result or against a known client rate identifier. Booking against a search result requires first calling rates_evaluate_total_price_from_instant_price_search and passing its confirmation token.

This operation is a synthetic representation of an MCP tools/call invocation, not a literal REST endpoint. The Flexport MCP server exposes a single JSON-RPC 2.0 endpoint at POST https://mcp.flexport.com/mcp (MCP Streamable HTTP transport) — the tool name and arguments below are carried in the JSON-RPC request body, not in the HTTP path.

Permissions (any of): Admin, Billing, Member

Request
Request Body schema: application/json
required
object

Cargo details for the booking. Required when booking via client_rate_id, and must match the rate's transportation mode (container_info for ocean_fcl, loose_cargo_info for ocean_lcl or air). Ignored when booking via search_snapshot_id/item_snapshot_id, since cargo is reused from the original search snapshot so the booking matches what was priced.

object

FCL container counts. Required for OCEAN_FCL.

required
object

Dangerous goods screening. Required.

object

Loose cargo details. Required for OCEAN_LCL and AIR.

cargo_ready_date
string

Cargo ready date in YYYY-MM-DD format. Required when booking via client_rate_id. Ignored when booking via search_snapshot_id/item_snapshot_id — the date from the original search is reused so the booking matches what was priced.

client_note
string

Optional note from client

client_rate_id
integer

Numeric client rate ID to book. No currently available endpoint returns this value directly; search_snapshot_id paired with item_snapshot_id from a search_instant_price call is the preferred way to identify a rate to book. Provide this field, or both search_snapshot_id and item_snapshot_id, but not both.

description_of_product
string

Optional description of products being shipped

detention_addon_free_days
integer

Additional detention free days selected from detention_addon_options on the search result, expressed as the add-on days only (not the total including base days). Omitting this field books with the base free days.

item_snapshot_id
string

PREFERRED. Item snapshot ID identifying which search_instant_price result to book. Must be paired with search_snapshot_id.

name
string

Optional name/description for the booking

price_confirmation_token
string

Required in snapshot mode. Must be the price_confirmation_token returned by rates_evaluate_total_price_from_instant_price_search for the same search_snapshot_id, item_snapshot_id, wants_* flags, and detention_addon_free_days being booked; this endpoint recomputes the same selection fingerprint and rejects the booking if it does not match. This is a workflow-consistency guard, not an authentication credential. Ignored for client_rate_id mode.

search_snapshot_id
string

PREFERRED. Search snapshot ID from a prior search_instant_price call. Must be paired with item_snapshot_id. Provide this pair OR client_rate_id — never both.

object

SSAT sailing week preference. Required in snapshot mode when the search result includes nac_allocation (rate_type=NAC with allocation data), using the year and week of one of the feasible weeks listed there (each described by week_date_range, available_allocation, and requested_teus). Omitted when nac_allocation is absent.

week
required
integer

Preferred SSAT sailing week (1–53). Must be paired with year.

year
required
integer

Preferred SSAT sailing year (e.g. 2025). Must be paired with week.

wants_export_customs
boolean

Whether to include Flexport export customs service. Must be true if it is force_included=true on the search result's addon_service_options, and should be kept in sync with the value passed to rates_evaluate_total_price_from_instant_price_search. Snapshot mode only (search_snapshot_id + item_snapshot_id); ignored for client_rate_id. Fails if this rate does not offer or allow export customs.

wants_hk_trade_declaration
boolean

Whether to include Hong Kong trade declaration service. Must be true if it is force_included=true on the search result's addon_service_options, and should be kept in sync with the value passed to rates_evaluate_total_price_from_instant_price_search. Snapshot mode only (search_snapshot_id + item_snapshot_id); ignored for client_rate_id. Fails if this rate does not offer or allow Hong Kong trade declaration.

wants_import_customs
boolean

Whether to include Flexport import customs service. Must be true if it is force_included=true on the search result's addon_service_options, and should be kept in sync with the value passed to rates_evaluate_total_price_from_instant_price_search. Snapshot mode only (search_snapshot_id + item_snapshot_id); ignored for client_rate_id. Fails if this rate does not offer or allow import customs.

wants_inbond_transit
boolean

Whether to include in-bond transit. Must be true if it is force_included=true on the search result's addon_service_options, and should be kept in sync with the value passed to rates_evaluate_total_price_from_instant_price_search. Snapshot mode only (search_snapshot_id + item_snapshot_id); ignored for client_rate_id. Fails if this rate does not offer or allow in-bond transit.

wants_insurance
boolean

Whether to include cargo insurance. Must be true if it is force_included=true on the search result's addon_service_options, and should be kept in sync with the value passed to rates_evaluate_total_price_from_instant_price_search. Snapshot mode only (search_snapshot_id + item_snapshot_id); ignored for client_rate_id. Fails if this rate does not offer or allow insurance.

Responses
200

Successful tool call.

Response Schema: application/json
booking_id
integer

Created booking ID (numeric dbid), null if the booking failed.

client_note
string

Client note echoed back from the request.

description_of_product
string

Description of product echoed back from the request.

destination
string

Destination display name (port or address) of the booked rate.

error_code
string

Failure reason, null on success. One of: RATE_LOOKUP_FAILED, RATE_NOT_FOUND, RATE_CLIENT_MISMATCH, RATE_NOT_ACTIVE, RATE_EXPIRED, RATE_NOT_YET_EFFECTIVE, CARGO_MODE_MISMATCH, BOOKING_FAILED, BOOKING_INCOMPLETE, SNAPSHOT_NOT_FOUND, SNAPSHOT_CLIENT_MISMATCH, MODE_NOT_ENABLED, REQUIRES_PRICE_CONFIRMATION.

error_message
string

Human-readable failure reason, null on success.

flex_id
string

Created shipment FLEX-ID (e.g. "FLEX-1234567"), null if the booking failed.

incoterm
string

Incoterm of the booked rate.

name
string

Name/description echoed back from the request.

origin
string

Origin display name (port or address) of the booked rate.

quote_id
integer

Created quote ID (numeric dbid), null if the booking failed.

shipment_id
integer

Created shipment ID (numeric dbid), null if the booking failed.

success
required
boolean

Whether the booking was created successfully.

transportation_mode
string

Transportation mode of the booked rate.

url
string

URL to view the created shipment in the Flexport app, null if the booking failed.

post/tools/rates_instant_book
Request samples
application/json
{
  • "cargo_details": {
    • "container_info": {
      • "container_20ft": 0,
      • "container_40ft": 0,
      • "container_40ft_hc": 0,
      • "container_45ft_hc": 0
      },
    • "dangerous_goods": {
      • "contains_dangerous_good": true,
      • "dangerous_goods_types": [
        ],
      • "lithium_batteries_packing_types": [
        ]
      },
    • "loose_cargo_info": {
      • "shipping_units": [
        ],
      • "total_volume_cbm": 0,
      • "total_weight_kg": 0
      }
    },
  • "cargo_ready_date": "string",
  • "client_note": "string",
  • "client_rate_id": 0,
  • "description_of_product": "string",
  • "detention_addon_free_days": 0,
  • "item_snapshot_id": "string",
  • "name": "string",
  • "price_confirmation_token": "string",
  • "search_snapshot_id": "string",
  • "ssat_allocation_preference": {
    • "week": 0,
    • "year": 0
    },
  • "wants_export_customs": true,
  • "wants_hk_trade_declaration": true,
  • "wants_import_customs": true,
  • "wants_inbond_transit": true,
  • "wants_insurance": true
}
Response samples
application/json
{
  • "booking_id": 0,
  • "client_note": "string",
  • "description_of_product": "string",
  • "destination": "string",
  • "error_code": "string",
  • "error_message": "string",
  • "flex_id": "string",
  • "incoterm": "string",
  • "name": "string",
  • "origin": "string",
  • "quote_id": 0,
  • "shipment_id": 0,
  • "success": true,
  • "transportation_mode": "string",
  • "url": "string"
}

Request a rate

Request a new rate quote for a lane when rates_search_instant_price has no acceptable option — for example, a lane that needs a fixed (NAC) rate where only spot pricing is available.

This operation is a synthetic representation of an MCP tools/call invocation, not a literal REST endpoint. The Flexport MCP server exposes a single JSON-RPC 2.0 endpoint at POST https://mcp.flexport.com/mcp (MCP Streamable HTTP transport) — the tool name and arguments below are carried in the JSON-RPC request body, not in the HTTP path.

Permissions (any of): Admin, Billing, Member

Request
Request Body schema: application/json
required
cargo_ready_date
required
string

Cargo ready date in YYYY-MM-DD format

destination_address_fid
string

Destination address, specified as a Flexport FID string beginning with 'flx::' (not a numeric ID). Obtained from the address_fid field returned by network_search_addresses, or the commerce_address_fid field returned by network_search_google_addresses if no matching address is found.

destination_port_id
integer

Destination port, specified as a numeric ID. Obtained from the port_id field returned by network_search_ports.

freight_type
string

Freight type: port_to_port, port_to_door, door_to_port, door_to_door

Enum: "port_to_port" "port_to_door" "door_to_port" "door_to_door"
incoterm
required
string

Incoterm: EXW, FCA, FOB, CIF, CIP, CFR, CPT, DAP, DAT, DDP, DPU, FAS

Enum: "CFR" "CIF" "CIP" "CPT" "DAP" "DAT" "DDP" "DPU" "EXW" "FAS" "FCA" "FOB"
note
string

Optional free-text note for the Flexport account team, such as cargo profile (commodity type, dimensions, weight, hazmat status, temperature requirements), target price or budget, expected shipment volume (shipments or TEUs per month/year), or other special requirements.

offering_contract_type
string

Contract type: HEDGE_FAK (spot/FAK rate, resolved in ~2 business days) or LONG_NAC (Named Account Contract, AE will communicate timeline). Omit if unspecified — defaults to HEDGE_FAK.

Enum: "HEDGE_FAK" "LONG_NAC"
origin_address_fid
string

Origin address, specified as a Flexport FID string beginning with 'flx::' (not a numeric ID). Obtained from the address_fid field returned by network_search_addresses, or the commerce_address_fid field returned by network_search_google_addresses if no matching address is found.

origin_port_id
integer

Origin port, specified as a numeric ID. Obtained from the port_id field returned by network_search_ports.

transportation_mode
required
string

Transportation mode: air, ocean_fcl, ocean_lcl

Enum: "air" "ocean_fcl" "ocean_lcl"
Responses
200

Successful tool call.

Response Schema: application/json
client_request_id
string

Created client request ID, null if request failed

errors
required
Array of strings

Error messages if the request failed, empty if successful

nextAction
required
string

Next action for the user

post/tools/rates_request_rate
Request samples
application/json
{
  • "cargo_ready_date": "string",
  • "destination_address_fid": "string",
  • "destination_port_id": 0,
  • "freight_type": "port_to_port",
  • "incoterm": "CFR",
  • "note": "string",
  • "offering_contract_type": "HEDGE_FAK",
  • "origin_address_fid": "string",
  • "origin_port_id": 0,
  • "transportation_mode": "air"
}
Response samples
application/json
{
  • "client_request_id": "string",
  • "errors": [
    • "string"
    ],
  • "nextAction": "string"
}

Search instant prices

Search available instant-price freight rates for Ocean FCL, Ocean LCL, or Air shipments, given origin, destination, cargo-ready date, incoterm, and cargo details. Returns rate options with carrier, pricing, transit time, charge breakdown, available add-on services, detention options, and CO2e emissions. Doesn't support dangerous goods or FTL/road-only shipments.

This operation is a synthetic representation of an MCP tools/call invocation, not a literal REST endpoint. The Flexport MCP server exposes a single JSON-RPC 2.0 endpoint at POST https://mcp.flexport.com/mcp (MCP Streamable HTTP transport) — the tool name and arguments below are carried in the JSON-RPC request body, not in the HTTP path.

Permissions (any of): Admin, Billing, Member

Request
Request Body schema: application/json
required
required
object

Cargo details. For OCEAN_FCL, provide container_info with container counts. For OCEAN_LCL or AIR, provide loose_cargo_info with total_weight_kg and total_volume_cbm; for AIR, also provide shipping_units with dimensions to detect oversized cargo. Must include dangerous_goods screening.

object

FCL container counts. Required for OCEAN_FCL.

required
object

Dangerous goods screening. Required.

object

Loose cargo details. Required for OCEAN_LCL and AIR.

cargo_ready_date
required
string

ISO date when cargo is ready at origin, e.g. 2025-09-01.

destination_commerce_address_fid
string

Destination address — a Flexport FID string beginning 'flx::', not a numeric ID. Required when freight_type is PORT_TO_DOOR or DOOR_TO_DOOR; also accepted for *_TO_PORT to let the backend resolve the nearest port from the address coordinates. Use the address_fid from a network_search_addresses result for an address already onboarded in Flexport, or the commerce_address_fid from a network_search_google_addresses result for a general address (e.g. city, postal code, street address).

destination_port_id
integer

Destination port — a numeric ID, taken from the port_id field of a network_search_ports result. Used when freight_type is PORT_TO_PORT or DOOR_TO_PORT and a specific port is specified. Mutually exclusive with destination_commerce_address_fid for PORT.

freight_type
required
string

Service scope controlling pickup/delivery inclusion: PORT_TO_PORT, PORT_TO_DOOR, DOOR_TO_PORT, or DOOR_TO_DOOR. Determined by whether the origin/destination is a port ID (PORT) or an address (DOOR).

Enum: "port_to_port" "port_to_door" "door_to_port" "door_to_door"
incoterm
required
string

Trade term governing cost/risk split: EXW, FCA, FAS, FOB, CFR, CIF, CPT, CIP, DAP, DAT, DPU, or DDP.

Enum: "CFR" "CIF" "CIP" "CPT" "DAP" "DAT" "DDP" "DPU" "EXW" "FAS" "FCA" "FOB"
origin_commerce_address_fid
string

Origin address — a Flexport FID string beginning 'flx::', not a numeric ID. Required when freight_type is DOOR_TO_PORT or DOOR_TO_DOOR; also accepted for PORT_TO_* to let the backend resolve the nearest port from the address coordinates. Use the address_fid from a network_search_addresses result for an address already onboarded in Flexport, or the commerce_address_fid from a network_search_google_addresses result for a general address (e.g. city, postal code, street address).

origin_port_id
integer

Origin port — a numeric ID, taken from the port_id field of a network_search_ports result. Used when freight_type is PORT_TO_PORT or PORT_TO_DOOR and a specific port is specified. Mutually exclusive with origin_commerce_address_fid for PORT.

transportation_mode
required
string

Freight mode: OCEAN_FCL, OCEAN_LCL, or AIR.

Enum: "air" "ocean_fcl" "ocean_lcl"
Responses
200

Successful tool call.

Response Schema: application/json
empty_reason
string

Set when results is empty. AIR_CARGO_OVERSIZED means one or more packages exceed regional dimension limits. NO_RESULTS means no instant-price rates were found.

errors
Array of strings
required
Array of objects

List of available rate options.

Array
required
Array of objects

Eligible add-on services for this rate. force_included=true means the service is automatically included and cannot be removed; force_included=false means it is optional.

carrier_name
string

Carrier or service provider name, e.g. 'Evergreen', 'Flexport Air Standard'.

required
Array of objects

Itemized charge line items. Each item includes a category (freight, origin, destination, customs, additional, capital), title, amount, and unit.

co2e_tonnes
number

Estimated CO2-equivalent emissions in tonnes for this shipment. Null if unavailable.

required
Array of objects

Available detention free-day add-on tiers that can be purchased.

detention_base_free_days
integer

Included detention free days at no extra cost. Null if not applicable.

effective_date
string

ISO timestamp when the rate becomes valid.

expiration_date
string

ISO timestamp when the rate expires.

gri_applicable
boolean

Whether General Rate Increase applies. Null for AIR.

item_snapshot_id
required
string

Snapshot ID for this rate item. Pass to evaluate_price and submit_booking to identify the selection.

object

TEU allocation data for NAC (SSAT) rates. Present only when rate_type=NAC; always null for non-FCL rates. Shows available vs total capacity per sailing week. Each week includes a feasible flag indicating whether available_allocation covers the shipment's requested_teus.

port_to_port_transit_max_days
integer
port_to_port_transit_min_days
integer
rate_type
string

NAC (Named Account Contract — client-specific negotiated rate) or FAK (Freight All Kinds — spot rate). Only applicable for OCEAN_FCL; null for LCL and AIR.

object

Route port information extracted from the offering bundle.

service_level
string

Raw service level: 'standard'/'premium' for FCL, air service tier for AIR, service level for LCL.

tags
required
Array of strings

Offering tags. Common values: NO_ROLL, EQUIPMENT_GUARANTEE, EXPEDITED_SAILING, SUBJECT_TO_ROLL, CHEAPEST, FASTEST.

required
object
total_transit_max_days
integer
total_transit_min_days
integer
search_snapshot_id
string

Snapshot ID for this search. Pass to follow-up calls to identify the search session.

post/tools/rates_search_instant_price
Request samples
application/json
{
  • "cargo": {
    • "container_info": {
      • "container_20ft": 0,
      • "container_40ft": 0,
      • "container_40ft_hc": 0,
      • "container_45ft_hc": 0
      },
    • "dangerous_goods": {
      • "contains_dangerous_good": true,
      • "dangerous_goods_types": [
        ],
      • "lithium_batteries_packing_types": [
        ]
      },
    • "loose_cargo_info": {
      • "shipping_units": [
        ],
      • "total_volume_cbm": 0,
      • "total_weight_kg": 0
      }
    },
  • "cargo_ready_date": "string",
  • "destination_commerce_address_fid": "string",
  • "destination_port_id": 0,
  • "freight_type": "port_to_port",
  • "incoterm": "CFR",
  • "origin_commerce_address_fid": "string",
  • "origin_port_id": 0,
  • "transportation_mode": "air"
}
Response samples
application/json
{
  • "empty_reason": "string",
  • "errors": [
    • "string"
    ],
  • "results": [
    • {
      • "addon_service_options": [
        ],
      • "carrier_name": "string",
      • "charge_line_items": [
        ],
      • "co2e_tonnes": 0,
      • "detention_addon_options": [
        ],
      • "detention_base_free_days": 0,
      • "effective_date": "string",
      • "expiration_date": "string",
      • "gri_applicable": true,
      • "item_snapshot_id": "string",
      • "nac_allocation": {
        },
      • "port_to_port_transit_max_days": 0,
      • "port_to_port_transit_min_days": 0,
      • "rate_type": "string",
      • "route": {
        },
      • "service_level": "string",
      • "tags": [
        ],
      • "total_price": {
        },
      • "total_transit_max_days": 0,
      • "total_transit_min_days": 0
      }
    ],
  • "search_snapshot_id": "string"
}

Track shipment

Search for a Flexport shipment by FLEX-ID, name, or client-assigned tag. Returns up to 20 matching shipments with full tracking detail: route stops, containers with last-free-day info, customs declarations with hold status, exceptions, work item tasks, and metadata tags.

This operation is a synthetic representation of an MCP tools/call invocation, not a literal REST endpoint. The Flexport MCP server exposes a single JSON-RPC 2.0 endpoint at POST https://mcp.flexport.com/mcp (MCP Streamable HTTP transport) — the tool name and arguments below are carried in the JSON-RPC request body, not in the HTTP path.

Permissions (any of): Admin, Analyst, Billing, Member, Tracker

Request
Request Body schema: application/json
required
flex_id
string

Flexport FLEX-ID to search for (e.g. "FLEX-1234567"). Exact match only — unlike name and tag, an ID with no exact match returns no results rather than a close (fuzzy) one. Mutually exclusive with name and tag — supply exactly one.

name
string

Shipment name to search for. Matches exactly when possible, otherwise returns close (fuzzy) matches. Mutually exclusive with flex_id and tag — supply exactly one.

tag
string

Client-assigned tag value to search for. Matches exactly when possible, otherwise returns close (fuzzy) matches. Mutually exclusive with flex_id and name — supply exactly one.

Responses
200

Successful tool call.

Response Schema: application/json
required
Array of objects

Matching shipments (up to 20).

Array
required
Array of objects

Containers with demurrage and detention last-free-day info.

created_at
required
string

ISO-8601 timestamp when the shipment was created.

required
Array of objects

Customs declarations with filing status and PGA hold information.

required
Array of objects

Active and historical operational exceptions.

flex_id
required
string

Flexport FLEX-ID of the shipment.

incoterm
string

Incoterm from ExecutionOrder (e.g. FOB, CIF, DDP). Null when not set or INVALID.

is_completed
boolean

True when the shipment is administratively complete. Tracked separately from status — a shipment can be at FINAL_DESTINATION and still not be complete. Null when unknown.

required
Array of objects

Shipment lifecycle milestones with status and date. Mode-filtered: only milestones applicable to this shipment's transportation mode are included.

mode
string

Transportation mode from ExecutionOrder transit offering (OCEAN_FCL, OCEAN_LCL, AIR, TRUCK_FTL, TRUCK_LTL).

name
required
string

Shipment name.

priority
required
string

Shipment priority (HIGH or STANDARD).

required
Array of objects

Route stops: ORIGIN, PORT_OF_LOADING, PORT_OF_UNLOADING, DESTINATION.

status
string

Transportation status from itinerary (e.g. IN_TRANSIT_TO_ARRIVAL_PORT). Null when not yet set or INVALID.

required
Array of objects

Client-assigned metadata tags on this shipment.

required
Array of objects

Open client-facing work items (tasks requiring client action).

post/tools/track_shipment
Request samples
application/json
{
  • "flex_id": "string",
  • "name": "string",
  • "tag": "string"
}
Response samples
application/json
{
  • "shipments": [
    • {
      • "containers": [
        ],
      • "created_at": "string",
      • "customs": [
        ],
      • "exceptions": [
        ],
      • "flex_id": "string",
      • "incoterm": "string",
      • "is_completed": true,
      • "milestones": [
        ],
      • "mode": "string",
      • "name": "string",
      • "priority": "string",
      • "route": [
        ],
      • "status": "string",
      • "tags": [
        ],
      • "tasks": [
        ]
      }
    ]
}
➔ Next to Milestones