Customer Order MCP (Python)

A safe Python 3.11+ MCP server modeled on the Java/Spring project weibxiao/internal-mcp-server. It uses the official MCP Python SDK and exposes Streamable HTTP at http://localhost:8000/mcp.

Tools

• create_customer(customer_id, name, email) creates an ACTIVE demo customer.
• search_customers(query, limit=10) searches ID, name, and email (1–25 results).
• get_customer(customer_id) returns one minimal customer profile.
• create_pending_order(customer_id, sku, quantity, unit_price) creates an order in PENDING_REVIEW only. It never charges, submits, reserves, or fulfills.
• get_orders_by_customer(customer_id) lists the customer's orders.
• run_health_check() returns safe service status.
• Resource: internal://service-info.

Run locally

Using uv:

uv sync --extra test
uv run pytest
uv run customer-order-mcp

Or using standard Python:

python -m venv .venv
source .venv/bin/activate       # Windows: .venv\Scripts\activate
python -m pip install -e ".[test]"
pytest
customer-order-mcp

Connect an MCP client or the MCP Inspector to http://localhost:8000/mcp.

npx -y @modelcontextprotocol/inspector

Fixing 421 Misdirected Request

The MCP SDK protects local servers from DNS-rebinding attacks. A 421 response means the request's Host header is not allowed. This commonly happens with an ngrok URL, reverse proxy, LAN hostname, or when connecting to 0.0.0.0.

For a tunnel such as https://example-name.ngrok-free.app, start the server with the exact public host and browser origin:

MCP_ALLOWED_HOSTS="example-name.ngrok-free.app" \
MCP_ALLOWED_ORIGINS="https://example-name.ngrok-free.app" \
uv run customer-order-mcp

Multiple values are comma-separated. Do not include https:// in MCP_ALLOWED_HOSTS; do include it in MCP_ALLOWED_ORIGINS. If a proxy sends a port in the Host header, add example-name.ngrok-free.app:* instead. Keep this allowlist narrow rather than disabling the protection.

To listen on all network interfaces for local Docker or LAN testing:

MCP_HOST=0.0.0.0 uv run customer-order-mcp

Binding to 0.0.0.0 makes the process reachable beyond localhost and disables the SDK's automatic localhost-only allowlist unless explicit allowlists are set.

Container

docker build -t customer-order-mcp:0.1.0 .
docker run --rm -p 8000:8000 customer-order-mcp:0.1.0

Design and storage

The MCP layer (server.py) is deliberately thin. service.py owns validation and business rules, while store.py is the storage boundary. InMemoryStore is thread-safe and contains two demo customers; all changes disappear on restart. Replace it with an authenticated database/API adapter for real use while preserving the service-facing methods.

Validation includes unique customer IDs/emails, validated email format, nonblank search/SKU fields, search limits of 1–25, quantities of 1–100, positive finite prices with at most two decimal places, and an existing customer requirement.

Production safety

Do not expose this demo publicly with real customer data. Add OAuth or an API gateway, authorize every lookup and mutation, audit tool calls without logging secrets or sensitive payloads, use least-privilege integrations, and replace in-memory storage. Order creation intentionally stops at PENDING_REVIEW.

Note about the Java reference

The Python server includes the Java repository's current customer creation and customer-order lookup tools in addition to the tools listed in its README. Its MCP annotations correctly mark customer/order creation as state-changing and non-idempotent.