MCP Dispatch Agent

An AI assistant for a freight dispatcher, built on the Model Context Protocol. It takes an order in natural language, picks a vehicle from the fleet, checks the relevant regulations and prepares documents for the client and the driver.

The project has two independent halves:

• MCP server - tools, resources and prompts. Runs on its own; any MCP client can connect to it.

• Agent - a model-to-tool loop on the Claude Messages API. Connects to the server as an ordinary client, using the same Bearer token.

Quick start

git clone https://github.com/yurii-sheremeta/mcp-dispatch-agent.git
cd mcp-dispatch-agent
cp .env.example .env    # fill in your tokens and ANTHROPIC_API_KEY

Local:

python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python -m src.rag.ingest        # build the document index
python -m src.server.main       # server on http://localhost:8000

Docker:

docker compose up --build

Check that it works:

curl http://localhost:8000/health

Talk to the agent (separate terminal, server must be running):

python -m src.agent

Related MCP server: ecmr-mcp

Architecture

flowchart TB
    U([Dispatcher]) --> A

    subgraph AG["Agent - model to tool loop"]
        A[loop.py<br/>Claude Messages API]
        G[guardrails.py<br/>context boundaries]
        M[memory.py<br/>conversation history]
        A --- G
        A --- M
    end

    A -->|Bearer token, HTTP| S

    subgraph SV["MCP server :8000"]
        AU[auth.py<br/>Bearer and roles]
        S[main.py<br/>streamable-http]
        MO[monitoring.py<br/>/health /metrics]
        AU --> S
        S --- MO
    end

    S --> T1[fleet.py]
    S --> T2[docs.py]
    S --> T3[external.py]

    T1 --> DB[(SQLite<br/>fleet, drivers,<br/>orders)]
    T2 --> RAG[(BM25 index<br/>5 documents)]
    T3 --> API[[ECB rates - Open-Meteo]]

    S -.-> LOG[/logs/server.log/]

Routing. The model picks the source itself, based on tool descriptions and the rules in prompts/routing.md:

Data sources

Document search uses BM25, not embeddings. This is a deliberate decision: Anthropic has no embeddings endpoint, and a second API key or a ~400 MB local model is not justified for five short documents. src/rag/retriever.py exposes a narrow search(query, k) interface, so moving to semantic search means replacing a single file.

Tools

Resources: resource://fleet, resource://tariffs, resource://client/{registry_id}/profile Prompts: quote_letter, driver_brief

Security

Authorization. Bearer token in the Authorization header. Two tokens, two roles:

• dispatcher - every tool;

• guest - read-only; plan_assignment and book_vehicle are unavailable.

/health and /metrics are open on purpose: otherwise external monitoring could not reach them.

Safe context boundaries (src/agent/guardrails.py, prompts/guardrails.md):

• Tool results are wrapped in <tool_output trust="data">. Text inside a document is data, not instructions to the model.

• Instruction-override attempts ("ignore previous instructions", <system>) are detected and flagged; the agent continues with the original request.

• Personal data never reaches the logs: redact() masks names, phone numbers and tokens. Logs carry identifiers only (DRV-03, a plate number).

• Tokens in logs are masked down to the last four characters.

Not committed to the repository: .env, the database, the index and the logs

• see .gitignore.

Logging and monitoring

Logs go to both the console and logs/server.log in a single format. Structured data is passed in a separate field and rendered as JSON - readable for a human, parsable by a machine:

2026-08-13 13:11:40 [INFO ] server   | === MCP Dispatch Server starting ===
2026-08-13 13:11:40 [INFO ] server   | Database ready | {"booked": 2, "free": 7, "service": 1}
2026-08-13 13:11:48 [WARNING] auth   | AUTH FAIL | {"client": "172.17.0.1", "reason": "no Authorization header"}
2026-08-13 13:11:48 [INFO ] auth     | AUTH OK | {"client": "172.17.0.1", "role": "dispatcher", "token": "***"}
2026-08-13 13:12:03 [DEBUG] fleet    | Vehicle rejected | {"plate": "TR-9911", "reason": "tachograph: 1.5 h left, 4.9 h needed"}
2026-08-13 13:12:05 [INFO ] fleet    | Assignment scan finished | {"chosen": "TR-4471", "price": 330, "checked": 10}
2026-08-13 13:12:19 [ERROR] fleet    | Vehicle unavailable | {"plate": "TR-2280", "status": "booked"}

A token value is never visible in the logs: mask() keeps the last four characters and redact() in the formatter additionally strips the token key entirely.

Endpoints:

curl http://localhost:8000/health    # {"status":"ok","uptime_seconds":312,...}
curl http://localhost:8000/metrics   # request, error, 401 and tool-call counters

/metrics reports uptime, request count, rejected-authorization count, errors, per-tool call counts, average assignment duration, memory usage and fleet state.

Demonstration

python -m scripts.reset_db        # restore the fleet to its initial state
python -m src.server.main         # terminal 1: server

./scripts/demo.ps1                # terminal 2: curl scenario (401 / 200 / metrics / logs)
python -m scripts.client_demo     # full scenario: progress, logs, RAG, booking
python -m scripts.check_roles     # guest vs dispatcher permissions
python -m src.agent               # interactive chat with the agent

Tests

pytest -q                         # 42 tests
ruff check src tests scripts      # lint

Coverage: authorization (401 without a token, 401 with a wrong one, 200 with a valid one, /health staying public), role separation, token masking, vehicle selection logic, RAG relevance, prompt-injection detection, PII masking, and source routing.

CI (.github/workflows/ci.yml) runs lint and tests, builds the Docker image, starts the container and verifies that /health responds while an unauthorized request receives a 401.

Layout

src/
  server/        MCP server: main, auth, monitoring, logging_conf
    tools/       fleet - docs (RAG) - external (APIs)
  agent/         loop, guardrails, memory, router
  rag/           store (chunking) - retriever (BM25) - ingest (CLI)
  db/            schema.sql - seed.sql - repo.py
prompts/         Prompt Book: system - routing - guardrails - templates
data/docs/       5 documents for RAG
tests/           42 tests
scripts/         demo.ps1 - client_demo - check_roles - reset_db

Limitations

This is a training project, not a production system.

1. The documents in data/docs/ are simplified training extracts, not current legal instruments. Each file carries a notice in its header. Wording must be verified against the applicable regulation before operational use.

2. The data is fictitious: plate numbers, registry IDs and driver names do not correspond to real ones.

3. Tariffs and distances are a simplified model: a lookup table of distances between seven cities and a linear per-kilometre rate instead of a routing service and real pricing.

4. Counters live in process memory. Several replicas would need a Prometheus exporter; the monitoring.py interface anticipates that.

5. Session state is not a database. The assignment draft lives as long as the connection does; a confirmed booking is written to SQLite immediately.

6. BM25 instead of embeddings - see the Data sources section.