Sentinel Data Governance Agent

Sentinel is a autonomous data governance agent that audits a PostgreSQL database through the Model Context Protocol (MCP). Instead of giving the LLM direct database access, the project exposes a controlled FastMCP bridge with purpose-built tools for schema inspection, null profiling, and anomaly detection.

The demo seeds an intentionally dirty raw_inventory table, asks an OpenAI-powered agent to inspect it through MCP tools, and writes a Markdown audit report to LATEST_AUDIT.md.

What It Demonstrates

• A Python MCP client that follows a ReAct-style Reason -> Act -> Observe workflow.
• A FastMCP server that acts as a governance bridge between the agent and PostgreSQL.
• SQLAlchemy-backed tools for safe, structured database inspection.
• Data quality checks for missing emails, negative inventory counts, and duplicate SKUs.
• A generated Data Health Audit with remediation SQL.

Architecture

flowchart LR
    U[User question] --> A[Python Agent<br/>MCP Client]
    A -->|tools/list and tools/call| M[FastMCP Server<br/>Sentinel-Bridge]
    M -->|SQLAlchemy queries| DB[(PostgreSQL 16<br/>raw_inventory)]
    DB -->|schema and quality metrics| M
    M -->|structured MCP tool results| A
    A -->|OpenAI analysis or local fallback| R[LATEST_AUDIT.md]

MCP Tools

inspect_schema() returns table names and column definitions for structural audits.

get_data_health_sample() returns 100 recent rows from raw_inventory for row-level review.

check_null_ratios(table_name="raw_inventory") returns null counts and percentages for every column.

find_logical_anomalies() returns rows with negative stock_count values and duplicated sku groups.

Project Layout

agent.py              # MCP client and ReAct audit workflow
server.py             # FastMCP server exposing database audit tools
seed_data.py          # Faker-based dirty data generator
docker-compose.yml    # PostgreSQL 16 local database
architecture.md       # Mermaid architecture diagram
.env.example          # Safe environment variable template

Setup

Requirements:

• Windows 11, macOS, or Linux
• Docker Desktop
• Python managed with uv
• An OpenAI API key with available API quota

Create your local environment file:

Copy-Item .env.example .env

Edit .env and replace placeholder values. Do not commit .env.

Install dependencies:

uv sync

Start PostgreSQL:

docker compose up -d

Seed the dirty inventory table:

uv run python seed_data.py

Run the MCP server directly:

uv run python server.py

In another terminal, run the autonomous audit agent:

uv run python agent.py

The agent writes its report to:

LATEST_AUDIT.md

Verify the Seeded Data

docker exec -it sentinel_postgres psql -U sentinel_user -d sentinel_db -c "SELECT COUNT(*) AS negative_stock_rows FROM raw_inventory WHERE stock_count < 0;"

Expected result after seeding:

30

Security Notes

• .env is ignored by Git and must never be committed.
• .env.example contains placeholders only.
• The LLM does not receive raw database credentials directly; it interacts with approved MCP tools.
• The MCP server is the policy boundary where database capabilities are explicitly exposed.
• Rotate any API key that has appeared in logs, screenshots, terminal output, or chat.

Why MCP Instead of Direct SQLAlchemy in the Agent?

MCP gives the LLM a constrained tool interface rather than unrestricted database access. The FastMCP server defines the allowed actions, making the governance boundary explicit and auditable. The same agent can later interoperate with catalogs, policy engines, warehouses, and observability systems through MCP without rewriting the agent around direct database connections.