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

---

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:

Question	Source
"which reefers are free"	SQLite - list_vehicles
"how long may a driver drive"	RAG - search_regulations
"what is that in dollars"	ECB rates - currency_rate
"find a truck and check the driver's hours"	SQLite plus RAG in sequence

---

Data sources

Source	Contents	Module
SQLite	10 vehicles, 8 drivers, 3 clients, orders	src/db/
Documents (RAG)	5 markdown files: driving time, tachograph, contract, claims, cargo types	src/rag/, data/docs/
External APIs	ECB exchange rates, Open-Meteo weather	src/server/tools/external.py

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

Tool	Source	Access	Context mechanism demonstrated
list_vehicles	SQLite	guest, dispatcher	ctx.info
plan_assignment	SQLite	dispatcher	report_progress, debug with extra, set_state
book_vehicle	SQLite	dispatcher	send_notification, disable_components, error paths
get_stats	SQLite	guest, dispatcher	-
search_regulations	RAG	guest, dispatcher	ctx.info
get_contract_clause	RAG	guest, dispatcher	-
list_documents	RAG	guest, dispatcher	-
currency_rate	ECB	guest, dispatcher	external failure handling
route_weather	Open-Meteo	guest, dispatcher	external failure handling

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

python -m scripts.capture_demo runs the whole scenario in one pass and writes logs/demo_run.md — verbatim output of every step against a live server: tests, authorization, role separation, tool calls with progress and rejection reasons, agent routing, metrics, and one example of each required log record type.

---

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.