Examples
The Metatate examples repository is the public, runnable cookbook for Metatate Cloud. Every notebook works against the Customer 360 sample — the same governed estate the in-app sample workspace loads — so what you learn in a notebook matches what you see in the product: 12 catalog tables across two databases, 20 policies, and one live publication. Eleven tables are governed; legacy_customer_backup is the deliberate ungoverned corner.
Offline and live modesDirect link to Offline and live modes
Every notebook runs in two modes:
- Offline (default): replays native Metatate Cloud answers recorded from the live SaaS MCP endpoint. The committed JSON has the same typed response envelope a new Cloud user receives—never the legacy Snowflake fixture shape. No account needed — clone and run.
- Live: the same pack against your own workspace's MCP endpoint, authenticated with a workspace access token. See Connect to MCP for endpoints and tokens.
export METATATE_EXAMPLES_MODE=live
export METATATE_MCP_URL=https://<your-workspace-mcp-endpoint>/mcp
export METATATE_SAAS_MCP_TOKEN=mtt_...
The full live-mode walkthrough is in the repo's docs/live-mode-saas.md.
The notebooksDirect link to The notebooks
Seventeen notebooks, from first contact to full estate patterns:
| Notebook | What it shows |
|---|---|
00_setup_live_or_offline | Environment check and context discovery. |
01_decision_layer_cookbook | The core Metatate flow: discover, inspect, authorize, validate, explain. |
02_governed_sql_agent_langgraph | A small governed SQL-agent pattern with optional LangGraph. |
03_transfer_governance_before_export | Destination-aware transfer decisions before export. |
04_governed_text_to_sql_agent | Text-to-SQL that validates and revises SQL before returning it. |
05_agent_red_team_evaluation_harness | Repeatable risky-prompt checks for governed agents. |
06_ci_gate_for_data_ai_changes | A runnable CI/CD policy gate for SQL, export, and AI workflow changes. |
07_governed_rag_embedding_ingestion_gate | Pre-ingestion checks before data enters RAG or embedding workflows. |
08_openai_agents_tool_guard_pattern | A deterministic tool guard pattern for OpenAI Agents SDK-style apps. |
09_human_approval_packet_for_conditional_export | A human-in-the-loop exception workflow for safe, conditional, and denied requests. |
10_llamaindex_governed_retrieval_pattern | A governed retrieval function that can be wrapped as a LlamaIndex tool. |
11_langgraph_governed_sql_agent_runtime | A LangGraph runtime SQL agent with approve, revise, and block routes. |
12_governance_states_and_the_wider_estate | Honest states (ungoverned, review-required), role gating, the AI lifecycle, collection targeting, and taxonomy-targeted masking. |
13_sql_gauntlet_validate_query_context | JOINs, SELECT *, intent-sensitive SQL, and honest ungoverned-reference findings. |
14_governed_agent_end_to_end | The full governed-agent arc: inspect, authorize, revise, request controls, reroute, and explain. |
15_audit_evidence_packet | A day of durable decision receipts rendered as an audit-ready evidence packet. |
16_purpose_bound_agent_data_windows | Database × purpose × rolling/as-of anchor × 90/30-day lookback, including SQL proof and fail-closed controls. |
Notebooks are generated from scripts/build_notebooks.py and drift-gated in CI — edits go into the generator, and CI fails if a notebook drifts from it.
Beyond the notebooks, the repo's docs include three live walkthroughs: the publish flip (author, approve, then watch the answer change only at publish), the Claude Code hero demo, and the governance-lead coverage review that finds and fixes the deliberately ungoverned corner.
Repository mapDirect link to Repository map
| Path | What it holds |
|---|---|
notebooks/ | The generated notebook pack above. |
sample-data/customer-360/ | The machine-readable estate spec: catalog, real policy YAML, expected decisions, synthetic tables, and recorded offline response fixtures. |
common/ | Shared Python client helpers, including metatate_client.py. |
cicd_policy_gate/ | A reusable CI/CD policy gate package behind notebook 06. |
human_exception_workflow/ | A reusable human review and exception workflow package behind notebook 09. |
The policy files in sample-data/customer-360/policies/ are real Metatate Cloud policy documents — the Policy YAML reference quotes one as its worked example.
Run it in five minutesDirect link to Run it in five minutes
Offline needs nothing but Python. To feel the decision layer live against your own workspace:
- Create a free account at app.getmetatate.com/sign-up and create a workspace.
- On the dashboard, follow the "New here?" banner to Load the demo, then choose Load the full estate — the notebooks expect the complete governed domain, not the smaller starter sample.
- Open MCP Tools → Tokens and issue an access token (shown once). Copy your endpoint from MCP Tools → Connect.
- Clone the repo, install, and point it at your workspace:
git clone https://github.com/metatateai/metatate-examples.git
cd metatate-examples
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export METATATE_EXAMPLES_MODE=live
export METATATE_MCP_URL=https://<your-workspace-mcp-endpoint>/mcp
export METATATE_SAAS_MCP_TOKEN=mtt_...
jupyter notebook notebooks
Every answer you get back is a typed, cited decision from your workspace's current deployment publication — see the governance model for what that means.