AgentsGate

AI Agent I/O Tracking & Rollback System — MCP Proxy Gateway

Status: 0.1.0, first public release. The proxy, risk scoring, checkpoints and rollback are covered by 7,200 tests, but the API surface should be treated as unstable until 1.0 — command flags and config keys may still change. Read SECURITY.md before exposing anything beyond loopback.

AgentsGate sits between AI agents (Claude, GPT, etc.) and the MCP tools they call. Every tool call is intercepted, risk-scored, checkpointed, and optionally paused for human approval before execution. If an agent does something destructive, you can roll back in seconds.

AI Agent (Claude, GPT, etc.)
        ↓ MCP Protocol
  ┌──────────────────────────┐
  │   AgentsGate Proxy      │  ← All traffic passes here
  └────────┬─────────────────┘
           │
    ┌──────▼──────┐    ┌──────────────────────┐    ┌────────────────────┐
    │   Logger    │    │  Risk Engine (L1/L2) │    │  Policy Engine     │
    └──────┬──────┘    └──────┬───────────────┘    └────────┬───────────┘
           │                  │                             │
    ┌──────▼──────────────────▼─────────────────────────────▼───────────┐
    │                     SQLite State Store                             │
    └──────────────────────────────┬─────────────────────────────────────┘
                                   │
                          ┌────────▼────────┐
                          │  Intervention   │  ← Block / Allow / Require-approval
                          └────────┬────────┘
                                   │
               allowed ────────────┤──────────── blocked / pending
                                   ↓
                          ┌────────▼────────┐
                          │  Actual MCP Tool│
                          └─────────────────┘

   Dashboard REST API  ←→  SQLite  (read-only visibility, real-time SSE)

---

Security model — read this first

AgentsGate is a local, single-operator tool. It records everything your agent does, including tool arguments and results that routinely contain file contents, database rows, and credentials.

The proxy transport has no authentication, and the dashboard's is opt-in. That is safe only because AgentsGate binds to loopback by default:

Surface	Default port	Default bind	Built-in auth
MCP proxy	4000	127.0.0.1	None
Dashboard REST/SSE	4001	127.0.0.1	Opt-in (dashboard.apiKey)

proxy.host controls the bind address for the proxy, dashboard, and WebSocket gateway. Leave it at 127.0.0.1 unless you know exactly what you are doing.

If you set proxy.host to a routable address, you must put an authenticating reverse proxy in front of it. No AgentsGate setting alone makes a non-loopback bind safe — exposing it without a reverse proxy means unauthenticated operation forwarding plus full read access to your agent's history. AgentsGate prints a startup warning when you do this; treat it as an error in production.

For the full threat model, residual risks, and a deployment checklist, see SECURITY.md.

---

Features

Proxy & Interception

• Zero-trust MCP proxy — every tool call intercepted regardless of agent cooperation
• Stdio transport support (MCPStdioProxy) for pipe-based MCP clients
• Dry-run mode (--dry-run) — scores and logs without blocking any operations
• Per-operation session tracking, agent identification, and tag propagation

Risk Scoring

• L1 static rules — 8 built-in rules covering destructive file ops, sensitive path writes, database drops, command execution, git force-push
• L2 user history — per-agent Bayesian model (requires ≥10 outcomes)
• L3 community enrichment — configurable HTTP endpoint (opt-in)

Checkpoints & Rollback

• Pre-operation file snapshots into a shadow git repository
• One-command rollback to any checkpoint
• Checkpoint diff view before restoring
• Rollback preview (dry-run before committing restore)

Policy System

• Custom policy rules loaded from ~/.agentsgate/policy.json
• Per-rule match on tool, method, agentId, pathPattern, and tags
• Rule actions: allow, block, require_approval, or score override
• Agent allowlist / denylist
• Per-agent tool allowlist / denylist
• L1 rule muting and score overrides
• Live policy stats via the dashboard

Approval Queue

