# horizon-mcp-demo-extended

Extends the [horizon-mcp-demo](https://github.com/christianashworth/horizon-mcp-demo) by connecting it to the Horizon Data Predictive Model — a professional services pipeline model — via a single Claude agent. Built as research material for the Horizon Data Partners white paper: *The Governed Data Layer: Why AI Agents Fail Without One, and How to Build It.*

---

## What this actually demonstrates

This demo was built to explore the Claudeception pattern — a single agent connecting to two governed systems and reasoning across them. In practice, it produced something more instructive than a clean success: **a concrete example of what happens when cross-system governance is absent.**

The two systems in this demo have completely incompatible analytical schemas:

- **Insurance data** — P&C insurance policies with product types (auto/homeowners) and states (TX/CA/FL/NY)
- **Predictive model** — professional services pipeline model expecting ServiceLine (Audit/Tax/Advisory), ClientType (Business/Individual), Industry, NewVsExisting, and LeadSource

These categories do not correspond to anything real across the two systems. P&C insurance policies are not professional services opportunities. Yet the agent — when asked to map insurance segments to model inputs — did so confidently. It reasoned about the mapping, cited governance risks, validated its payload, and returned a WinPct estimate that was internally consistent and analytically meaningless.

**This is the paper's argument made concrete:** a governed semantic layer protects an agent within a system. It cannot protect against an agent being pointed at two systems that have no valid analytical relationship. The agent followed its governance rules correctly. It produced nonsense anyway — because cross-system governance was never done.

Three things were missing that cross-system governance would have required:
1. **Domain compatibility check** — do the analytical categories in System A correspond to anything meaningful in System B?
2. **Approved mapping** — who has authority to approve the field-level mapping, under what conditions, and what triggers a review?
3. **Governed interface definition** — what kinds of upstream data sources are valid inputs semantically, not just technically?


---

## Technical notes

| System | Transport | What it exposes |
|--------|-----------|----------------|
| Insurance Data (from `horizon-mcp-demo`) | MCP via stdio | P&C insurance semantic layer — loss ratio, claim frequency, earned premium by segment |
| Predictive Model (this repo) | Direct Python calls | Professional services pipeline model — win probability, fees, margin, milestone timing |

The predictive model tools run as direct Python function calls rather than via a second MCP server. This resolves a Windows asyncio/anyio compatibility issue with nested stdio clients. On Linux/macOS, the full two-MCP-server pattern works correctly.

The predictive model's trained segment estimates are loaded from a DuckDB file into memory at startup, generated by `data/seed_predictive_model.py` from synthetic training data using the same parameters as the original SQL Server model.

---

## Project structure

```
horizon-mcp-demo-extended/
├── data/
│   └── seed_predictive_model.py    # Generates predictive_model.duckdb
├── mcp_server/
│   └── predictive_model_mcp_server.py  # MCP server definition (Linux/macOS)
├── scripts/
│   └── run_two_server_agent.py     # Agent demo — insurance MCP + model Python calls
├── requirements.txt
├── .gitignore
└── README.md
```

---

## Prerequisites

- Python 3.12
- `horizon-mcp-demo` cloned at the **same directory level** as this repo
- `horizon-mcp-demo` fully built (`dbt seed && dbt run` completed)

---

## Setup (Windows)

### 1. Clone this repo

```powershell
git clone https://github.com/christianashworth/horizon-mcp-demo-extended.git
cd horizon-mcp-demo-extended
```

### 2. Create and activate virtual environment

```powershell
py -3.12 -m venv .venv
.venv\Scripts\activate
```

### 3. Install dependencies

```powershell
python -m pip install --upgrade pip
pip install -r requirements.txt
```

### 4. Generate the predictive model database

```powershell
python data/seed_predictive_model.py
```

### 5. Run the demo

```powershell
$env:ANTHROPIC_API_KEY = "your-api-key-here"
python scripts/run_two_server_agent.py
```

---

## Demo questions

| # | Question | Purpose |
|---|----------|---------|
| 1 | What inputs does the predictive model require? | Establish model requirements |
| 2 | What are the loss ratios by segment in the insurance data? | Governed single-system query |
| 3 | Map insurance segments to model inputs and score | Surfaces the schema mismatch and governance failure |
| 4 | Score all homeowners state segments and combine with loss ratios | Cross-system join — analytically meaningless given the incompatible schemas |
| 5 | What governance decisions would be needed before using this mapping in production? | Agent correctly identifies what should have been done first |

Question 5 is the most instructive: the agent accurately describes the governance framework that was absent throughout the rest of the demo.

---

## Notes

- `data/predictive_model.duckdb` is excluded from version control — generated locally by the seed script.
- Token usage is logged per question in `logs/two_server_run_<timestamp>.json`.
- The full technical documentation is in `horizon-mcp-demo-extended-technical-documentation.docx`.