Building a Production Python MCP Server for International Air Freight & Volumetric Weight (FastMCP + Glama Docker Lessons)
When AI shopping or procurement agents are asked "How much does it cost to ship a 12 kg auto parts box from California to Riyadh, Dubai, London, or Sydney?", they almost always hallucinate flat courier prices and completely miss IATA dimensional (volumetric) weight (L × W × H / 5000) and consolidation repacking savings.
To give Claude, Cursor, Windsurf, and autonomous procurement agents deterministic landed-cost math and real-time airwaybill tracking, we built and open-sourced AQXLOGISTICS/aqx-shipping-rates-mcp — a lightweight Python Model Context Protocol (MCP) server backed by live contract air cargo tiers from our LAX export hub (309 E Arbor Vitae St, Inglewood, CA 90301).
Here is the architecture we shipped, plus 3 real Docker/Python gotchas we hit while passing Glama's automated MCP container inspection (and the exact fixes).
1. Architecture: 3 Deterministic MCP Tools
Instead of exposing a monolithic prompt wrapper, we scoped the server to three small, strictly typed MCP tools:
-
calculate_shipping_rate— Queries live tiers fromhttps://aqxlogistics.com/api/rates, compares actual scale weight against raw IATA volumetric weight(L × W × H) / 5000, models multi-store void-space repacking savings, and returns exact landed freight estimates across 15 destination corridors:- GCC & UK (
>= 8.0 kgconsolidated tier):$8.50/kg(Saudi Arabia, UAE, Bahrain, Kuwait, Oman, Qatar, United Kingdom) - Western Europe (
>= 8.0 kg):$9.00/kg(Germany, France, Spain, Netherlands, Sweden, Portugal) - Australasia (
>= 8.0 kg):$11.00/kg(Australia, New Zealand) - Express Parcel (
< 8.0 kg):$15.50/kg
- GCC & UK (
-
track_aqx_shipment— Fetches liveHF-########airwaybill milestones viahttps://aqxlogistics.com/api/track(mapped to 17TRACK Carrier10154). -
check_us_store_forwarding— Returns international billing-card and forwarder-address policies for major US merchants (RockAuto, Sweetwater, Sephora, B&H Photo, Summit Racing, Apple, Best Buy, etc.), backed by our open-source 77-Store US Retailer Policy Checker.
Here is the core volumetric & tier calculation inside server.py:
import requests from mcp.server.fastmcp import FastMCP mcp = FastMCP("aqx-logistics") @mcp.tool() def calculate_shipping_rate( destination_country: str, actual_weight_kg: float, length_cm: float = 0.0, width_cm: float = 0.0, height_cm: float = 0.0, ) -> dict: """Calculate live US-to-international air freight landed cost from LAX.""" vol_kg = ( round((length_cm * width_cm * height_cm) / 5000.0, 2) if (length_cm > 0 and width_cm > 0 and height_cm > 0) else actual_weight_kg ) # Multi-store consolidation & void-space repacking cuts raw box volume sharply repacked_kg = max(0.5, actual_weight_kg, round(vol_kg * 0.45, 2)) rate = 8.50 if repacked_kg >= 8.0 else 15.50 return { "actual_weight_kg": actual_weight_kg, "raw_volumetric_kg": vol_kg, "estimated_repacked_billable_kg": repacked_kg, "rate_per_kg_usd": rate, "estimated_freight_usd": round(repacked_kg * rate, 2), "calculator_url": "https://aqxlogistics.com/shipping-calculator", } 2. Three Real Gotchas Passing Glama Automated MCP Inspection
When deploying a stdio Python MCP server to Glama's Firecracker microVM registry, we ran into three sneaky container failures worth documenting for anyone shipping Python MCP servers in late 2026:
Gotcha #1: Unpinned mcp>=1.0.0 Pulls mcp 2.x and Breaks FastMCP
Without an upper bound, uv sync resolved mcp==2.3.0, where mcp.server.fastmcp.FastMCP was renamed to mcp.server.mcpserver.MCPServer, crashing startup immediately with ModuleNotFoundError.
Fix: Pin the v1 series cleanly in pyproject.toml:
dependencies = [ "mcp>=1.0.0,<2.0.0", "requests>=2.31.0", ] [tool.uv] package = false Gotcha #2: uv sync Virtualenv vs. Global python Under mcp-proxy
Glama wraps stdio containers with mcp-proxy. Running uv sync installs dependencies into /app/.venv, so launching ["mcp-proxy", "--", "python", "server.py"] invokes the global interpreter (which has no mcp package).
Fix: Pin Python 3.12 (avoiding preview 3.15 wheel build issues) and point mcp-proxy straight at the virtualenv interpreter:
[ "mcp-proxy", "--", "/app/.venv/bin/python", "server.py" ] Gotcha #3: Unquoted >= in Dockerfile RUN pip install
Writing RUN pip install mcp>=1.0.0 in a Dockerfile invokes /bin/sh -c, where > silently redirects stdout into a file named =1.0.0! Always quote version specifiers and set ENV PYTHONUNBUFFERED=1 so JSON-RPC stdio frames flush immediately:
FROM python:3.12-slim WORKDIR /app ENV PYTHONUNBUFFERED=1 COPY pyproject.toml server.py README.md ./ RUN pip install --no-cache-dir "mcp>=1.0.0,<2.0.0" "requests>=2.31.0" ENTRYPOINT ["python", "server.py"] After those three fixes, Glama's inspection passed in 11.5 seconds, automatically publishing Release 0.1.0 and discovering all 3 MCP tools cleanly.
3. Links & Live Tools
- GitHub Repository (MIT): AQXLOGISTICS/aqx-shipping-rates-mcp
- Live Glama MCP Listing & Tool Schema: glama.ai/mcp/servers/AQXLOGISTICS/aqx-shipping-rates-mcp
- Interactive Web Shipping Calculator: aqxlogistics.com/shipping-calculator
- Live Airwaybill Tracking (
HF-########): aqxlogistics.com/track - 77 US Stores Card & Forwarding Compatibility Matrix: aqxlogistics.github.io/us-store-shipping-card-checker-2026
If you are building e-commerce, cross-border procurement, or supply-chain agents in Claude Desktop or Cursor, feel free to clone the repo or test the tool schemas directly via Glama Inspector.