gov-mcp

Governed execution for any AI agent framework. Install in 30 seconds. Works with Claude Code, OpenClaw, and any MCP-compatible client.

pip install gov-mcp
gov-mcp install

An MCP server that enforces runtime governance on AI agent actions — file access, command execution, delegation chains, and permission escalation. Built on the Y*gov governance kernel.

Why

AI agents can read files, run commands, and call APIs. Without governance, a single prompt injection or misaligned sub-agent can rm -rf /, leak .env secrets, or escalate privileges.

gov-mcp sits between the agent and the system. Every action is checked against a governance contract before execution. Deterministic commands are auto-executed inline — no second tool call needed.

Related MCP server: Waymark

Performance (EXP-008)

Security (SIM-001 tested): 50 concurrent agents, 1,000 checks, zero data leaks across isolated tenants.

Compliance: FINRA audit trail (3/4 requirements met), EU AI Act Article 14 compatible (3/5 met out of box, remaining 2 partial with clear upgrade path).

Limitations (Honest Assessment)

• Per-event auto-hash: Implemented in v0.1.0 via governance envelope chain

• Confidence score: Included in every governance response (1.0 deterministic, 0.95 auto-routed)

• Multi-currency amount parsing: Supported ($, ¥, €, £, USD/EUR/CNY prefix, comma separators)

• Per-client encryption keys: Not yet available (roadmap for legal vertical)

• COSO/ISO report templates: Not yet available (roadmap for enterprise compliance)

• Non-MCP ERP integration: Requires custom adapter (no native SAP/Oracle bridge)

Quick Start

1. Install

pip install gov-mcp

2. Write your governance contract

Create AGENTS.md:

## Agent: my-agent
## Prohibited: rm -rf, sudo, .env files, /etc access
## Permitted: file read/write, shell commands

3. One-command install

gov-mcp install

This will:

1. Detect your environment (Claude Code, Cursor, Windsurf, OpenClaw)

2. Start the GOV MCP server (background, auto port selection)

3. Auto-configure detected clients

4. Verify the connection

5. Print a summary with next steps

4. Management commands

gov-mcp status     # Check if server is running
gov-mcp restart    # Restart with fresh config
gov-mcp uninstall  # Stop server, remove all configs

5. Manual setup (alternative)

If you prefer manual configuration:

# Start server directly
python -m gov_mcp --agents-md ./AGENTS.md --transport sse --port 7922

Connect from any MCP client:

{
  "mcpServers": {
    "gov-mcp": {
      "url": "http://127.0.0.1:7922/sse",
      "transport": "sse"
    }
  }
}

Tools (38)

Core Enforcement

Delegation & Escalation

Contract Management

Audit & Observability

Governance Analysis

User Experience

Domain & Data

How It Works

Agent proposes action
    |
    v
gov_check(agent_id, tool_name, params)
    |
    +-- Is agent delegated? --> Use delegated contract
    |   (otherwise)         --> Use global contract
    |
    +-- Contract check: ALLOW or DENY
    |
    +-- If ALLOW + deterministic Bash command:
    |   Execute inline, return stdout in response
    |   { "decision": "ALLOW", "auto_executed": true, "stdout": "..." }
    |
    +-- If ALLOW + non-deterministic:
    |   Return ALLOW only (agent handles execution)
    |
    +-- If DENY:
        Return DENY with violation details

Auto-Execution

Deterministic commands (ls, git status, cat, pwd, etc.) are classified by the structural router and executed inline within gov_check. The agent receives stdout/stderr in the same response — no second tool call needed.

This saves 22% tokens and eliminates one LLM round-trip per safe command. 66.7% of typical Bash commands are auto-executed (based on stress testing).

Governance Extension Layer

Every gov_check response includes a governance field — a structured audit envelope that rides on top of the MCP protocol:

{
  "decision": "ALLOW",
  "auto_executed": true,
  "stdout": "...",
  "governance": {
    "cieu_seq": 17753,
    "contract_hash": "sha256:b6e47016...",
    "contract_version": "1.0",
    "latency_ms": 1.9,
    "host": "claude_code"
  }
}

This is backward compatible — callers that don't inspect governance are unaffected. The field enables audit trails, compliance reporting, and contract versioning across multi-agent deployments.

A2A Integration (Coming Soon)

Y*gov is designed as the governance layer for A2A (Agent-to-Agent) ecosystems. Every agent-to-agent communication can be audited, controlled, and proven compliant with CIEU five-tuple records.

Roadmap:

• Phase 1 (Current): GOV MCP — governance for MCP tool calls (33 tools, 100% coverage)

• Phase 2 (2026 Q3): GOV A2A — governance layer for the A2A protocol

• Phase 3 (2026 Q4): Gov Pipeline — end-to-end multi-agent workflow governance

License

MIT