# foundation-mcp-demo

An MCP server that lets an AI agent turn a messy CRM account list into a ranked list of accounts to work, with every step authorized, scoped, rate limited, and replayable from an audit log.

**This is a demo I built, not production infrastructure.** It runs on a laptop, serves no real traffic, and has not been load tested or security reviewed by anyone else.

## What's real and what isn't

| Data | Source | Tag in every result |
|---|---|---|
| Legal entities, LEIs, parent relationships | [GLEIF API](https://www.gleif.org/en/lei-data/gleif-api) | `real:gleif` |
| Public company filings, 8-K item codes | [SEC EDGAR](https://www.sec.gov/search-filings/edgar-application-programming-interfaces) | `real:sec-edgar` |
| Intent scores, buying stage, contacts | Generated locally | `synthetic:6sense-shape` |

The synthetic fields use names copied from 6sense's public API reference (`api.6sense.com/docs`), such as `company_buying_stage` and `contact_grade`. The values are made up. **All people in this repo are synthetic, including their names.** Nothing here comes from 6sense or claims to describe how their platform works.

Why a stand-in: 6sense's MCP server (`api.6sense.com/mcp`) requires a customer login, so I couldn't build against it. See [DECISIONS.md](DECISIONS.md) D1.

## Status

- [x] Authorization server and MCP resource server, OAuth 2.1 end to end (`scripts/oauth_smoke.py`)
- [ ] Data adapters with response snapshots
- [ ] Hash-chained audit log and offline replay
- [ ] The seven tools, matching, ranking
- [ ] Proposals and approval
- [ ] Rate limits and run budgets
- [ ] Recorded agent runs
- [ ] Docker Compose

## Run it locally

Requires Python 3.12.

```bash
python -m venv .venv
.venv/Scripts/pip install -e ".[dev]"        # macOS/Linux: .venv/bin/pip
cp .env.example .env                          # then fill in the passwords and secret
python -m foundation_demo.auth                # authorization server on :9000
python -m foundation_demo.mcp_server          # MCP server on :8001
python scripts/oauth_smoke.py                 # walks the OAuth flow and checks the refusals
```

## Design

Every non-obvious choice, the alternatives, and the strongest argument against each pick: [DECISIONS.md](DECISIONS.md).