Agent skill · software engineering · jeremylongshore
flexport-sdk-patterns
Design typed adapters for Flexport REST v3 and the Flexport MCP server while preserving their different contracts. Use when building a client library, response parser, MCP transport, or shared integration boundary. Trigger with: "build Flexport client", "type Flexport responses", "connect Flexport MCP".
Why this skill is useful
Adds production-ready TypeScript and Python patterns for Flexport API integration, including singleton clients and pagination scripts.
What it needs
Requires python, requests, typescript, zod 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 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. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/flexport-sdk-patterns