{"slug": "building-a-production-python-mcp-server-for-international-air-freight-volumetric", "title": "Building a Production Python MCP Server for International Air Freight & Volumetric Weight (FastMCP + Glama Docker Lessons)", "summary": "A developer at AQX Logistics built and open-sourced aqx-shipping-rates-mcp, a Python Model Context Protocol server using FastMCP that gives AI agents deterministic air freight landed-cost math, including IATA volumetric weight (L×W×H/5000), consolidation repacking savings, and live airwaybill tracking from the company's LAX hub. The writeup documents three container failures hit while passing Glama's automated MCP inspection: an unpinned mcp dependency resolving to 2.3.0 and breaking the FastMCP import, and mcp-proxy launching the global interpreter instead of the uv virtualenv, fixed by pinning mcp<2.0.0 and pointing mcp-proxy at /app/.venv/bin/python.", "body_md": "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.\n\nTo 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](https://github.com/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`).\n\nHere 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).\n\nInstead of exposing a monolithic prompt wrapper, we scoped the server to three small, strictly typed MCP tools:\n\n`calculate_shipping_rate`` https://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 `>= 8.0 kg` consolidated tier):`$8.50/kg` (Saudi Arabia, UAE, Bahrain, Kuwait, Oman, Qatar, United Kingdom)`$9.00/kg` (Germany, France, Spain, Netherlands, Sweden, Portugal)`$11.00/kg` (Australia, New Zealand)`< 8.0 kg`):`$15.50/kg`\n`track_aqx_shipment`` HF-########` airwaybill milestones via `https://aqxlogistics.com/api/track` (mapped to `10154`` check_us_store_forwarding`\nHere is the core volumetric & tier calculation inside `server.py`:\n\n``` python\nimport requests\nfrom mcp.server.fastmcp import FastMCP\n\nmcp = FastMCP(\"aqx-logistics\")\n\n@mcp.tool()\ndef calculate_shipping_rate(\n    destination_country: str,\n    actual_weight_kg: float,\n    length_cm: float = 0.0,\n    width_cm: float = 0.0,\n    height_cm: float = 0.0,\n) -> dict:\n    \"\"\"Calculate live US-to-international air freight landed cost from LAX.\"\"\"\n    vol_kg = (\n        round((length_cm * width_cm * height_cm) / 5000.0, 2)\n        if (length_cm > 0 and width_cm > 0 and height_cm > 0)\n        else actual_weight_kg\n    )\n    # Multi-store consolidation & void-space repacking cuts raw box volume sharply\n    repacked_kg = max(0.5, actual_weight_kg, round(vol_kg * 0.45, 2))\n    rate = 8.50 if repacked_kg >= 8.0 else 15.50\n    return {\n        \"actual_weight_kg\": actual_weight_kg,\n        \"raw_volumetric_kg\": vol_kg,\n        \"estimated_repacked_billable_kg\": repacked_kg,\n        \"rate_per_kg_usd\": rate,\n        \"estimated_freight_usd\": round(repacked_kg * rate, 2),\n        \"calculator_url\": \"https://aqxlogistics.com/shipping-calculator\",\n    }\n```\n\nWhen deploying a `stdio` Python MCP server to [Glama's Firecracker microVM registry](https://glama.ai/mcp/servers/AQXLOGISTICS/aqx-shipping-rates-mcp), we ran into three sneaky container failures worth documenting for anyone shipping Python MCP servers in late 2026:\n\n`mcp>=1.0.0` Pulls `mcp 2.x` and Breaks `FastMCP`\nWithout 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`.\n\n**Fix:** Pin the v1 series cleanly in `pyproject.toml`:\n\n```\ndependencies = [\n    \"mcp>=1.0.0,<2.0.0\",\n    \"requests>=2.31.0\",\n]\n\n[tool.uv]\npackage = false\n```\n\n`uv sync` Virtualenv vs. Global `python` Under `mcp-proxy`\nGlama 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).\n\n**Fix:** Pin Python `3.12` (avoiding preview `3.15` wheel build issues) and point `mcp-proxy` straight at the virtualenv interpreter:\n\n```\n[\n  \"mcp-proxy\",\n  \"--\",\n  \"/app/.venv/bin/python\",\n  \"server.py\"\n]\n```\n\n`>=` in `Dockerfile` `RUN pip install`\nWriting `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:\n\n```\nFROM python:3.12-slim\nWORKDIR /app\nENV PYTHONUNBUFFERED=1\nCOPY pyproject.toml server.py README.md ./\nRUN pip install --no-cache-dir \"mcp>=1.0.0,<2.0.0\" \"requests>=2.31.0\"\nENTRYPOINT [\"python\", \"server.py\"]\n```\n\nAfter those three fixes, Glama's inspection passed in **11.5 seconds**, automatically publishing Release `0.1.0` and discovering all 3 MCP tools cleanly.\n\nIf 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.", "url": "https://wpnews.pro/news/building-a-production-python-mcp-server-for-international-air-freight-volumetric", "canonical_source": "https://dev.to/aqxlogistics-eng/building-a-production-python-mcp-server-for-international-air-freight-volumetric-weight-fastmcp-38ja", "published_at": "2026-11-20 18:07:32+00:00", "updated_at": "2026-11-20 18:14:24.779889+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-tools", "developer-tools"], "entities": ["AQX Logistics", "Model Context Protocol", "FastMCP", "Glama", "Claude", "Cursor", "Windsurf", "uv"], "also_reported_by": [], "takeaway": "Pin mcp>=1.0.0,<2.0.0 because mcp 2.x renames FastMCP to MCPServer and crashes startup, and launch stdio servers through the uv virtualenv interpreter (/app/.venv/bin/python) rather than global python under mcp-proxy.", "recommendation": {"advice": "When shipping a Python MCP server, pin mcp below 2.0.0 and point mcp-proxy at the virtualenv interpreter so FastMCP imports and dependencies resolve correctly.", "playbook": "agent-architecture", "playbook_url": "https://wpnews.pro/playbooks/agent-architecture"}, "alternates": {"html": "https://wpnews.pro/news/building-a-production-python-mcp-server-for-international-air-freight-volumetric", "markdown": "https://wpnews.pro/news/building-a-production-python-mcp-server-for-international-air-freight-volumetric.md", "text": "https://wpnews.pro/news/building-a-production-python-mcp-server-for-international-air-freight-volumetric.txt", "jsonld": "https://wpnews.pro/news/building-a-production-python-mcp-server-for-international-air-freight-volumetric.jsonld"}}