The protocol process is intentionally thin. It authenticates the HTTP request, advertises the frozen four-field tool Schema, bounds concurrent processor replays, and calls DirectSubmissionService. It does not contain SQL or trust Agent-provided Finance facts.

Runtime

The official MCP Python SDK 2.0 requires Python 3.10+. Keep it separate from the portal's historical Python 3.9 virtual environment:

python3.12 -m venv .venv-mcp
.venv-mcp/bin/python -m pip install -r requirements-arr-mcp.txt

The server uses the recommended stateless Streamable HTTP transport with JSON responses, a 4 MiB HTTP-body limit, DNS-rebinding Host allowlisting, and a required bearer token. See the official Python SDK and low-level server guidance.

Local launch with Keychain-backed secrets:

.venv-mcp/bin/python -m arr_mcp.launch \
  --db-config /path/to/private/booking-test-db.env \
  --host 127.0.0.1 \
  --port 8890

The launcher reads only OSS routing values from the owned 0600 route file. It loads OSS credentials and ARR_MCP_BEARER_TOKEN from macOS Keychain account arr-web; no secret belongs in this repository, command line, Main Prompt, or Agent output.

When binding beyond loopback, pass every accepted reverse-proxy Host header:

--host 0.0.0.0 --allowed-host mcp.example.com

Do not expose plain HTTP publicly. Terminate HTTPS at a controlled reverse proxy or tunnel and forward only the MCP endpoint.

SuperAgent MCP entry

Service identifier: arr_ingestion_gateway
Display name: ARR Ingestion Gateway
Transport: HTTP
Service address: https://<controlled-host>/mcp
Status: activate only after the no-PII acceptance test passes
Headers: Authorization: Bearer <ARR_MCP_BEARER_TOKEN> supplied through the platform's secret facility
OAuth JSON: {} unless the deployment later adopts a dedicated OAuth server

The bearer protects the transport. The short-lived submission_grant inside the tool call separately binds the write to one registered job attempt. Both must be valid.

Success and error behavior

Success returns only the strict receipt: committed or already_committed, job/attempt, business date, daily version identity and record count. A business or validation error is an MCP tool error containing only a stable code, safe message and retryable flag. Request payloads and grants are never logged.