# Horizon MCP Demo -- Extended v2

Companion reference implementation for the Horizon Data Partners white paper
**The Governed Data Layer: Why AI Agents Fail Without One, and How to Build It.**

Two governed systems, one agent:

```
                         +---------------------------+
                         |       Claude agent        |
                         | scripts/run_two_server_   |
                         |        agent.py           |
                         +------+-------------+------+
                                |  MCP (SSE)  |
                 +--------------+             +---------------+
                 v                                            v
  +-----------------------------+            +--------------------------------+
  |  Pipeline Semantic Layer    |            |  Predictive Model Service      |
  |  port 8001                  |            |  port 8002                     |
  |  dbt Core + DuckDB          |            |  DuckDB segment store          |
  |  list_models                |            |  describe_inputs               |
  |  get_model_details          |            |  describe_outputs              |
  |  get_metric_definitions     |            |  validate_payload              |
  |  query_data                 |            |  score_opportunity             |
  |  owns: win_rate, fees,      |            |  owns: segments, matching,     |
  |  margin, velocity           |            |  the 6 outcome estimates       |
  +-----------------------------+            +--------------------------------+
```

## Why v2 exists

The first extension (horizon-mcp-demo-extended) wired a P&C **insurance**
semantic layer into this same predictive model. Every tool call succeeded and
the agent produced numerically precise, analytically meaningless answers --
insurance policies are not professional services opportunities. The failure
was not technical; it was the absence of cross-system governance.

v2 fixes both failures of v1:

1. **Governance first.** `docs/CROSS_SYSTEM_GOVERNANCE.md` was written and
   approved before any code: a domain compatibility check, an approved exact
   field mapping (no assumptions -- and the document explains why that is the
   correct baseline), and a governed interface definition that the model
   server returns from `describe_inputs` and enforces before scoring. The
   server refuses out-of-contract input; it does not adapt it.
2. **SSE transport, not stdio.** Both MCP servers run as independent local
   HTTP processes (ports 8001/8002) and the agent connects with
   `mcp.client.sse.sse_client`. With no stdio subprocesses nested inside the
   agent's event loop, the Windows anyio `BrokenResourceError` from v1 cannot
   occur, and the fix generalizes to any number of servers.

## Repository layout

```
docs/CROSS_SYSTEM_GOVERNANCE.md    governance doc (read this first)
seeds/                             opportunities.csv, jobs.csv, pipeline_summary.csv
models/staging, models/marts       dbt models (the semantic layer)
models/schema.yml                  descriptions + tests served through MCP
model_data/analytical_segments.csv the model's trained segment artifact
model_store/                       built by scripts/build_model_store.py (gitignored)
mcp_server/pipeline_mcp_server.py  System A, port 8001 (SSE)
mcp_server/predictive_model_mcp_server.py  System B, port 8002 (SSE)
scripts/build_model_store.py       loads the segment CSV into DuckDB
scripts/smoke_test_servers.py      exercises all 8 tools, no API key needed
scripts/run_two_server_agent.py    the 5-question agent demo
```

## Quickstart (Windows PowerShell)

From the repository root:

```powershell
# 1. environment
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

# 2. build the semantic layer (profiles.yml is at the repo root; run from here)
dbt seed
dbt run
dbt test

# 3. build the model's segment store
python scripts\build_model_store.py

# 4. start the servers -- one PowerShell terminal each
python mcp_server\pipeline_mcp_server.py           # terminal 1, port 8001
python mcp_server\predictive_model_mcp_server.py   # terminal 2, port 8002

# 5. pre-flight (terminal 3) -- 17 checks, no API key required
python scripts\smoke_test_servers.py

# 6. run the agent demo (terminal 3)
$env:ANTHROPIC_API_KEY = "sk-ant-..."
python scripts\run_two_server_agent.py
```

## The five demo questions

1. What does the pipeline semantic layer contain and what metrics are governed?
2. What are the win rates and average fees by service line and client type in
   the pipeline data?
3. Score a new Advisory/Business/Healthcare/New/Referral opportunity -- what
   are the six outcome estimates and how reliable is the segment match?
   (Deliberately chosen: its finest segment has only 27 observations, under
   the 30 minimum, so outcomes match at levels 1-2 and the response says so.)
4. For open opportunities in the pipeline that have been open longer than the
   model's estimated DaysSellToStart, identify which ones are delayed and by
   how much. (Cross-system: mart_open_pipeline from System A, estimates per
   distinct segment from System B, joined by the agent.)
5. Which service line has the highest fee-to-margin ratio in the historical
   data, and what does the model predict for win probability in that segment
   going forward? (Historical metric and forward estimate side by side, from
   independent definitions.)

## Token logging

Each run writes `logs/agent_run_<timestamp>.json` in the same format as the
original horizon-mcp-demo, extended per server:

- every `tool_calls` entry carries a `server` field;
- `question_totals` and `run_totals` carry `by_server`, holding
  `tool_call_count` and attributed API tokens. Attribution rule: an API call
  whose response invokes tools has its tokens split evenly across the
  distinct servers invoked in that response; synthesis calls (no tools) are
  attributed to `"synthesis"`.

## Data notes

- The pipeline seeds are a static snapshot: `days_open` for open
  opportunities is as of **2026-07-15**, so demo output is reproducible.
- `model_data/analytical_segments.csv` is the model's trained artifact
  (the DuckDB analogue of `dbo.analytical_segments` from
  HorizonDataPredictiveModel), built from a synthetic 1,400-record training
  corpus. Every coarser level is the exact observation-weighted aggregate of
  its children, so the numbers survive scrutiny.
- Dimension drop order when coarsening: LeadSource, NewVsExisting, Industry,
  ClientType, ServiceLine (level 0 finest to level 5 overall) -- the same
  order as `usp_BuildSegments`.

## Troubleshooting

- **Port already in use** -- something else holds 8001/8002. Find it with
  `netstat -ano | findstr :8001`, stop it, or change the PORT constant at the
  top of the affected server file (and the URL in both scripts).
- **Windows Firewall prompt on first server start** -- uvicorn binding
  127.0.0.1 can trigger a Defender prompt. Allow access; the servers bind
  loopback only.
- **DuckDB lock errors from dbt** -- stop the pipeline server before
  re-running `dbt seed`/`dbt run`; the server holds a read-only connection
  but dbt needs the writer.
- **`manifest.json not found` / `Model store not found`** -- run steps 2 and
  3 of the quickstart before starting the servers.
- **Agent cannot connect** -- both servers must be running first; the agent
  does not spawn them (that is the point of the SSE architecture).

## Relationship to the other repositories

- `horizon-mcp-demo` -- the original single-server insurance demo. Untouched
  by this project.
- `HorizonDataPredictiveModel` -- the SQL Server implementation this model
  service ports. The DuckDB segment-matching SQL mirrors `usp_ApplyModel`'s
  CROSS APPLY pattern: per-outcome, OR-IS-NULL per dimension, finest
  qualifying level, minimum 30 observations.