corporatetravel-dispatch-mcp

Last verified against code: 2026-08-11

Right repo? You want corporatetravel-dispatch-mcp (this one) for the MCP server. The dispatch platform source lives at corporatetraveldc-dispatch. The public mirror is at ctdi-dispatch.

MCP server exposing the CS Executive Services dispatch platform (Raspberry Pi 5 based), airplanes.live flight tracking, and airframes.io ACARS as portable, agent-agnostic tools. Works with any MCP-compatible agent: Claude Code, Cline, Cursor, Zed, Windsurf, and — via two mcpo HTTP bridges — Open WebUI locally and remote integrations (e.g. a Claude.ai custom connector) publicly.

ALL Public Commits are GPG signed using Key: ABD3976FCC006E0F3FE559177286B3118BA4EFB2. Pubkey is included in this repo as ABD3976FCC006E0F3FE559177286B3118BA4EFB2.gpg.

Tools (34 total; 26 in public-safe mode)

Tool registration lives in dispatch_mcp/tools/__init__.py: register(mcp, public_safe: bool). With DISPATCH_MCP_PUBLIC_SAFE=1 the admin module (7 tools) and second_brain package (1 tool) are never loaded — not merely gated — leaving the 26-tool public-safe subset. Counts verified 2026-08-11 with grep -rc "@mcp.tool" dispatch_mcp/tools/ and against both running mcpo instances' /openapi.json (34 paths private, 26 public).

Dispatch platform — Tier 0 (no auth required) — tools/dispatch.py

Dispatch platform — Watchlist — tools/dispatch.py (bearer token sent)

Dispatch platform — FIDS — tools/fids.py

FAA Aircraft Registry — tools/aircraft.py (local cache on the Pi, updated weekly)

Admin — tools/admin.py (requires DISPATCH_TOKEN; excluded in public-safe mode)

Second Brain — tools/second_brain/remember.py (requires DISPATCH_TOKEN; excluded in public-safe mode)

Flight Tracking — airplanes.live — tools/flight.py (no auth)

Hex resolution order: callsign → registration → hex. Always confirm hex via flight_get_by_registration before adding to watchlist — hex is airframe-bound; callsign-to-hex mappings can be stale day-over-day.

ACARS — airframes.io — tools/acars.py (no auth)

Related MCP server: quads-mcp

Security model: no per-caller auth on admin/second-brain tools

admin._check_token() only verifies the process has a DISPATCH_TOKEN configured — it does not verify the MCP caller presented anything. Every outbound admin call uses that one fixed token regardless of caller. These tools are therefore only safe on instances where reachability itself is the access control (stdio on your own machine, or the loopback/tailnet mcpo instance). Any instance fronted by a public hostname must run with DISPATCH_MCP_PUBLIC_SAFE=1, which never loads them at all. See docs/mcpo-openwebui.md for the two-instance deployment that enforces this.

Install

pip install -e .

Requires Python 3.11+. Dependencies (declared in pyproject.toml): mcp[cli], httpx, pydantic, and jsonschema.

Why jsonschema is pinned here: mcp/server/lowlevel/server.py imports jsonschema unconditionally, but the mcp package does not declare it and the mcp[cli] extra does not reliably pull it in. Without it the server crashes at import. Declared explicitly in this repo's pyproject.toml as of 2026-08-11.

Public mirror gap (2026-08-11): the public GitHub mirror (corporatetravel-dispatch-mcp public copy) is missing the public_safe registration-mode commits. Anyone installing from the public repo's pip install git+https://... instructions gets a build with no way to exclude admin/second_brain tools. Until the mirror is re-synced, do not build a publicly exposed instance from the public repo.

Configure

Retired hostname: ops.csexecutiveservices.com is fully retired and hard-rejected app-side (dispatch platform runner/main.py _RETIRED_HOSTNAMES). It must not appear in any config. Older docs and examples that referenced it as the default DISPATCH_BASE_URL are obsolete.

