An open, machine-readable standard for AI safety & governance documentation
A unified standard for AI safety & governance documentation โ making safety and compliance claims checkable.
โBridging machine-readable governance documentation with zero-trust runtime policy enforcement.โ
Industry-agnostic by design. The four cards describe any AI system in any industry. Cross-sector frameworks (NIST AI RMF, EU AI Act) are mapped today; sector rules such as HIPAA, FDA SaMD and banking model-risk guidance are designed to plug in as optional profiles, so one card serves every regime without forking the standard.
Most AI safety controls exist only on paper. Oversight rules, escalation procedures and shutdown plans are written down, but nothing ensures they bind an AI agent once it is running. When an agent acting through MCP does something harmful, can you prove which version acted, what it was allowed to do at that moment, and what the tool actually executed? When you pull the kill switch, does the agent actually stop?
MCML closes that gap in two steps:
| ย | What it does | Status |
|---|---|---|
| 1. Pre-deployment gate | Blocks deployment when safety evidence is missing: failure modes, evaluations that missed their thresholds, no human oversight, no tested kill switch, or a configuration that would let the agent bypass enforcement | โ Available |
| 2. Runtime enforcement gateway | Enforces the signed Agentic Governance Card on every MCP tool call, from outside the agentโs runtime, so enforcement does not depend on the agentโs cooperation | ๐งช Prototype: 7 of 7 scenarios pass in a synthetic environment (results) |
The runtime gateway is designed to:
The prototype passes seven scenarios, including gateway bypass, model provenance injection and adversarial payload injection, in a synthetic clinical workflow, and the tests run on every commit. It has not been tested in production. We publish its limits too: it enforces declared limits, so an action the card permits can still cause harm.
MCML is a standard language that formalizes and unifies AI documentation practices into a machine-readable protocol for regulatory compliance. It defines four card types (Model, Dataset, Interface, and Agentic Governance), each with JSON Schema definitions, and the structure needed to validate them automatically.
Documentation that says a model has limitations, requires human review, or is monitored is not enough on its own. MCML requires these claims to be specified in a form tools can check: failure modes with severity and mitigation, evaluation evidence with thresholds, oversight authority, monitoring commitments with actions on breach, recorded risk acceptance, and links to incidents.
MCML is part of the ModelConnect platform, an open-source integration layer for enterprise AI infrastructure.
MCML integrates four documentation standards from the AI governance community:
These four card types are becoming the de facto industry standards for AI documentation. MCML provides the integration layer that makes them work together.
Organizations must comply with multiple regulatory frameworks and ISO standards:
The Problem: Each framework has different documentation requirements, and the four card types exist independently without a unified structure or machine-readable format.
MCML formalizes the structure of all four card types with:
MCML provides JSON/YAML schemas enabling:
MCML maps card fields to regulatory requirements:
| Framework | MCML Mapping |
|---|---|
| NIST AI RMF | Shows which card fields satisfy GOVERN/MAP/MEASURE/MANAGE functions |
| EU AI Act | Maps cards to risk classification, transparency, human oversight requirements |
| ISO/IEC 42001 | Links cards to AI management system documentation clauses |
| GDPR | Demonstrates data provenance, purpose limitation, accountability |
| FDA | Provides device traceability and adverse event reporting structure |
Example: โTo satisfy NISTโs MEASURE function, you need performance_metrics from Model Card + quality_metrics from Dataset Card + fairness_metrics from both.โ
Manual, Fragmented Compliance:
1. Read Model Card PDF
2. Search wiki for Dataset documentation
3. Check spreadsheet for API governance
4. Manually verify bias assessment exists
5. Write audit report by hand
6. Hope documentation matches production reality
โฑ๏ธ Time: Hours to days per audit
โ No automation
โ Documentation drifts from deployments
โ Can't validate before deployment
Automated, Unified Compliance:
// Single API call returns complete governance lineage
GET /governance/lineage/event_12345
{
"model": {
"name": "credit_scorer",
"version": "3.2.1",
"governance": {
"intended_use": "Credit risk assessment for personal loans",
"performance_metrics": {"auc": 0.87, "f1": 0.82},
"limitations": ["Not validated for commercial loans"]
}
},
"dataset": {
"name": "customer_credit_data",
"version": "2.3",
"governance": {
"known_biases": ["geographic_urban", "age_skew_25_45"],
"quality_score": 0.91,
"contains_pii": true
}
},
"interface": {
"governance": {
"access_control": "oauth2",
"logging_level": "detailed"
}
},
"agent": {
"governance": {
"autonomy_level": "semi_autonomous",
"escalation_rules": {...}
}
},
"compliance": {
"nist_rmf": {
"status": "COMPLIANT",
"functions": {
"GOVERN": "โ", "MAP": "โ", "MEASURE": "โ", "MANAGE": "โ"
}
},
"eu_ai_act": {
"risk_category": "HIGH",
"status": "COMPLIANT"
}
}
}
โฑ๏ธ Time: Milliseconds โ Fully automated โ Documentation linked to deployments โ Pre-deployment validation
While MCML is implementation-agnostic (you can use any database, file system, or architecture), we describe a reference architecture, our patent-pending two-layer architecture, that demonstrates the power of machine readability. The schemas, example cards and validator in this repository implement the pre-deployment checks; the two-layer database implementation is described here and is not yet published as code.
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ GOVERNANCE LAYER (Documentation) โ
โ โ
โ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโ โ
โ โ Model Cards โ โDataset Cardsโ โInterface Cardsโ โ
โ โโโโโโโโฌโโโโโโโ โโโโโโโโฌโโโโโโโ โโโโโโโโฌโโโโโโโโโ โ
โ โ โ โ โ
โ โโโโโโโโดโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโดโโโ โ
โ โ Agentic Cards โ โ
โ โโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโผโโโโโโโโโโโผโโโโโโโโโโโผโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโ
โ Foreign Key Relationships โ
โโโโโโโโโโโผโโโโโโโโโโโผโโโโโโโโโโโผโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโ
โ โผ โผ โผ โผ โ
โ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ โ
โ โModel Registryโ โ Dataset โ โInterface Registryโ โ
โ โโโโโโโโโโโโโโโโ โ Registry โ โโโโโโโโโโโโโโโโโโโโ โ
โ โโโโโโโโโโโโโ โ
โ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Agent Registry โ โ Inference Events โ โ
โ โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ
โ OPERATIONAL LAYER (Deployments) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Governance Layer (Documentation):
Operational Layer (Deployed Systems):
Foreign Keys create enforceable relationships:
| Capability | How Foreign Keys Enable It | Time Saved |
|---|---|---|
| Pre-deployment validation | FK constraint blocks deployment if card missing | Catches issues before production |
| Single-query audit trails | One SQL JOIN traverses entire governance graph | Hours โ Milliseconds |
| Guaranteed completeness | Database enforces all required cards exist | No manual verification |
| Automatic compliance checks | Query card fields to validate regulatory requirements | Days โ Seconds |
| Drift prevention | Documentation canโt get out of sync with deployments | Eliminates documentation debt |
| Incident investigation | Trace from prediction โ model โ biased training data | Hours โ Minutes |
-- PostgreSQL implementation: Complete lineage in one query
SELECT
ie.event_id,
ie.prediction,
ie.timestamp,
-- Model governance
mc.intended_use,
mc.performance_metrics,
mc.limitations,
-- Dataset governance
dc.known_biases,
dc.collection_method,
dc.quality_score,
-- Interface governance
ic.access_control_policy,
ic.logging_level,
-- Agent governance
ac.identity,
ac.autonomy,
ac.enforcement
FROM inference_events ie
JOIN model_registry mr ON ie.model_fk = mr.id
JOIN model_cards mc ON mr.model_card_fk = mc.id
JOIN dataset_cards dc ON mc.training_dataset_fk = dc.id
JOIN interface_registry ir ON ie.interface_fk = ir.id
JOIN interface_cards ic ON ir.interface_card_fk = ic.id
LEFT JOIN agent_registry ar ON ie.agent_fk = ar.id
LEFT JOIN agentic_governance_cards ac ON ar.agent_card_fk = ac.id
WHERE ie.event_id = '550e8400-e29b-41d4-a716-446655440000';
โฑ๏ธ Query time: <100ms for complete governance lineage across all four card types
The two-layer architecture with foreign keys is our patent-pending reference implementation, but MCML can be implemented in other ways:
The MCML standard is implementation-agnostic. Our reference implementation demonstrates the benefits of machine readability plus relational integrity.
Documents the governance metadata for ML models.
Core Fields:
model_card:
model_name: credit_risk_scorer
version: 3.2.1
# Purpose and scope
intended_use: "Credit risk assessment for personal loans up to $50K"
out_of_scope_uses:
- "Commercial loan assessment"
- "International credit scoring"
# Relationships to other cards
training_dataset_ref: "dataset://customer_credit_data/v2.3"
validation_dataset_ref: "dataset://holdout_data/v1.0"
# Performance documentation
performance_metrics:
primary_metric: auc
auc: 0.87
f1_score: 0.82
precision: 0.85
recall: 0.79
# Fairness and bias
fairness_metrics:
demographic_parity: 0.92
equal_opportunity: 0.94
disparate_impact: 0.88
# Transparency
limitations:
- "Performance degrades for recent immigrants (limited training data)"
- "Not validated for loan amounts above $50K"
- "Requires annual retraining to maintain accuracy"
ethical_considerations:
high_risk_groups:
- recent_immigrants
- first_time_borrowers
mitigation_strategies:
- "Manual review required for confidence < 0.85"
- "Quarterly fairness audits by external auditor"
# Accountability
responsible_team: "ML Engineering - Credit Models"
contact_email: "ml-credit@example.com"
# Compliance mapping
nist_rmf_alignment:
GOVERN: "Responsible team designated, approval workflow documented"
MAP: "Risk categorized as HIGH, context fully documented"
MEASURE: "Performance and fairness metrics tracked continuously"
MANAGE: "Monitoring commitments and risk acceptance recorded"
Safety Extension (v1.1):
model_card:
# ...core fields above
failure_modes:
- id: FM-01
description: "Reduced accuracy for applicants with thin credit files"
severity: high
detection: "Subgroup AUC and population stability index monitoring"
mitigation_ref: MIT-03
residual_risk: medium
evaluation_evidence:
evaluation_date: 2026-01-10
test_dataset_ref: "dataset://holdout_data/v1.0"
metrics:
- metric: auc
threshold: 0.85
observed: 0.87
passed: true
report_uri: "https://example.com/evals/credit_scorer_3.2.1.pdf"
human_oversight:
oversight_model: human_on_the_loop # or human_in_the_loop, human_in_command
reviewer_role: senior_underwriter
override_authority: "Reviewer may overturn any automated decision"
review_triggers:
- "Confidence below 0.85"
- "Applicant requests explanation"
reviewer_training: "Bias-awareness training completed before assignment"
monitoring_commitments:
- metric: population_stability_index
threshold: 0.25
frequency: daily
action_on_breach: "Suspend automated decisions and route to manual review"
owner: "ML Monitoring Team"
risk_acceptance:
risk_category: high
accepted_residual_risk: medium
accepted_by: "Chief Risk Officer"
accepted_on: 2026-02-01
review_due: 2026-08-01
incident_refs: [] # Incident Card planned for v1.2
MCML Extensions for Machine Readability:
training_dataset_ref: URI reference to Dataset Card (enables automated lineage)performance_metrics: structured numbers (enables automated threshold checks)fairness_metrics: quantitative bias measures (enables drift detection)nist_rmf_alignment: direct mapping to compliance frameworkfailure_modes, evaluation_evidence, human_oversight, monitoring_commitments, risk_acceptance: safety fields (v1.1)Documents the governance metadata for training/evaluation datasets.
Core Fields:
dataset_card:
dataset_name: customer_credit_data
version: 2.3
# Provenance
collection_method: "Production credit applications 2023-2024 + synthetic augmentation"
collection_date_start: 2023-01-01
collection_date_end: 2024-12-31
data_owner: "Data Governance Office"
# Bias documentation
known_biases:
- bias_type: geographic
description: "Urban areas over-represented (65% vs 45% national population)"
impact: "May underperform for rural applicants"
mitigation: "Synthetic rural data augmentation + stratified validation"
- bias_type: demographic
description: "Age distribution skewed toward 25-45 (68% vs 52% population)"
impact: "May underperform for applicants <25 or >60"
mitigation: "Age-based fairness constraints in training"
# Quality metrics
quality_metrics:
completeness: 0.94
consistency_score: 0.89
accuracy_sample_validated: 0.97
missing_value_rate: 0.06
# Preprocessing
preprocessing_steps:
- step: "Remove duplicate applications"
description: "Deduplicated on national_id + application_date"
- step: "Impute missing income"
description: "Median imputation by ZIP code + job category"
- step: "Outlier removal"
description: "Remove income >$500K or <$5K (0.3% of data)"
# Legal and compliance
contains_pii: true
pii_fields:
- national_id
- full_name
- address
- date_of_birth
legal_basis: "Customer consent for credit assessment (GDPR Art. 6.1.b)"
retention_policy: "7 years from application date per banking regulations"
# GDPR compliance
gdpr_compliance:
lawful_basis: "Contract necessity"
data_minimization: "Only credit-relevant fields collected"
purpose_limitation: "Used only for credit risk assessment"
subject_rights: "Deletion requests processed within 30 days"
MCML Extensions for Machine Readability:
known_biases: structured list (enables automated fairness validation)quality_metrics: quantitative scores (enables data quality gates)preprocessing_steps: reproducible transformations (enables lineage tracking)pii_fields: explicit PII listing (enables GDPR compliance checks)Documents the governance metadata for API endpoints and services.
Core Fields:
interface_card:
service_name: credit_scoring_api
description: "Production credit scoring endpoint for loan origination system"
# API specification
api_specification_url: "https://api.example.com/docs/credit/v2/openapi.json"
supported_protocols:
- REST
- gRPC
base_url: "https://api.example.com/v2/credit"
# Access control
authentication_method: oauth2
access_control_policy:
authorized_roles:
- loan_officer
- underwriter
- risk_analyst
ip_whitelist:
- "10.0.0.0/8" # Internal network only
rate_limits:
requests_per_minute: 100
requests_per_hour: 5000
burst_allowance: 150
# Data governance
data_classification: confidential
pii_handling_policy: "All requests/responses encrypted in transit and at rest"
# Monitoring and logging
logging_level: detailed
log_retention_days: 365
audit_requirements:
- "Log all access attempts (success and failure)"
- "Log all prediction inputs and outputs"
- "Alert on unusual access patterns"
# Compliance
compliance_frameworks:
- GDPR
- CCPA
- SOC2
- PCI-DSS
data_residency_requirements:
allowed_regions:
- us-east
- eu-west
prohibited_regions:
- china
- russia
# Ownership
service_owner: "Platform Engineering - APIs"
contact_email: "api-team@example.com"
MCML Extensions for Machine Readability:
rate_limits: structured throttling (enables automated enforcement)access_control_policy: machine-readable permissions (enables IAM integration)compliance_frameworks: explicit framework list (enables compliance validation)data_residency_requirements: geographic constraints (enables deployment validation)agentic_card)Documents the governance metadata for AI agents and autonomous components. The v1.0 agentic_card name remains as a deprecated alias for one minor version.
agentic_governance_card:
schema_version: "1.1"
agent_name: loan_approval_agent
agent_version: "1.3.0"
description: "Semi-autonomous agent supporting personal loan decisions"
last_verified: 2026-11-01
# Identity: who the agent is and how it authenticates
identity:
agent_id: "agent://lending/loan-approval/1.3.0"
authentication: "OAuth 2.1 client credentials, workload-attested via SPIFFE ID"
credential_rotation: "Every 24 hours; revocable immediately"
owner: "Risk Management - Lending Operations"
# Autonomy and decision authority
autonomy:
level: semi_autonomous
decision_authority:
max_loan_amount: 25000
max_approval_without_review: 15000
requires_human_approval_above: 25000
# Authorization: scoped, time-limited permissions per tool
authorization:
tools:
- name: credit_bureau_lookup
scopes: ["credit:read"]
max_calls_per_application: 3
permission_ttl: "PT30M"
- name: fraud_check
scopes: ["fraud:read"]
max_calls_per_application: 1
permission_ttl: "PT30M"
standing_access: none
forbidden_actions:
- modify_credit_score
- approve_loan_above_authority
- disable_fraud_check
- access_competitor_data
# Delegation: who acted on whose authority
delegation:
max_hops: 2
requires_origin_user: true
chain_recorded: true
permitted_downstream_agents:
- fraud_detection_agent
prohibited_downstream_agents:
- external_third_party_agents
# Interoperability: protocols and spec versions as ranges
interoperability:
mcp:
supported: true
spec_version_range: "[verify against current MCP specification]"
auth_profile: "OAuth 2.1 resource server"
a2a:
supported: true
spec_version_range: "[verify against current A2A specification]"
agent_card_signed: true
upstream_spec_links:
- "https://modelcontextprotocol.io/specification"
- "https://a2a-protocol.org"
# Runtime enforcement: how rules are applied, not only declared
enforcement:
policy_engine: "[name the policy decision point]"
enforcement_point: "Tool gateway, before each tool call"
violation_behavior: "Block action, log event, escalate"
audit_log:
captures: [identity, origin_user, tool, arguments_hash, decision, timestamp]
retention_days: 365
tamper_evident: true
# Kill switch and rollback
kill_switch:
trigger_conditions:
- "error_rate > 10% over 5 minutes"
- "approval_rate > 95% over 1 hour"
- "tool_call_failure_rate > 20%"
action: "Revoke credentials and route requests to manual review queue"
tested: [test date]
tested_by: "[owning team]"
rollback_procedure_ref: "[runbook location]"
# Oversight: reference the Model Card, do not duplicate it
human_oversight:
model_card_ref: "model://credit_risk_scorer/3.2.1#human_oversight"
escalation_rules:
- condition: "confidence_score < 0.85"
action: escalate_to_senior_underwriter
sla: "4 hours"
- condition: "fraud_score > 0.7"
action: immediate_escalation_to_fraud_team
sla: "1 hour"
# Monitoring: reference the Model Card's commitments
monitoring:
model_card_ref: "model://credit_risk_scorer/3.2.1#monitoring_commitments"
action_logging_level: all
# Threat coverage
threat_coverage:
framework: "OWASP Top 10 for Agentic Applications"
reviewed_categories:
- "Insecure inter-agent communication"
- "Identity and privilege abuse"
- "Tool misuse"
last_reviewed: [review date]
incident_refs: []
MCML Extensions for Machine Readability:
identity and delegation: who acted and on whose authority (enables attribution across agent chains)authorization.tools with permission_ttl: scoped, time-limited permissions (enables least-privilege enforcement)forbidden_actions: blocklist (enables runtime enforcement)escalation_rules: structured conditions (enables automated routing)kill_switch.trigger_conditions: quantitative thresholds (enables automatic shutdown)enforcement: how rules are applied at runtime (enables verification)card_signature, enforcement.gateway_isolation, per-tool argument_schema, structured kill-switch triggers and actions, provenance_verification, adversarial_defenses. See the Runtime Safety specification.MCML provides direct mappings from card fields to regulatory and framework requirements, enabling automated compliance checking. Mappings show where evidence can be found. They do not guarantee compliance.
| NIST Function | Required MCML Fields | Validation Check |
|---|---|---|
| GOVERN | model_card.responsible_teamagentic_governance_card.identity.ownerdataset_card.data_owner |
โ All ownership fields populated |
| MAP | model_card.intended_usemodel_card.limitationsmodel_card.failure_modesagentic_governance_card.autonomy.decision_authority |
โ Purpose, constraints, and failure modes documented |
| MEASURE | model_card.performance_metricsmodel_card.fairness_metricsmodel_card.evaluation_evidencedataset_card.quality_metricsdataset_card.known_biases |
โ Quantitative assessments present |
| MANAGE | interface_card.logging_level = 'detailed'model_card.monitoring_commitmentsmodel_card.risk_acceptanceagentic_governance_card.kill_switch |
โ Monitoring, response, and risk acceptance mechanisms present |
Automated Validation Example:
def validate_nist_compliance(model_card, dataset_card, interface_card, agentic_card):
results = {
"GOVERN": bool(
model_card.responsible_team and
dataset_card.data_owner
),
"MAP": bool(
model_card.intended_use and
model_card.limitations and
model_card.failure_modes
),
"MEASURE": bool(
model_card.performance_metrics and
model_card.fairness_metrics and
model_card.evaluation_evidence and
dataset_card.quality_metrics
),
"MANAGE": (
interface_card.logging_level == "detailed" and
bool(model_card.monitoring_commitments) and
bool(model_card.risk_acceptance) and
bool(agentic_card.kill_switch)
),
}
return {
"compliant": all(results.values()),
"function_status": results,
}
| Article | Requirement | MCML Fields | Validation |
|---|---|---|---|
| Art. 6 | Risk Classification | model_card.risk_acceptance.risk_category |
โ
Must be: minimal, limited, high, unacceptable |
| Art. 11 | Technical Documentation | All four card types complete | โ All required fields present |
| Art. 13 | Transparency | model_card.intended_usemodel_card.limitationsdataset_card.known_biases |
โ Clear purpose and constraints |
| Art. 14 | Human Oversight | model_card.human_oversightagentic_governance_card.kill_switchagentic_governance_card.human_oversight.escalation_rules |
โ Oversight mechanisms defined for high-risk systems |
| Art. 15 | Accuracy Requirements | model_card.evaluation_evidencemodel_card.performance_metricsdataset_card.quality_metrics |
โ Metrics meet thresholds |
| Clause | Requirement | MCML Fields |
|---|---|---|
| 6.1 | Risk Assessment | model_card.failure_modesmodel_card.ethical_considerationsmodel_card.risk_acceptance |
| 7.2 | Competence | model_card.responsible_teamagentic_governance_card.identity.owner |
| 7.5 | Documented Information | All four card types |
| 8.1 | Operational Planning | model_card.intended_useagentic_governance_card.autonomy.decision_authority |
| 9.1 | Monitoring | model_card.monitoring_commitmentsagentic_governance_card.enforcement.audit_log |
| Principle | Requirement | MCML Fields | Validation |
|---|---|---|---|
| Art. 5.1.b | Purpose Limitation | model_card.intended_usemodel_card.out_of_scope_uses |
โ Explicit boundaries |
| Art. 5.1.c | Data Minimization | dataset_card.collection_methoddataset_card.pii_fields |
โ Only necessary data |
| Art. 5.1.e | Storage Limitation | dataset_card.retention_policy |
โ Retention period defined |
| Art. 13 | Transparency | model_card.limitationsdataset_card.known_biases |
โ Explainability |
| Art. 24 | Accountability | All cards: ownership fields | โ Controllers identified |
| Reference | Relevant MCML Fields |
|---|---|
| NIST AI Agent Standards Initiative (CAISI, launched February 2026) | identity, authorization, delegation, enforcement |
| OWASP Top 10 for Agentic Applications | threat_coverage, delegation, authorization |
MCML maps to these references by topic. It does not claim endorsement by NIST, OWASP, or any other body.
This repository contains the MCML v1.1 JSON Schemas, example cards, and a reference validator (tools/mcml.py) that checks cards and acts as a pre-deployment gate. A pip-installable package and Python SDK are planned (see Roadmap).
git clone https://github.com/PLEYVERSE-AI/mcml-standard
cd mcml-standard
pip install -r requirements.txt
python tools/mcml.py validate examples/credit-scoring/*.yaml
PASS examples/credit-scoring/agentic-governance-card.yaml (agentic_governance_card)
PASS examples/credit-scoring/dataset-card.yaml (dataset_card)
PASS examples/credit-scoring/interface-card.yaml (interface_card)
PASS examples/credit-scoring/model-card.yaml (model_card)
Cards are YAML or JSON files whose top-level key names the card type: model_card, dataset_card, interface_card or agentic_governance_card. The schemas are in schema/v1.1/ and can be used with any JSON Schema (draft 2020-12) validator.
python tools/mcml.py compliance-check examples/credit-scoring --framework nist # or eu-ai-act
PASS GOVERN
PASS MAP
PASS MEASURE
PASS MANAGE
nist: evidence present for all requirements
Note: this reports documentation evidence, not legal compliance.
pre-deploy-check exits non-zero, blocking the pipeline, when:
--require-agent) is missing or fails its schematraining_dataset_ref) does not resolve to a card in the stackunacceptable, or the risk-acceptance review is overduepython tools/mcml.py pre-deploy-check examples/blocked-deployment --require-agent
DEPLOYMENT BLOCKED
- examples/blocked-deployment/agentic-governance-card.yaml: agentic_governance_card: 'kill_switch' is a required property
- missing required dataset_card
- missing required interface_card
- examples/blocked-deployment/model-card.yaml: safety field 'failure_modes' is missing
...
.github/workflows/validate.yml runs the gate on every push. To use it in your own pipeline:
- run: pip install -r requirements.txt
- run: python tools/mcml.py pre-deploy-check governance/ --require-agent
| Folder | What it shows |
|---|---|
examples/credit-scoring/ |
Complete four-card stack for a credit model and a loan agent; passes the gate |
examples/clinical-alert-agent/ |
Synthetic healthcare stack: an agent that may page a rapid response team only after charge-nurse approval; passes the gate |
examples/blocked-deployment/ |
Incomplete stack the gate refuses |
The validator above implements use case 1. Use cases 2 to 5 describe planned SDK capabilities; the code shown is illustrative and not yet released.
Block incomplete deployments with python tools/mcml.py pre-deploy-check <dir>. See Getting Started.
from mcml import ComplianceReporter # planned API
reporter = ComplianceReporter()
nist_report = reporter.generate_report(
inference_event_id="evt_12345",
framework="nist_rmf",
output_format="pdf"
)
from mcml import GovernanceDashboard # planned API
status = GovernanceDashboard().get_production_status()
# {'total_models': ..., 'fully_documented': ..., 'missing_cards': ...}
from mcml import IncidentInvestigator # planned API
analysis = IncidentInvestigator().analyze_incident(
inference_event_id="incident_789",
include_full_lineage=True
)
# Returns the event, the model and dataset cards in force, and the matching known limitations and biases
A gateway outside the agentโs runtime enforces the signed Agentic Governance Card on every MCP tool call: it holds tool credentials, runs an out-of-band kill switch, checks model attestation, validates tool arguments, and links each decision to the toolโs own receipt. See the MCML Runtime Safety specification for the architecture, card fields, six-scenario threat model and known limits.
docs/mcml-spec.mdschema/v1.1/examples/tools/mcml.pySchemas allow additional properties, so organizations can add their own fields while staying valid.
MCML is an open standard. Contributions are welcome through GitHub issues and pull requests:
Available in this repository:
tools/mcml.py): schema validation, framework evidence reports, pre-deployment gate.github/workflows/validate.yml): runs the gate on every pushPlanned:
โ Core Specification
โ Compliance Mappings
โ Reference Architecture
โ Published in this repository
agentic_card: identity, scoped and time-limited authorization, delegation chains, runtime enforcement, kill switchโ Runtime safety fields in the Agentic Governance Card schema, with gate checks that block configurations an agent could bypass
๐ฒ In development
gateway/ with out-of-band kill switch, model provenance checks, payload validation, signed tool receipts and hash-chained evidence; 7 of 7 synthetic scenarios pass๐ฒ Planned
๐ฒ Incident Card: link post-deployment incidents to cards ๐ฒ Proposed MCP extension for agent governance evidence, if runtime testing supports it
๐ฎ Federated Learning Governance
๐ฎ Real-Time Governance Monitoring
๐ฎ Blockchain Integration
๐ฎ Extended Card Types
Q: What is MCML? A: MCML is a standard language that formalizes four documentation practices (Model, Dataset, Interface, and Agentic Governance cards) into a unified, machine-readable protocol for regulatory compliance.
Q: Did MCML invent Model Cards and Dataset Cards? A: No. Model Cards were created by Google (Mitchell et al., 2019) and Dataset Cards/Datasheets by Microsoft (Gebru et al., 2018). MCML formalizes these existing standards and adds machine readability.
Q: What problem does MCML solve? A: MCML enables automated compliance by making AI governance documentation machine-readable. Instead of manually reconstructing audit trails from PDFs and spreadsheets, you can programmatically validate completeness, generate compliance reports, and enforce governance requirements in CI/CD.
Q: Do I need to use the two-layer architecture? A: No. The two-layer architecture with foreign keys is our patent-pending reference implementation that demonstrates the benefits of MCML. You can implement MCML using any database, file system, or architecture. The standard is implementation-agnostic.
Q: What makes MCML โmachine-readableโ? A: MCML provides JSON Schemas with formal validation rules and structured field definitions, plus a reference validator. This allows tools to parse, validate, and query governance documentation automatically.
Q: How does MCML relate to NIST AI RMF / EU AI Act / GDPR? A: MCML provides mappings from card fields to regulatory requirements. It helps you demonstrate compliance but doesnโt guarantee it. You still need to satisfy the actual regulatory requirements. MCML makes it easier to document and prove.
Q: Can I extend MCML with custom fields?
A: Yes. MCML schemas support additionalProperties for organization-specific extensions. You can add custom fields while maintaining compatibility with the core standard.
Q: How do the four card types relate? A: Cards reference each other via URIs:
Q: What if my organization doesnโt use AI agents? A: Agentic Governance Cards are optional. If youโre not deploying autonomous agents, you only need Model, Dataset, and Interface cards.
Q: Is MCML only for ML models, or can it document traditional software? A: MCML is designed for AI/ML systems. For traditional software, use standard documentation practices (OpenAPI, README, etc.). However, Interface Cards can document any API.
Q: How do I migrate existing documentation to MCML?
A: Migration tooling is planned. Today, copy the relevant fields from your existing Model Card or Datasheet into the YAML structure shown in examples/ and run python tools/mcml.py validate until it passes.
Q: What if Iโm already using MLflow / Weights & Biases / other MLOps tools? A: MCML is designed to sit alongside existing tools. Cards are plain YAML or JSON, so they can be generated from MLOps metadata by your own scripts; official MLflow and W&B integrations are planned.
Q: How often should cards be updated? A:
Q: Can MCML be used for open source models? A: Yes. MCML is well suited to documenting open source models. Publish Model and Dataset Cards alongside your model releases to provide transparency and enable responsible use.
Q: How does MCML handle model versioning?
A: Each card includes a version field (semantic versioning recommended: 1.0.0, 1.1.0, 2.0.0). Cards can reference specific versions of other cards via URIs like dataset://customer_data/v2.3.
Q: What about models trained on proprietary data?
A: Dataset Cards can document data characteristics (biases, quality) without exposing proprietary details. Use collection_method: "Proprietary customer data" and document known biases and limitations without revealing specifics.
| โMCML: A Universal Schema for AI Traceability & Lifecycle Governance,โ co-presented with Alex Olaniyan (PLEYVERSE AI), virtual Day 1 session, 6th annual MLOps World | GenAI Summit, October 2025. Recording |
The two-layer architecture with foreign key relationships for AI governance is patent pending. Implementing the MCML specification and schemas does not require a patent license.
MCML is open in the way Linux is: free to use and build on, with changes to the code shared back, and commercial licenses available.
The MCML specification, JSON Schemas, compliance mappings, example cards and documentation are licensed under Creative Commons Attribution 4.0 International. Anyone, including commercial vendors, may use, adapt and implement the standard, provided they give credit and indicate changes.
The code in this repository (tools/ and any future SDKs, gateway and reference implementation code) is licensed under the GNU General Public License v3.0 or later. You may use it for any purpose, including commercially. If you distribute modified versions, you must release them under the same license.
Organizations that want to embed or distribute the code in proprietary products without GPL obligations can obtain a commercial license: contact lanre@pleyverse.com.
Contributions are accepted under the same terms, so the project can continue to offer both licenses.
MCML builds on pioneering work by:
We are grateful to the AI governance research community, open source contributors, and early adopters who shaped this standard.
If MCML helps your AI governance work, please star this repository to show support and help others discover the standard.
If you use MCML in research or production, please cite:
@misc{mcml_standard,
title = {Model Connect Markup Language (MCML): A Machine-Readable Standard for AI Governance},
author = {Ogunkunle, Olanrewaju},
year = {2026},
url = {https://mcml-standard.org}
}
For the reference implementation:
@misc{mcml_two_layer_2026,
title = {Two-Layer Architecture for AI Governance Traceability},
author = {Ogunkunle, Olanrewaju},
year = {2026},
note = {Patent pending. Reference implementation of the MCML standard.},
url = {https://mcml-standard.org}
}
Model Connect Markup Language (MCML): From documentation to automation. Making AI governance machine-readable, compliant, and auditable.
| **Version 1.1 (draft) | Last updated: 2026-11-10** |