ShipSmart-MCP

Standalone MCP (Model Context Protocol) server exposing ShipSmart's shipping tools (validate_address, get_quote_preview, …) over a small HTTP contract.

It is the single source of truth for tool behavior across the platform. Both ShipSmart-API (Python / FastAPI — RAG & LLMs) and ShipSmart-Orchestrator (Java / Spring Boot — upcoming AI features) call this server instead of implementing tools in-process.

HTTP contract

Wire-compatible with the MCP tools/list and tools/call semantics: each call returns { success, content: [...], error? }, where content is a list of {type, text} blocks suitable for LLM consumption.

/docs and /redoc are mounted only when APP_ENV != production.

Auth

If MCP_API_KEY is set on the server, every POST /tools/* request must send the matching value in X-MCP-Api-Key. If MCP_API_KEY is empty, auth is disabled (local dev only). GET / and GET /health are always unauthenticated so health checks and service discovery work without the shared secret.

Error responses

Validation and execution errors deliberately return HTTP 200 with success=false so consumers can distinguish protocol-level failures (4xx) from tool-level failures (200 + success=false).

Tools

Tools delegate to pluggable ShippingProvider implementations selected by SHIPPING_PROVIDER.

Adding a tool is a matter of dropping a new class into app/tools/ and registering it in app/main.py.

Provider startup behavior

• SHIPPING_PROVIDER=mock (default) emits a loud WARNING at startup so operators are not surprised by fake data.

• Selecting a real carrier (ups/fedex/dhl/usps) without all required credentials raises ValueError at startup. There is no silent fallback to mock — misconfiguration fails fast and visibly.

Configuration

All settings are loaded from environment variables (or .env for local dev). See .env.example for the full list and defaults.

Running locally

Prerequisites: Python 3.13+ and uv.

cp .env.example .env
# fill in credentials if you want real carrier integration; default is SHIPPING_PROVIDER=mock
uv sync
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8001

Smoke test:

curl -s http://localhost:8001/health
curl -s -X POST http://localhost:8001/tools/list
curl -s -X POST http://localhost:8001/tools/call \
  -H 'Content-Type: application/json' \
  -d '{
        "name": "validate_address",
        "arguments": {
          "street": "123 Main St",
          "city":   "San Francisco",
          "state":  "CA",
          "zip_code": "94105"
        }
      }'

Tests

uv run pytest

Observability

RequestLoggingMiddleware (app/core/middleware.py) handles correlation IDs for every request:

• Reads X-Request-Id from the inbound request, or mints a UUID hex if absent.

• Reads W3C traceparent, or mints a fresh one if absent or malformed.

• Echoes both headers on the response so callers can grep by ID across services.

• Emits one log line per request on the shipsmart_mcp.requests logger:

  GET /health → 200 (1.4ms) [a1b2c3...]

Pass X-Request-Id from upstream services to stitch a single request across ShipSmart-API → MCP → carrier APIs.

Deployment (Render)

render.yaml is a Render Blueprint defining the deployed service:

• Python web service, build via pip install uv && uv sync, start via uvicorn app.main:app --host 0.0.0.0 --port $PORT.

• Health check at /health.

• MCP_API_KEY is sync: false — set it once in the Render dashboard and use the same value for every consumer's SHIPSMART_MCP_API_KEY.

• Default SHIPPING_PROVIDER=fedex pointing at https://apis-sandbox.fedex.com (FedEx sandbox, not production). Override the base URL when promoting to live carrier traffic.

• CORS origins are pinned in the blueprint to the deployed consumer URLs.

Provision by pointing Render at this repo; all sync: false env vars must be filled before the first deploy succeeds.

Consumers

• ShipSmart-API (Python / FastAPI; deployed as shipsmart-api-python on Render): points SHIPSMART_MCP_URL at this server and calls /tools/list + /tools/call from its orchestration and advisor services.

• ShipSmart-Orchestrator (Java / Spring Boot; deployed as shipsmart-api-java on Render): will call the same HTTP contract from its upcoming AI-assist flows. No tool logic lives in the Java codebase.

This keeps the tool layer centralized — add a tool once, every service gets it.