Use with Claude Code

Register at user scope (persists across projects):

claude mcp add dispatch \
  -e DISPATCH_BASE_URL=http://100.94.80.100:8000 \
  -e DISPATCH_TOKEN=your-token-here \
  --scope user \
  -- dispatch-mcp

Or add to ~/.claude/.claude.json directly under "mcpServers":

{
  "mcpServers": {
    "dispatch": {
      "type": "stdio",
      "command": "/full/path/to/dispatch-mcp",
      "args": [],
      "env": {
        "DISPATCH_BASE_URL": "http://100.94.80.100:8000",
        "DISPATCH_TOKEN": "your-token-here"
      }
    }
  }
}

On the Pi itself, dispatch-mcp-wrapper.sh (repo root) is the preferred command: it extracts DISPATCH_ADMIN_TOKEN from /etc/corporatetraveldc/dispatch-secrets.env without sourcing the file as bash, exports it as DISPATCH_TOKEN, and execs the venv binary at /opt/corporatetraveldc/corporatetravel-dispatch-mcp/venv/bin/dispatch-mcp. Both deployed mcpo services use this wrapper.

Use with Cline / Cursor / Zed / Windsurf

Same MCP JSON config block — each supports mcpServers in their settings file. Point command at the installed dispatch-mcp binary or python -m dispatch_mcp.server.

Use with Open WebUI / Claude.ai / HTTP clients

See docs/mcpo-openwebui.md. Two separate mcpo bridge instances run on the Pi:

• Private, full toolset (34): corporatetraveldc-mcpo.service, port 8082, no public hostname — Open WebUI consumes it via host.containers.internal:8082.

• Public-safe (26): corporatetraveldc-mcpo-public.service, port 8083 (loopback-bound), DISPATCH_MCP_PUBLIC_SAFE=1, fronted by nginx + Cloudflare Tunnel at https://mcp.csexecutiveservices.com — the endpoint remote integrations (e.g. a Claude.ai custom connector) use.

Context efficiency and plan compatibility

MCP tool responses are structured and compact — each tool returns only the data the agent actually needs, rather than dumping raw API payloads into the context window. This matters for subscription plan users:

• Claude Pro — operational dispatch workflows (TFR checks, CPS queries, flight lookups, daily brief) stay well within the message window because context stays lean. Pairing with a context guardian skill (e.g. the dispatch-context-guardian Cowork skill bundled with this deployment) automatically compacts sessions before they hit plan limits.

• Claude Max / API — compact responses reduce per-request token cost and latency.

• Cline / Cursor / Windsurf — same economy; MCP tool calls consume far fewer tokens than equivalent REST-then-paste workflows.

Verify syntax

python -m py_compile \
  dispatch_mcp/server.py \
  dispatch_mcp/config.py \
  dispatch_mcp/client.py \
  dispatch_mcp/tools/__init__.py \
  dispatch_mcp/tools/dispatch.py \
  dispatch_mcp/tools/flight.py \
  dispatch_mcp/tools/admin.py \
  dispatch_mcp/tools/aircraft.py \
  dispatch_mcp/tools/acars.py \
  dispatch_mcp/tools/fids.py \
  dispatch_mcp/tools/second_brain/__init__.py \
  dispatch_mcp/tools/second_brain/remember.py
echo "All clean"

Notes

• Tier 0 endpoints (/api/v1/*) require no authentication.

• dispatch_get_runsheet is Tailscale-gated and only works against the default Tailscale DISPATCH_BASE_URL.

• Admin endpoints require DISPATCH_TOKEN. Create tokens on the Pi: csex-token create.

• dispatch.csexecutiveservices.com has Cloudflare Access on POST routes; it is the transport-failure fallback only, not the primary.

• ops.csexecutiveservices.com is retired and hard-rejected — never use it.

• CUI rules: this server never generates or exposes SHARES/HEARS/HEART frequencies. The platform ships with empty placeholder credential files.

License

MIT