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
| Method | Path | Purpose |
|---|---|---|
| GET | / | Service discovery (name, version, tool count, endpoints). |
| GET | /health | Liveness probe used by Render. |
| POST | /tools/list | Return schemas for all registered tools. |
| POST | /tools/call | Execute a tool by name with the provided arguments. |
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.
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).
Tools
| Name | Description |
|---|---|
validate_address | Validate + normalize a shipping address through the configured carrier. |
get_quote_preview | Non-binding rate preview for a package. Final rates come from the Java API. |
Tools delegate to pluggable ShippingProvider implementations
(mock, ups, fedex, dhl, usps) 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.
Running locally
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
Consumers
- ShipSmart-API (Python/FastAPI): points
SHIPSMART_MCP_URLat the deployed server and calls/tools/list+/tools/callfrom its orchestration and advisor services. - ShipSmart-Orchestrator (Java/Spring Boot): 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.