Syncnox MCP Server

An MCP server that gives AI agents (like Claude) direct access to the Syncnox route-management backend.

Transport

Streamable HTTP — the server exposes a single HTTP endpoint at /mcp.
This means you can deploy it in Docker, expose it over the network, and connect multiple remote clients.

Authentication

Every request must include the header:

X-API-Key: <your MCP_API_KEY>

The server itself also authenticates to your Syncnox FastAPI backend using a Bearer token (API_KEY).

Available Tools

Tool	What it does
add_stop	Add a new stop to an existing route
optimize_route	Re-order stops for fastest time or shortest distance
get_eta	Get ETA for the whole route or a single stop
get_route	Fetch full route details including all stops

Project Layout

syncnox-mcp/
├── server.py          ← entry point, Streamable HTTP app + auth middleware
├── config.py          ← settings loaded from .env
├── api_client.py      ← shared httpx client for Syncnox backend
├── tools/
│   ├── __init__.py
│   └── routes.py      ← route & stop tools (add more files here)
├── requirements.txt
└── .env               ← secrets (not committed to git)

Setup

# 1. Create & activate virtual env
python -m venv .venv
source .venv/bin/activate

# 2. Install dependencies
pip install -r requirements.txt

# 3. Configure
cp .env .env.local    # edit values
# Set: API_BASE_URL, API_KEY, MCP_API_KEY, PORT

# 4. Run
python server.py

Server starts at http://0.0.0.0:8100.

Connecting a Client

In Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "syncnox": {
      "type": "http",
      "url": "http://localhost:8100/mcp",
      "headers": {
        "X-API-Key": "changeme-mcp-secret"
      }
    }
  }
}

Health Check

curl http://localhost:8100/health
# → OK

Adding More Tools

1. Create tools/drivers.py (copy routes.py as a template)
2. Add from tools import drivers in server.py
3. Call drivers.register(mcp) below the existing routes.register(mcp)