cd /news/ai-agents/building-a-production-python-mcp-ser… · home › topics › ai-agents › article
[ARTICLE · art-173396] src=dev.to ↗ pub= topic=ai-agents verified=true sentiment=· neutral

Building a Production Python MCP Server for International Air Freight & Volumetric Weight (FastMCP + Glama Docker Lessons)

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.

recommendation

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.

more in playbook: Designing agent systems
by read3 min views10 publishedNov 20, 2026

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).

Instead of exposing a monolithic prompt wrapper, we scoped the server to three small, strictly typed MCP tools:

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 track_aqx_shipment`` HF-######## airwaybill milestones via https://aqxlogistics.com/api/track (mapped to 10154`` check_us_store_forwarding 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
    )
    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",
    }

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:

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

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"
]

>= 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.

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.

── more in #ai-agents 4 stories · sorted by recency
── more on @aqx logistics 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/building-a-productio…] indexed:0 read:3min 2026-11-20 · —