eGordian AEO MCP Service

A remote, headless, horizontally stateless MCP service that exposes:

• the AEO (Assignment Estimate Operator) nine-stage deterministic estimating pipeline,

• the private, licensed Gordian CTC catalogue behind a hard licensing firewall,

• an exact allowlist of every operation documented on the eGordian JOC Service Help page,

over MCP protocol revision 2026-07-28 at a single POST /mcp endpoint, plus a minimal REST/status surface and an operator console.

The backend is the product. The console exists only to observe the service.

1. What it is (and is not)

Related MCP server: Trae MCP Monitor

2. Quick start (container)

docker build -t egordian-aeo-mcp .
docker run --rm -p 8080:8080 \
  -e DEPLOYMENT_ENV=production \
  -e AUTH_MODE=bearer \
  -e 'SERVICE_TOKENS=REPLACE_TOKEN|trevor|P-1|catalogue:read,egordian:read,aeo:run,aeo:approve' \
  egordian-aeo-mcp

The service listens on 0.0.0.0:$PORT (default 8080). Nothing else needs to be run locally — clients connect to the deployed URL.

Local development only:

pip install -r requirements-dev.txt
AUTH_MODE=dev DEPLOYMENT_ENV=preview uvicorn app.main:app --host 0.0.0.0 --port 8080
python -m pytest

AUTH_MODE=dev is refused whenever DEPLOYMENT_ENV=production.

3. Remote MCP client configuration

The service is a plain HTTP MCP endpoint: URL + bearer token. There is no local process, no stdio bridge, and no session to keep alive.

Claude (remote/custom MCP connector):