• Pending operations pause at the proxy until approved or denied
• Webhook notifications (with retry) on enqueue
• Slack Incoming Webhook integration
• Escalation webhooks for stale approvals
• Approvals persist across restarts (SQLite-backed)
• Auto-expiry with configurable TTL (default 24h)
• Real-time SSE push when approvals expire

Dashboard API (see docs/api-reference.md)

• Full REST API: operations, agents, tools, sessions, risk, checkpoints, rollback, approvals, policy, telemetry, circuit breakers, rate limits, quota, audit
• Server-Sent Events (GET /events) for live operation feed
• Prometheus metrics (GET /metrics)
• RBAC via X-API-Key header
• Audit log HMAC-SHA256 verification (GET /audit/verify)
• CSV export for operations

Telemetry & Analytics

• Anonymized aggregate stats — zero PII stored
• Anomaly detection with z-score alerting (configurable threshold)
• Periodic export to a configurable HTTP endpoint
• Per-agent, per-tool, per-session telemetry breakdowns

Plugin Adapters

• BaseRollbackAdapter base class for extending rollback to SaaS tools
• Community adapter registry — load adapters from a directory

Operations Management

• Per-agent and per-tool operation history
• Full-text and filter-based search across operations
• Rate limiting per agent (ops/minute)
• Circuit breaker per agent
• Daily quota management per agent
• Log retention and pruning

Developer / Ops Tools

• agentsgate doctor — environment health check
• agentsgate benchmark — throughput benchmark
• agentsgate inject / eject — auto-configure Claude Desktop
• agentsgate completion — shell autocomplete

---

Installation

npm install -g agentsgate

Or run directly without installing:

npx agentsgate start

For local development from a fresh clone:

git clone https://github.com/agentsgate/agentsgate.git
cd agentsgate
npm run bootstrap

---

Quick Start

# Start the proxy (default port 4000, dashboard on port 4001)
agentsgate start

# Start on a custom port
agentsgate start 8080

# Check that the proxy is running
agentsgate status

# Show effective config
agentsgate config

# Show dashboard health
agentsgate health

Configure Claude Desktop

# Auto-inject AgentsGate into Claude Desktop's MCP config
agentsgate inject

# Verify injection
agentsgate status

# Remove injection
agentsgate eject

Restart Claude Desktop after injection. All Claude tool calls now flow through AgentsGate.

---

CLI Reference

Commands are grouped by category. Run agentsgate <command> --help for full flag details.

Startup

Command	Description
agentsgate start [port] [--config=path] [--policy=path] [--dry-run] [--log-ttl=ms]	Start the proxy and dashboard
agentsgate stop	Send stop signal to the running proxy
agentsgate status	Show proxy PID, port, dashboard URL, and start time
agentsgate health	Liveness check against the running dashboard
agentsgate doctor	Diagnose environment (Node version, build, config, DB)
agentsgate inject	Auto-configure Claude Desktop to route through AgentsGate
agentsgate inject status [--config=path]	Show current injection status
agentsgate eject	Remove AgentsGate from Claude Desktop config
agentsgate proxy [subcommand]	Stdio proxy mode

Database MCP servers

Register a guarded database server in the Claude config, so the SQL an agent issues is risk-scored and checkpointed like any other tool call. Restart Claude Desktop / Claude Code after registering.

Command	Description
agentsgate inject-db --db=<path> [--name=X] [--force] [--config=path]	Register the SQLite MCP server
agentsgate inject-sqlite --db=<path>	Alias for inject-db
agentsgate inject-pg --connection-string=<url> [--name=X] [--force]	Register the PostgreSQL MCP server
agentsgate inject-mysql --connection-string=<url> [--name=X] [--force]	Register the MySQL MCP server
agentsgate inject-db|inject-pg|inject-mysql remove [--name=X]	Remove that server from the Claude config
agentsgate db snapshot prune --db=<path> [--older-than=<Nd|Nh>]	Delete rollback snapshots older than the cutoff (default 7d)

# PostgreSQL — the connection string is redacted in all output and logs
agentsgate inject-pg --connection-string=postgresql://user:pass@localhost:5432/mydb

