74 lines
2.8 KiB
Markdown
74 lines
2.8 KiB
Markdown
# ARR MCP ingestion gateway
|
|
|
|
This is a standalone Streamable HTTP MCP server with exactly one tool:
|
|
`arr_submit_processing_result`.
|
|
|
|
It is retained solely for the frozen v3 direct-MCP compatibility contract. It accepts only a completed successful v3
|
|
structured result; `PRICE_UNMATCHED` review and manual price finalization exist only in the ARR2 XML upload path.
|
|
|
|
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.
|