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

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. Add 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

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.

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.