# Several databases at once — distinguish them with --name
agentsgate inject-pg    --connection-string=postgresql://... --name=production-db
agentsgate inject-mysql --connection-string=mysql://...      --name=staging-db

Configuration

Command	Description
agentsgate config	Print effective config (merged defaults + file)
agentsgate config show	Fetch live sanitized config from running dashboard

Operations

Command	Description
agentsgate logs [limit] [--action=X] [--tool=X] [--agentId=X] [--sessionId=X]	List recent operation logs
agentsgate ops watch	Live-tail operations via SSE
agentsgate ops tail [--limit=N] [--action=X] [--tool=X] [--agent=X] [--tags=X]	Tail operations in tabular format
agentsgate ops summary	Aggregate statistics (counts, risk, trends, top agents/tools)
agentsgate ops stats [--agentId=X] [--tool=X] [--limit=N]	Offline stats from local DB
agentsgate ops export [--format=csv|json] [--out=file]	Export operations to CSV or JSON
agentsgate ops get <id>	Fetch a single operation by ID
agentsgate ops count [filters]	Count operations matching filters
agentsgate ops prune [--before=date] [--dry-run]	Prune old operation logs
agentsgate risk [--operationId=X] [--agentId=X] [--limit=N]	Show risk assessments
agentsgate explain <operationId>	Explain the risk decision for a specific operation
agentsgate replay <operationId> [--dry-run]	Re-run an operation through the pipeline
agentsgate top [--by=risk|count] [--limit=N]	Top agents/tools by risk or count
agentsgate watch [--filter=X]	Live watch operation stream
agentsgate benchmark [--ops=N]	Throughput benchmark
agentsgate export [--format=X] [--out=file]	Export full operation history

Policy

Command	Description
agentsgate policy	Print current policy rules
agentsgate policy list	List all policy rules with details
agentsgate policy add --id=X --action=X --tool=X [--method=X] [--agentId=X] [--pathPattern=X] [--score=N] [--priority=N] [--description=X]	Add a new policy rule
agentsgate policy remove --id=X	Remove a policy rule by ID
agentsgate policy [--policy=path]	Load policy from a specific file

Sessions

Command	Description
agentsgate sessions [list]	List sessions with event counts and risk stats (requires telemetry)
agentsgate sessions <sessionId>	Detail for one session
agentsgate session <sessionId>	Show operations for a specific session
agentsgate session expire <sessionId>	Force-expire a session — blocks all its future operations
agentsgate session-ops [sessionId]	Session detail derived from the operation log

Agents

Command	Description
agentsgate agents	List all agents with operation counts and risk stats
agentsgate agent <agentId>	Detail view for a single agent
agentsgate agents tools <agentId>	Tools used by an agent
agentsgate agents sessions <agentId>	Sessions for an agent

Tools

Command	Description
agentsgate tools	List all tools with operation counts and risk stats
agentsgate tool <toolName>	Detail view for a single tool

Telemetry

Command	Description
agentsgate telemetry	Current in-memory telemetry snapshot
agentsgate telemetry sessions	Per-session telemetry
agentsgate telemetry agents	Per-agent telemetry
agentsgate telemetry tools	Per-tool telemetry

Checkpoints & Rollback

Command	Description
agentsgate checkpoints [limit] [--operationId=X]	List recent checkpoints
agentsgate snapshot [--operationId=X]	Manage snapshots
agentsgate diff <checkpointId>	Show diff for a checkpoint
agentsgate rollback <checkpointId>	Restore files from a checkpoint

Approvals

Command	Description
agentsgate approvals	List pending approval requests
agentsgate approve <id>	Approve a pending operation
agentsgate deny <id>	Deny a pending operation

Audit & Debug

