Governed Model Context Protocol (MCP) servers in both Java and Python, exposing enterprise tools (ledger, pricing, search) to an LLM agent behind a governance layer: read/write sensitivity classification, human-in-the-loop approval for write actions, role-based policy, and a hash-chained audit log. The connective tissue that lets agents act on systems of record safely.
Part of the Enterprise Platform Reference Architecture. Models the platform
engineering / agentic enablement domain. See docs/INDUSTRY-APPLICABILITY.md.
Enterprises are polyglot. The same governance model is implemented identically in
python-mcp-server (JSON-RPC over stdio) and
java-mcp-server (JSON-RPC over HTTP), proving the pattern is transport- and
language-agnostic.
flowchart LR
agent["LLM agent / client"] -->|"MCP tools/call"| server["Governed MCP server (Java or Python)"]
server --> policy["PolicyEngine: read=allow, write=approval, unknown=deny"]
policy -->|"write"| human["Human approver (HITL)"]
human -->|"approvalToken"| server
server --> tools["Tools -> ledger / pricing / search backends"]
server --> audit["Hash-chained audit log"]
| Tool class | Example | Policy |
|---|---|---|
| READ | get_account_balance, search_docs, lookup_supplier, lookup_location, lookup_item_cost |
Allowed for any known role |
| WRITE | post_payment, propose_price_change |
Requires human approval (unless trusted role) |
| Unknown role | — | Denied |
Every call -- allowed, denied, or pending approval -- is appended to a hash-chained audit log;
verify() detects any tampering with history. Tool arguments are redacted (RETAIL + PCI + HIPAA
rule sets) before hashing — see AUDIT-REDACTION.md.
cd python-mcp-server
python -m venv .venv && source .venv/bin/activate && pip install pytest
pytest -q
python -m agent_mcp.server # speak JSON-RPC on stdin/stdoutcd java-mcp-server
mvn spring-boot:run # POST JSON-RPC to http://localhost:8086/mcp ; GET /audit
mvn testdocker compose up --buildThree READ tools wire the gateway to the retail pillar repos (mocked offline, HTTP in production):
| MCP tool | Retail repo | API shape |
|---|---|---|
lookup_supplier |
supplier-golden-record-platform | GET /api/suppliers/legacy/{id} |
lookup_location |
location-reference-cache | GET /api/locations/{nbr} |
lookup_item_cost |
item-cost-ledger-platform | GET /api/costs/clubs/{club}/items/{item} |
cd python-mcp-server && PYTHONPATH=src python -m agent_mcp.merchandising_demoSee docs/RETAIL-MERCHANDISING-MCP.md.
- System design
- Industry applicability
- Business & governance: BRD - SOP - NFR - Cost savings
- ADRs:
docs/adr/
Python 3.11+ (stdlib-only server core), Java 21 + Spring Boot 3.3, MCP JSON-RPC 2.0.