Flexport REST, MCP, and Webhook Architecture

Overview

Use three explicit provider planes: REST v3 for resource operations, MCP Streamable HTTP JSON-RPC for permissioned assistant tools, and signed webhooks for notifications. Join them only through durable application policy and reconciliation.

Prerequisites

Capability inventory split into reads, mutations, events, and assistant tools
Identity, account, environment, and data-flow boundaries
Business approval, operation ledger, queue, and recovery requirements

Instructions

Step 1: Draw provider surfaces

Show api.flexport.com, mcp.flexport.com/mcp, and public HTTPS webhook ingress as distinct external nodes.

Step 2: Place credential boundaries

Use endpoint-scoped OAuth clients per REST workload, authenticated MCP sessions with documented tool roles, and a separate webhook secret.

Step 3: Separate control and data

Put business approval and policy before booking/trade mutations; keep payload handling in minimized data services.

Step 4: Add durable state

Persist operation keys, provider references, event dedupe state, cursor/link checkpoints, and redacted outcomes.

Step 5: Add reconciliation

Connect events and uncertain outcomes to authorized REST/resource reads. Never make webhook delivery the sole source of truth.

Step 6: Prove failure paths

Model token-cache failure, permission denial, additive schema change, duplicate/missing event, ambiguous mutation, and rollback.

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

A booking assistant queries rates through MCP, sends an exact candidate to an approval service, and records one operation key before booking. Signed events enqueue notifications, while a reconciler reads provider state to close gaps.

Error Handling

Failure	Response
REST and MCP contracts collapsed	Split transport, auth/session, errors, and pagination before implementation.
Webhook directly mutates core state	Insert verified durable enqueue and reconciliation.
Approval follows booking	Move it before the provider mutation.
Architecture logs payloads	Replace them with redacted operation receipts.

flexport-reference-architecture