Governance Gateway

governance-gateway

Governance checks that an AI agent runs before it acts, built so they keep up with the agent instead of falling behind it.

Every request gets a format check and a personal-data (PII) scan, which never skip. A safety classifier, which flags toxic text and jailbreak attempts, is the slow, optional check: it runs only if a cheap screen finds the text suspicious and it can still finish before the request's deadline. Under load, a guardrail that checks everything falls behind and its checks finish after the agent has already acted; this one stays on time and never drops the privacy check.

It runs locally as an MCP server, so text never leaves your machine, and works with any MCP client: Claude Desktop, Claude Code, Cursor, VS Code, Gemini CLI and others. In Claude Code an optional hook makes the checks compulsory for every command, file write and web request the agent makes.

Install

With uv nothing needs installing in advance:

uvx governance-gateway --version

Or with pip: pip install governance-gateway, then run governance-gateway. Python 3.10 or later; the only dependency is the mcp package.

Add it to your AI tool

Claude Desktop: in claude_desktop_config.json (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "governance-gateway": { "command": "uvx", "args": ["governance-gateway"] }
  }
}

Cursor: the same block in ~/.cursor/mcp.json (or .cursor/mcp.json in a project).

Gemini CLI: the same block in ~/.gemini/settings.json.

VS Code (Copilot agent mode): in .vscode/mcp.json:

{
  "servers": {
    "governance-gateway": { "type": "stdio", "command": "uvx", "args": ["governance-gateway"] }
  }
}

Claude Code:

claude mcp add governance-gateway -- uvx governance-gateway

If you installed with pip, use "command": "governance-gateway" and no args.

Tools

Tool	What it does
check_message(text, deadline_ms=100)	Runs the checks. Returns allow, redact (with the personal data masked) or block, the reasons, whether the screen and the classifier ran, and the timing. Never echoes the text back.
governance_status()	Requests so far: verdicts, mean and 95th-percentile lag, share on time, share of classifier checks skipped or screened out.
recent_decisions(limit=20)	The latest decisions: verdict, kinds of personal data found, timing. No text.
decision_matrix(...)	For a pipeline's deadline, traffic shape, peak-hour factor, detector recall, target and cost share: whether checking everything is enough, adaptive checking is needed, or only more capacity helps.
simulate_load(load, deadline_ms, traffic, seconds)	Races "check everything" against the deadline-aware guard on a simulated clock with measured check costs.

Resources: governance://status and governance://policy (which checks run, which are mandatory, and how the gateway decides). All tools are read-only.

Make the checks compulsory in Claude Code

An MCP tool is only called when the agent decides to call it. In Claude Code a PreToolUse hook can run the check before every action instead. The easiest way is the governance-guard plugin, which adds both the server and the hook:

/plugin marketplace add tanishq-ctrl/governance-gateway
/plugin install governance-guard@governance-gateway

Or add the hook yourself to ~/.claude/settings.json (or a project's .claude/settings.json):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit|MultiEdit|NotebookEdit|WebFetch",
        "hooks": [
          {
            "type": "command",
            "command": "uvx",
            "args": ["--from", "governance-gateway", "governance-gateway-hook"],
            "timeout": 10,
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

The hook sends the text of each action (the command, the file content, the URL) to the running gateway, with a budget of GSL_HOOK_DEADLINE_MS (default 200 ms):

• harmful or malformed: the action is refused and the agent is told why;
• personal data found: you are asked whether to allow it;
• otherwise: nothing changes, and your normal permissions apply.

If the gateway is not running, the hook still runs the personal-data scan itself. If the check cannot run at all, the action is blocked (set GSL_FAIL_OPEN=1 to allow it instead). Addresses at GSL_ALLOW_EMAIL_DOMAINS (default anthropic.com, users.noreply.github.com, example.com) are ignored, so commit trailers pass.

Settings

Option	Environment	Default	Meaning
--cascade on/off	GSL_CASCADE	on	Run the suspicion screen before the classifier
--estimator p90/mean	GSL_ESTIMATOR	p90	How the classifier's cost is estimated from recent checks
--workers N	GSL_GATEWAY_WORKERS	1	Workers serving the queue
--audit-log PATH	GSL_AUDIT_LOG	none	Append one JSON line per decision (no text)
--port N	GSL_GATEWAY_PORT	8737	Local port for the hook (127.0.0.1 only)
--no-hook-endpoint			Do not open the local port

What it detects, and what it does not

• Personal data: e-mail addresses, telephone numbers and US-style national ID numbers, by pattern. Names, postal addresses and other identifiers are not detected.
• Harmful text: a TF-IDF and logistic-regression classifier trained on ToxicChat, real prompts to a public chatbot labelled by people. On held-out ToxicChat messages it catches about 6 in 10 harmful messages with a precision of about 0.78; it is a light first line of defence, not a complete safety system, and it was trained on English.
• The screen passes on 95% of harmful messages in validation and sends about 31% of ordinary traffic to the classifier.

Use it alongside, not instead of, your organisation's own data-protection controls.

Background

The gateway comes from an MSc project that measured how far governance checks fall behind fast automated decisions as load grows. Checking everything collapses at full capacity: on real chatbot traffic it stopped meeting its target at 77% of capacity. The deadline rule held to 1.06, and the screen plus the deadline rule to 1.44, while keeping the privacy check on time.

Prabhu, T. S. (2026). Quantifying "Governance Speed Lag" (GSL) in Agentic AI Ecosystems: A simulation-based framework for self-adaptive real-time data compliance. MSc Data Science project, VIT.

Source and issues

https://github.com/tanishq-ctrl/governance-gateway

Licence

Code: MIT. The bundled models and workload data are derived from ToxicChat and are for non-commercial use only (CC BY-NC 4.0); see LICENSE-DATA.md.