███╗   ███╗  ██████╗ ██████╗     ██████╗  ██████╗ ██╗   ██╗
████╗ ████║ ██╔════╝ ██╔══██╗   ██╔════╝ ██╔═══██╗██║   ██║
██╔████╔██║ ██║      ██████╔╝   ██║  ███╗██║   ██║██║   ██║
██║╚██╔╝██║ ██║      ██╔═══╝    ██║   ██║██║   ██║╚██╗ ██╔╝
██║ ╚═╝ ██║ ╚██████╗ ██║        ╚██████╔╝╚██████╔╝ ╚████╔╝
╚═╝     ╚═╝  ╚═════╝ ╚═╝         ╚═════╝  ╚═════╝   ╚═══╝

MCP Governance System

Permission control and audit logging for Model Context Protocol (MCP) servers.

What is MCP-GOV?

MCP-GOV adds a security layer between your AI assistant (Claude, etc.) and MCP tool servers. It:

• Controls permissions - Block dangerous operations like delete, execute, admin
• Logs everything - Audit trail of all tool calls with timestamps
• Works transparently - No changes needed to your MCP servers

Install

# Using npm
npm install -g mcp-gov

# Or run directly with npx
npx mcp-gov

Usage

mcp-gov

███╗   ███╗  ██████╗ ██████╗     ██████╗  ██████╗ ██╗   ██╗
████╗ ████║ ██╔════╝ ██╔══██╗   ██╔════╝ ██╔═══██╗██║   ██║
██╔████╔██║ ██║      ██████╔╝   ██║  ███╗██║   ██║██║   ██║
██║╚██╔╝██║ ██║      ██╔═══╝    ██║   ██║██║   ██║╚██╗ ██╔╝
██║ ╚═╝ ██║ ╚██████╗ ██║        ╚██████╔╝╚██████╔╝ ╚████╔╝
╚═╝     ╚═╝  ╚═════╝ ╚═╝         ╚═════╝  ╚═════╝   ╚═══╝
                                                   v2.0.0

Select action:
  1) Wrap MCP servers
  2) Unwrap MCP servers
  3) View audit logs
  4) Edit rules
  5) Exit

Enter choice [1-5]:

How It Works

┌─────────────────────────────────────────────────────────────┐
│                     WITHOUT MCP-GOV                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Claude ──────────────────────────────► MCP Server         │
│           (all operations allowed)       (filesystem,       │
│                                           github, etc.)     │
│                                                             │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                      WITH MCP-GOV                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Claude ────► mcp-gov-proxy ────► MCP Server               │
│                     │                                       │
│                     ├── Check rules.json                    │
│                     │   ├── read: ✅ allow                  │
│                     │   ├── write: ✅ allow                 │
│                     │   ├── delete: ❌ deny                 │
│                     │   └── admin: ❌ deny                  │
│                     │                                       │
│                     └── Log to audit.log                    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Workflow

1. Install         npm install -g mcp-gov
                            │
                            ▼
2. Run             mcp-gov
                            │
                            ▼
3. Select          1) Wrap MCP servers
                            │
                            ▼
4. Enter path      ~/.claude.json
                            │
                            ▼
5. Done!           ✓ Servers wrapped
                   ✓ Rules generated at ~/.mcp-gov/rules.json
                   ✓ Audit logs at ~/.mcp-gov/logs/

Default Rules

Rules are auto-generated at ~/.mcp-gov/rules.json:

| Operation | Default | Examples | |-----------|---------|----------| | read | ✅ Allow | get, list, search, fetch | | write | ✅ Allow | create, update, add, save | | delete | ❌ Deny | delete, remove, drop, purge | | execute | ❌ Deny | run, exec, invoke, trigger | | admin | ❌ Deny | admin, configure, grant |

Files

| Path | Description | |------|-------------| | ~/.mcp-gov/rules.json | Governance rules | | ~/.mcp-gov/logs/*.log | Audit logs by service |

Rules Format

{
  "defaultPolicy": "deny",
  "rules": [
    {
      "service": "github",
      "operations": ["delete"],
      "permission": "deny",
      "reason": "Block destructive operations"
    },
    {
      "service": "github",
      "operations": ["read", "write"],
      "permission": "allow"
    }
  ]
}

defaultPolicy controls what happens when no rule matches a service/operation:

• "deny" — fail-closed: only explicitly-allowed operations pass (recommended). New rules files generated by mcp-gov-wrap use this and include a complete allow/deny rule set per service, so normal read/write traffic is unaffected.
• "allow" — fail-open: anything not explicitly denied passes. This is the default when defaultPolicy is omitted, for backward compatibility. Existing rules files keep this behavior until you add "defaultPolicy": "deny".

Two older rule shapes are still accepted and normalized internally: the legacy { "services": { svc: { "operations": { op: "allow"|"deny" } } } } object, and the library's nested map { svc: { op: "allow"|"deny" } } (used by GovernedMCPServer). defaultPolicy may be set at the top level of any of them.

Audit Log Format

Audit records are written one JSON object per line (so tool names can't forge or corrupt entries). Each record:

{"type":"AUDIT","timestamp":"2026-01-24T10:30:45.123Z","status":"DENIED","tool":"delete_repo","service":"github","operation":"delete","project":"/home/user/myproject"}

CLI Commands

The interactive menu is recommended, but you can also use commands directly:

# Wrap servers
mcp-gov-wrap --config ~/.claude.json

# Unwrap servers
mcp-gov-unwrap --config ~/.claude.json

# Low-level proxy (used internally)
mcp-gov-proxy --service github --target "npx server" --rules ~/.mcp-gov/rules.json

Security Model & Limitations

MCP-GOV is a useful guardrail, not a complete sandbox. Know what it does and does not protect:

• Operation type is inferred from the tool name (keyword matching), and tool arguments are not inspected. A destructive tool whose name contains no destructive keyword is classified write. For stronger control, write explicit per-service rules and set "defaultPolicy": "deny".
• Only tools/call is mediated. Other MCP methods (resources/*, prompts/*, etc.) pass through unchecked.
• Config backups may contain secrets (tokens copied from your MCP config). They are written with 0600 permissions and are gitignored (*.backup-*), but you should still clean them up.
• Treat the audit log as a record, and the rules as advisory policy — not as a hard security boundary against a fully adversarial MCP server.

License

Apache-2.0 — see LICENSE.