Syncnox 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
get_job_info	Fetch the details of a specific job by its ID
add_job	Add a single job (address geocoded automatically)
add_jobs	Add multiple jobs from a JSON list of dictionaries (addresses geocoded automatically)
import_jobs_from_text	Import jobs from CSV content passed directly as text
import_jobs_from_file	Import a list of jobs from a local CSV/Excel file path

Project Layout

syncnox-mcp/
├── server.py          ← entry point, Streamable HTTP app
├── middleware.py      ← API-key auth middleware (production ASGI wrapper)
├── config.py          ← settings loaded from .env
├── api_client.py      ← shared httpx client for Syncnox backend
├── tools/
│   ├── __init__.py    ← central tools registry exposing register_all()
│   ├── routes.py      ← route-related tools (get_route, optimize_route, get_eta)
│   ├── stops.py       ← stop-related tools (add_stop)
│   └── jobs.py        ← job-related tools (get_job_info)
├── 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

Deployment on EC2

cd syncnox-mcp
git pull
sudo systemctl restart syncnox-mcp.service