materials-semantic-mcp

An MCP server that gives agents meaning, not access: governed metric definitions over a materials test lab, plus agent memory that can't enter the system without a provenance label.

Built by a materials & clinical engineering manager who spent years running V&V documentation, now applying the same discipline to agent systems. The dataset is synthetic; the governance problems are real.

The thesis

Give an agent your database and it will rediscover — differently each run — what "first-pass yield" means, which joins are valid, and which numbers are comparable. Give it a semantic layer and those meanings are defined once, versioned, owned, and enforced. Agents don't need access to your data. They need access to your definitions.

The same argument applies to what agents learn. Unlabeled model-generated memory that becomes instruction is an uncontrolled document entering your quality system. Here, every memory carries a provenance label — a disposition record — and the write rules are enforced, not suggested.

Related MCP server: Orenyl

Architecture

semantic/metrics.yaml     ← definitions: formula, unit, grain, dimensions,
   │                        access rules, owner, lineage (SINGLE SOURCE OF TRUTH)
   ▼
src/semantic_layer.py     ← interprets definitions; computes metrics;
   │                        rejects ungoverned dimensions; masks gated identities
   ▼
src/server.py (MCP)       ← thin wiring: 7 tools, role injected by deployment
   ▲
src/memory.py             ← provenance-labeled write-back (se10)

Tool surface

Provenance as disposition (the V&V translation)

Rules enforced at write time: agents may write observed/inferred only; promotion requires a human; unlabeled writes are rejected; confirmed memories never age out silently — humans deprecate them with a reason.

Quickstart

pip install -r requirements.txt
python src/generate_dataset.py --db data/lab.db        # synthetic, seeded
python -m pytest tests/ -q                              # 25 tests
MCP_ROLE=engineering python src/server.py --db data/lab.db

Claude Desktop / Claude Code config:

{
  "mcpServers": {
    "materials-semantic-layer": {
      "command": "python",
      "args": ["src/server.py", "--db", "data/lab.db"],
      "cwd": "/path/to/materials-semantic-mcp",
      "env": { "MCP_ROLE": "public" }
    }
  }
}

The role lives in the deployment environment, not the conversation — an agent cannot talk its way into engineering.

What the tests pin down

Metric math equals hand-written ground-truth SQL; populations honor their where clauses (ESC-only, cracked-only); ungoverned dimensions and unknown metrics reject; supplier identity masks for public and unmasks for engineering; filter values are parameterized (injection-shaped input returns zero rows, not a breach); provenance write rules, promotion gates, supersede chains, and the stale sweep are all deterministic and covered.

Data

Fully synthetic, generated by a seeded script shaped like a polymer test lab: ESC (environmental stress cracking), wet-patch chemical exposure, and tensile runs over resin batches from fictional suppliers — including one problem supplier and one with sloppy paperwork, so governance questions have answers worth finding. No real supplier, material, or employer data.

Roadmap

• Wire into the Materials RAG agent + 10-case routing eval (retrieve vs predict vs query-metric)

• Model-swap eval experiment: same tools, same gold sets, second lab's model — publish the delta

• Blog: The Semantic Layer for Agents — definitions, not data