Command	Description
agentsgate audit [--verify] [--limit=N]	HMAC-verify operation log integrity
agentsgate verify-logs [--limit=N]	Verify HMAC signatures on recent logs
agentsgate errors [limit]	Recent errors recorded by the running proxy
agentsgate circuit-breakers [reset <agentId>]	View or reset per-agent circuit breakers
agentsgate rate-limits	View per-agent rate limiter stats
agentsgate quota	View per-agent daily quota usage
agentsgate report [--agentId=X] [--format=X]	Generate a risk report
agentsgate tree	Show the operation tree
agentsgate prune [--days=N] [--dry-run]	Prune old logs from the database
agentsgate completion [bash|zsh|fish]	Print shell completion script

---

Dashboard API

While the proxy is running, a REST server on port+1 (default: 4001) provides full visibility and control. See docs/api-reference.md for the complete endpoint reference.

Key features:

• All endpoints (except GET /health) require X-API-Key header when dashboard.apiKey is set
• Real-time events via GET /events (Server-Sent Events)
• Prometheus metrics via GET /metrics
• CSV export via GET /operations/export
• Rollback via POST /rollback/:checkpointId
• Approval management via POST /approvals/:id/approve and POST /approvals/:id/deny

---

Risk Scoring

Operations are scored 0.0 (safe) → 1.0 (extremely risky) using three layers:

Layer	Source	Status
L1 Static rules	Built-in rule set	Always active
L2 User history	Per-agent Bayesian model	Active (requires ≥10 outcomes)
L3 Community	Configurable HTTP enrichment	Opt-in via intelligence.communityEndpoint

L1 Rules

Rule ID	Trigger	Default Score
L1_DELETE_FILE	delete_file, unlink, rm on filesystem tools	0.90
L1_SENSITIVE_PATH_WRITE	Write to .env, .ssh/, .aws/, credentials, etc.	0.90
L1_DROP_TABLE	drop/truncate on non-filesystem tools	0.95
L1_DELETE_RECORD	delete/remove on non-filesystem tools	0.75
L1_EXECUTE_COMMAND	execute, exec, shell, spawn	0.80
L1_GIT_FORCE_PUSH	force/reset/rebase on github/git tools	0.85
L1_OVERWRITE_FILE	write_file, overwrite, create on filesystem	0.65
L1_READ_ONLY	read_*, list_*, get_*, describe_*, etc.	0.05

Intervention thresholds (default)

Score range	Action
< 0.3	allow — proceed immediately
0.3 – 0.69	require_approval — pause, create checkpoint, wait for user
≥ 0.7	block — reject outright

Override thresholds in policy.json or config.json.

---

Policy System

Create ~/.agentsgate/policy.json to define custom rules:

{
  "rules": [
    {
      "id": "BLOCK_PROD_DB_DELETE",
      "description": "Always block deletes on the production database tool",
      "match": { "tool": "database", "method": "/delete|drop/i" },
      "action": "block"
    },
    {
      "id": "TRUST_READONLY_AGENT",
      "description": "Treat all ops from the readonly-agent as low risk",
      "match": { "agentId": "readonly-agent" },
      "score": 0.05
    },
    {
      "id": "ELEVATE_SECRET_WRITES",
      "description": "Treat writes to /secrets/ as very high risk",
      "match": { "pathPattern": "/secrets/" },
      "score": 0.95
    }
  ],
  "thresholds": { "allowBelow": 0.2, "blockAtOrAbove": 0.8 },
  "agents": {
    "denylist": ["untrusted-agent-*"],
    "allowlist": [],
    "toolRules": {
      "limited-agent": {
        "allowlist": ["filesystem", "search"]
      }
    }
  },
  "mutedRules": [],
  "ruleOverrides": {
    "L1_OVERWRITE_FILE": 0.4
  }
}

Policy rule fields

Field	Type	Description
id	string	Unique rule identifier
description	string	Human-readable description (optional)
match.tool	string	Exact or /regex/ match on tool name
match.method	string	Exact or /regex/ match on method name
match.agentId	string	Exact or /regex/ match on agent ID
match.pathPattern	string	Regex matched against params.path / params.filePath
match.tags	string[]	Operation must have ALL of these tags
score	number	Override L1 risk score (0–1)
action	string	Force allow, block, or require_approval
priority	number	Evaluation order — lower wins (default: 100)
max	number	Maximum score this rule can produce
redact	string[]	Parameter keys to redact in the audit log

