Flexport Dual-Surface Client Contracts

Overview

REST resources and MCP tools are two distinct public surfaces. Keep separate transports, authentication/session handling, error models, and pagination adapters behind business-level interfaces.

Prerequisites

Inventory of required REST endpoints and MCP tools
Pinned account/version behavior and schema snapshot date
Runtime validation, redaction, timeout, and test-fixture strategy

Instructions

Step 1: Define business ports

Express outcomes such as readShipment, browseRisk, or evaluateRate; keep HTTP paths and MCP JSON-RPC details behind adapters.

Step 2: Build the REST adapter

Use base https://api.flexport.com, Bearer authentication, optional Flexport-Version, documented envelopes, status/code/message errors, and link-style pagination where documented.

Step 3: Build the MCP adapter

Use Streamable HTTP JSON-RPC at POST https://mcp.flexport.com/mcp. Treat the per-tool paths shown in reference pages as synthetic documentation, not literal REST routes.

Step 4: Validate at runtime

Accept documented additive fields, preserve opaque identifiers/cursors, and reject missing required fields without guessing replacements.

Step 5: Normalize evidence, not schemas

Return a stable application result and surface provider metadata separately; do not force REST and MCP payloads into one lossy provider model.

Step 6: Contract-test both surfaces

Replay sanitized official-shape fixtures for success, pagination, permission errors, additive fields, and ambiguous transport failure.

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

The application calls one ShipmentReader interface. Its REST adapter follows shipment pagination links; its MCP adapter sends tools/call for browse_shipments and advances end_cursor, while both return the same minimal internal summary.

Error Handling

Failure	Response
Synthetic tool path called as REST	Replace it with an MCP JSON-RPC `tools/call` request.
Unknown additive field	Preserve or ignore it safely; do not fail a tolerant reader.
Required field absent	Quarantine the response and compare against the current schema.
Transport outcome ambiguous	Reconcile the operation rather than blind-retrying a mutation.

flexport-sdk-patterns