Agent skill · software engineering · jeremylongshore
flexport-reference-architecture
Analyze and design a Flexport integration that separates REST v3 resources, MCP tools, webhook ingress, approval, and reconciliation. Use when producing an architecture, threat model, or service boundary. Trigger with: "design Flexport architecture", "Flexport MCP architecture", "Flexport integration boundaries".
Why this skill is useful
Provides a detailed project structure and specific service patterns for integrating with the Flexport API that the AI wouldn't reliably generate on its own.
What it needs
Requires docker installed locally. Requires flexport account access. About 2k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
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. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/flexport-reference-architecture