---

Plugin Adapters

Extend rollback to external services by implementing RollbackAdapter. See docs/plugin-authoring.md for the full authoring guide.

Quick example:

import { BaseRollbackAdapter } from 'agentsgate';
import type { MCPOperation, RollbackCapability, StateSnapshot, RollbackResult, RollbackPreview } from 'agentsgate';

export default class GitHubIssueAdapter extends BaseRollbackAdapter {
  readonly adapterId = 'github-issues';
  readonly version = '1.0.0';
  readonly supportedTools = ['github', 'github-mcp'];

  async canRollback(operation: MCPOperation): Promise<RollbackCapability> {
    const isDestructive = ['close_issue', 'delete_comment'].includes(operation.method);
    return { canRollback: isDestructive, confidence: 0.9 };
  }

  async captureState(context: MCPOperation): Promise<StateSnapshot> {
    // Snapshot current state before the operation
    return { adapterId: this.adapterId, operationId: context.id, data: {}, capturedAt: new Date() };
  }

  async rollback(snapshot: StateSnapshot): Promise<RollbackResult> {
    // Restore via external API
    return { success: true, restoredFiles: ['github:issue'], failedFiles: [] };
  }

  async previewRollback(snapshot: StateSnapshot): Promise<RollbackPreview> {
    return { willRestore: ['github:issue#1'], cannotRestore: [], warnings: [] };
  }
}

Load adapters at startup:

import { CommunityAdapterRegistry } from 'agentsgate';

const registry = new CommunityAdapterRegistry();
await registry.load('./plugins');   // scans ./plugins/*.js

---

Configuration

Config file: ~/.agentsgate/config.json

{
  "proxy": {
    "port": 4000,
    "host": "127.0.0.1",
    "checkpointThreshold": 0.3
  },
  "intervention": {
    "allowBelow": 0.3,
    "blockAtOrAbove": 0.7
  },
  "webhook": {
    "url": "https://your-webhook-endpoint.example.com",
    "secret": "your-hmac-signing-secret",
    "slackUrl": "https://hooks.slack.com/services/..."
  },
  "approvals": {
    "maxAgeMs": 86400000
  },
  "telemetry": {
    "exportEndpoint": "https://your-telemetry-sink.example.com",
    "exportIntervalMs": 300000,
    "anomalyWebhookUrl": "https://alerts.example.com",
    "anomalyZScoreThreshold": 2.0,
    "otlpEndpoint": "http://collector:4318/v1/metrics",
    "otlpExportIntervalMs": 300000
  },
  "intelligence": {
    "communityEndpoint": "https://community-risk.example.com"
  },
  "rateLimit": {
    "enabled": false,
    "maxOpsPerMinute": 60
  },
  "logs": {
    "retentionDays": 30
  },
  "dashboard": {
    "apiKey": "your-secret-api-key"
  },
  "audit": {
    "signingSecret": "your-hmac-secret"
  }
}

Configuration fields

