# ARR MCP ingestion gateway

This is a standalone Streamable HTTP MCP server with exactly one tool:
`arr_submit_processing_result`.

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:

```bash
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](https://github.com/modelcontextprotocol/python-sdk) and
[low-level server guidance](https://py.sdk.modelcontextprotocol.io/v2/advanced/low-level-server/).

Local launch with Keychain-backed secrets:

```bash
.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:

```bash
--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.