{
  "mcpServers": {
    "egordian-aeo": {
      "type": "http",
      "url": "https://YOUR-HOST/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Perplexity (remote MCP connector): add a custom connector with Server URL = https://YOUR-HOST/mcp and header Authorization: Bearer YOUR_TOKEN.

Any other 2026-07-28 client: point it at https://YOUR-HOST/mcp with the bearer header. The client must send MCP-Protocol-Version: 2026-07-28, Mcp-Method, and — for tools/call / resources/read — a matching Mcp-Name.

Raw call:

curl -sS https://YOUR-HOST/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: server/discover" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"server/discover",
       "params":{"_meta":{"clientInfo":{"name":"curl","version":"8"}}}}'

Legacy stateless 2025 clients are refused unless ALLOW_LEGACY_2025_CLIENTS=true; even then they run on an isolated path that still creates no session and still rejects initialize.

First calls

1. tools/call handle_create {"project_ids":["P-1"]} → opaque, user- and project-bound, expiring handle.

2. Pass handle + project_id on every subsequent tool call.

3. Any side-effecting tool additionally needs actor, approval {approved, actor, rationale, approved_at}, and idempotency_key.

4. Deployment notes

Perplexity private deploy (preview)

Two pieces:

1. Backend — run the service in the sandbox on port 8080, bound to 0.0.0.0: uvicorn app.main:app --host 0.0.0.0 --port 8080. Set AUTH_MODE=bearer and SERVICE_TOKENS. The SQLite overlay (data.db) plus the bundled read-only catalogue are sufficient. Treat this as preview: the container filesystem is not durable.

2. Static console bundle — python scripts/build_static_console.py writes dist/public/ (index.html, docs.html, assets/, robots.txt). Deploy that directory. Every backend call in the bundle is built from the __PORT_8080__ placeholder, which the deploy proxy rewrites to port/8080, so the console reaches the sandbox backend through the same authenticated proxy as the static assets.

The bundle is read-only (GET-only, endpoint allowlist), uses no cookies or web storage, uses only relative links so it works from any /computer/a/<id>/ iframe path, and ships no service data, credentials, or catalogue content. scripts/preview_proxy.py emulates the deploy proxy locally for QA; it is not part of the bundle.

MCP clients still talk to the backend URL (https://…/mcp), not to the static bundle.

Vercel — limitations

Vercel's serverless functions are ephemeral and read-only apart from /tmp, cap the deployment bundle well below the 115 MiB catalogue, and recycle instances between requests. That is incompatible with the bundled immutable catalogue and with a SQLite overlay. If you must use Vercel: set DATABASE_URL to an external PostgreSQL instance and host the catalogue-backed tools elsewhere, or accept catalogue tools reporting unavailable. Vercel is not a supported target for the full service.

Registry-safe variant (no SSH upload) — Dockerfile.registry

When the catalogue cannot be uploaded to the host over SSH and the image must travel through a container registry, use the registry variant: no layer ever contains the plaintext catalogue. The catalogue is sealed with AES-256-GCM before the build; the plaintext exists only inside a private volume at run time, and only when CATALOGUE_DECRYPTION_KEY and the pinned CATALOGUE_SHA256 are both supplied.

 export CATALOGUE_DECRYPTION_KEY='<long passphrase>'   # leading space: no shell history
./scripts/seal_catalogue.sh          # -> build/catalogue.enc + <=60 MiB parts + manifest

# A) registry path
DOCKER_BUILDKIT=1 docker build -f Dockerfile.registry -t "$EGORDIAN_IMAGE" .
docker push "$EGORDIAN_IMAGE"
docker compose -f docker-compose.hostinger.yml --env-file ./egordian.env up -d

# B) public-source path - no registry credentials
./scripts/prepare_public_build_repo.sh /tmp/egordian-aeo-runtime   # stages + leak-scans
docker compose -f docker-compose.hostinger-build.yml --env-file ./egordian.env up -d --build

The sealed container is above GitHub's 100 MiB single-file limit, so the public repo carries deterministic ciphertext parts plus a hash manifest; a throwaway builder stage verifies and reassembles them inside the image.

Full procedure, container format, fail-closed behaviour and the OpenSSL fallback (with its limitations) are in docs/REGISTRY_DEPLOY.md.

Recommended durable deployment — Hostinger VPS + Supabase

1. Compute: Hostinger VPS (or any container host) running the image above with a persistent volume for /app/data.

2. Control plane: Supabase PostgreSQL. Set DATABASE_URL=postgresql://... and the service switches to PostgresRepository automatically; migrations run at start-up. No local filesystem is then required for state.

3. Catalogue: ship the licensed SQLite catalogue inside the image (private registry) or mount it read-only. It is never served, never listed, never downloadable.

4. TLS + secrets: terminate TLS at the reverse proxy; inject SERVICE_TOKENS and any eGordian credentials from the platform's secret store.

5. Scaling: run N replicas behind a plain round-robin load balancer. No session affinity is needed or supported.

5. Configuration

See env.example for the full list (names only, never values). Key variables:

No eGordian credentials are currently available for jocservice.egordian.com. With EGORDIAN_AUTH_PROVIDER=none the service runs normally: status shows disconnected and eGordian tools return an actionable credential_required error instead of crashing.

6. Scopes

catalogue:read, egordian:read, egordian:write, aeo:run, aeo:approve, admin (admin implies all). Writes require both the scope and the approval envelope.

7. Deliberate refusals

8. AEO pipeline

Code owns every transition. Stages 2–4 may propose candidates but can never invent a catalogue line, a quantity, or a price. Every run emits a manifest with version hashes, evidence spans, exceptions and the gate decision — no manifest, no deliverable.

9. Project layout

app/
  main.py               FastAPI app: /mcp, REST, console, OpenAPI
  config.py             environment-only settings
  security.py           auth, RBAC, approval envelopes, rate limits, redaction
  catalogue_gateway.py  licensing firewall over the sealed catalogue
  mcp/                  protocol.py · dispatcher.py · tools.py · resources.py
  egordian/             registry.py · client.py · auth.py
  aeo/                  machine.py · runner.py
  repo/                 base.py · sqlite_repo.py · postgres_repo.py · migrations.py
gordian_ctc/            the existing deterministic engine (imported unchanged)
fixtures/               fetched eGordian Help page snapshot (registry source of truth)
console/                operator console + API documentation page
data/catalogue.sqlite   licensed, immutable, never served
tests/                  144 tests

10. Licensing

Private and contract-bound. The catalogue is supplied for an authorized owner/contract and must never be exported, published, mined, or placed in a model prompt. See vendor_docs/licensing-boundaries.md.