Field	Default	Description
proxy.port	4000	Proxy listen port; dashboard runs on port+1
proxy.host	127.0.0.1	Bind address for proxy, dashboard, and WS gateway. The proxy is unauthenticated — only set a routable address behind an authenticating reverse proxy. See Security model
proxy.checkpointThreshold	0.3	Minimum risk score to trigger a pre-op checkpoint
intervention.allowBelow	0.3	Risk scores below this are allowed
intervention.blockAtOrAbove	0.7	Risk scores at or above this are blocked
webhook.url	—	POST target for approval-required notifications
webhook.secret	—	HMAC-SHA256 secret. When set, every webhook POST carries X-AgentsGate-Signature: sha256=<hex> over the raw body — verify it before acting
webhook.slackUrl	—	Slack Incoming Webhook for block/approval events
approvals.maxAgeMs	86400000	Approval TTL in ms (default: 24h)
telemetry.exportEndpoint	—	HTTP endpoint for periodic telemetry export
telemetry.exportIntervalMs	300000	Export interval in ms (default: 5 min)
telemetry.anomalyWebhookUrl	—	Webhook for z-score anomaly alerts
telemetry.anomalyZScoreThreshold	2.0	Z-score threshold for anomaly firing
telemetry.otlpEndpoint	—	OpenTelemetry OTLP/HTTP metrics endpoint
telemetry.otlpExportIntervalMs	300000	OTLP export interval in ms
intelligence.communityEndpoint	—	L3 community risk enrichment endpoint
rateLimit.enabled	false	Enable per-agent rate limiting
rateLimit.maxOpsPerMinute	60	Max operations per agent per minute
logs.retentionDays	—	Days to retain operation logs before auto-pruning
dashboard.apiKey	—	X-API-Key required on all dashboard endpoints except GET /health. Unset means no authentication — required whenever the dashboard is reachable beyond loopback
audit.signingSecret	—	HMAC-SHA256 secret for operation log signing
team	—	Namespace identifier — selects the database file (data-{team}.db)

---

Architecture

Module	Responsibility
M1 MCP Proxy Core	HTTP/stdio server + pipeline orchestration
M2 State Store	SQLite persistence (WAL mode)
M3 Operation Logger	Audit trail for every intercepted event
M4 Checkpoint Engine	Pre-operation file state capture
M5 File Shadow System	Shadow git repo for file snapshots
M6 Risk Scoring Engine	L1 static rules
M7 Intervention Controller	allow / require_approval / block gate
M8 Rollback Engine	File restore from checkpoint
M9 Plugin Adapter SDK	Registry + base class for community adapters
M10 Dashboard API	REST API + SSE + Prometheus metrics
M11 Risk Intelligence	L2 Bayesian user-history + L3 community scoring
M12 Community Registry	Plugin discovery and validation
M13 Telemetry	Anonymized aggregate stats + anomaly detection

Project structure

src/
  cli.ts                  ← agentsgate CLI entry point
  index.ts                ← library exports
  config.ts               ← configuration loader
  policy.ts               ← policy engine
  types/
    interfaces.ts         ← all shared types (Architect-owned)
    errors.ts             ← typed error classes
  modules/
    m1-proxy/             ← MCP proxy + createPipeline factory
    m2-store/             ← SQLite state store
    m3-logger/            ← operation logger
    m4-checkpoint/        ← checkpoint engine
    m5-shadow/            ← file shadow system
    m6-risk/              ← risk scoring engine (L1)
    m7-intervention/      ← intervention controller
    m8-rollback/          ← rollback engine
    m9-plugin-sdk/        ← plugin adapter SDK
    m10-dashboard/        ← dashboard REST API + SSE
    m11-intelligence/     ← risk intelligence (L2/L3)
    m12-registry/         ← community adapter registry
    m13-telemetry/        ← anonymized telemetry
  utils/
    rate-limiter.ts       ← per-agent rate limiting
    circuit-breaker.ts    ← per-agent circuit breaker
    agent-quota.ts        ← per-agent daily quota
    graceful-shutdown.ts  ← signal handling + drain
    slack-notifier.ts     ← Slack webhook notifications
    claude-desktop-injector.ts ← Claude Desktop config management
    mcp-server-registry.ts ← MCP server discovery
tests/
  modules/                ← unit tests (one file per module)
  e2e/                    ← end-to-end pipeline tests

---

Development

git clone https://github.com/agentsgate/agentsgate.git
cd agentsgate
npm install
npm run build      # compile TypeScript
npm test           # run full test suite
npm run typecheck  # type-check without building

Recommended first run:

npm run bootstrap
npm run smoke:start
node dist/cli.js start

---

Contributing

Contributions are welcome. Please open an issue to discuss proposed changes before submitting a pull request.

License

MIT — see LICENSE