π¦
agent-guard-mcp
agent-guard-mcp
0 installs
Trust: 34 β Low
Other
Ask AI about agent-guard-mcp
Powered by Claude Β· Grounded in docs
I know everything about agent-guard-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Loading tools...
Reviews
Documentation
agent-guard-mcp
MCP Guard Server β Budget control, approval workflows, and audit logging for AI agents.
Works with Claude Code, Cursor, ChatGPT, and any AI agent that speaks the MCP protocol.
Features
- Budget Control β Daily credits hard limit prevents agent overspending
- High-Risk Approval β Operations exceeding amount threshold or matching sensitive resource keywords trigger human approval
- Approval Workflow β Agent requests β token generated β human approves via Dashboard or Telegram
- Audit Log β All spend, approval, and rejection actions recorded with cursor-based pagination
- Web Dashboard β Gin + HTMX + Tailwind real-time dashboard
- Telegram Notifications β Instant approval links for high-risk operations
- Multi-Transport β stdio / SSE / StreamableHTTP with automatic detection
MCP Tools
| Tool | Description |
|---|---|
check_budget | Query today's budget status |
spend | Execute a spend (auto-detects high-risk) |
request_approval | Explicitly request human approval |
approve | Approve a pending token |
reject | Reject a pending token |
check_approval | Poll approval status |
get_audit_log | Query audit log with filtering and pagination |
get_pending_approvals | List all pending approval requests |
Quick Start
Requirements
- Go 1.24+
- No CGO required (pure Go SQLite driver)
Build from Source
git clone https://github.com/dygogogo/agent-guard-mcp.git
cd agent-guard-mcp
go build -o mcp-guard main.go
Download Pre-built Binary
Download the latest release for your platform:
| Platform | amd64 | arm64 |
|---|---|---|
| macOS | darwin-amd64.zip | darwin-arm64.zip |
| Linux | linux-amd64.zip | linux-arm64.zip |
| Windows | windows-amd64.zip | windows-arm64.zip |
Or visit the latest release page.
Configuration
Configure via environment variables or .env file:
| Variable | Description | Default |
|---|---|---|
MCP_TRANSPORT | Transport: stdio / sse / http | Auto-detect (TTY β http) |
BUDGET_LIMIT | Daily budget cap (credits) | 10.0 |
HIGH_RISK_THRESHOLD | High-risk amount threshold | 2.0 |
HIGH_RISK_RESOURCES | High-risk resource keywords (comma-separated) | delete,send |
DB_PATH | SQLite database path | ./mcp-guard.db |
DASHBOARD_PORT | Dashboard HTTP port | 8080 |
APPROVAL_BASE_URL | Base URL for approval links | http://localhost:8080 |
LOG_LEVEL | Log level: debug/info/warn/error | info |
PAYER_ID | Payer identity | hostname |
TELEGRAM_BOT_TOKEN | Telegram Bot Token (optional) | - |
TELEGRAM_CHAT_ID | Telegram Chat ID (optional) | - |
Running
# HTTP mode (auto-detected, with Dashboard)
./mcp-guard
# Dashboard: http://localhost:8080/dashboard
# MCP endpoint: http://localhost:8080/mcp
# stdio mode (for MCP clients)
MCP_TRANSPORT=stdio ./mcp-guard
# SSE mode
MCP_TRANSPORT=sse ./mcp-guard
# SSE endpoint: http://localhost:8080/sse
Claude Code Integration
Add to Claude Code's MCP configuration:
{
"mcpServers": {
"agent-guard-mcp": {
"command": "mcp-guard",
"env": {
"MCP_TRANSPORT": "stdio",
"BUDGET_LIMIT": "10"
}
}
}
}
Architecture
βββββββββββββββ MCP Protocol ββββββββββββββββββ
β AI Agent β ββββββββββββββββββββΊ β MCP Guard β
β (Claude, β stdio / HTTP β Server β
β Cursor...) β β β
βββββββββββββββ β ββββββββββββββ β
β β BudgetStore β β
βββββββββββββββ HTTP β β (SQLite) β β
β Dashboard β ββββββββββββββββββββΊ β ββββββββββββββ β
β (Gin+HTMX) β ββββββββββββββββββ
βββββββββββββββ
βββββββββββββββ Webhook
β Telegram β βββββββ Approval notifications
βββββββββββββββ
Core Files
| File | Description |
|---|---|
main.go | Entry point, transport selection, graceful shutdown |
server.go | MCP Server with 8 registered tools |
store.go | BudgetStore interface + SQLite implementation |
approval.go | High-risk detection, approval workflow, Telegram |
config.go | Environment config, auto transport detection |
logger.go | zap logging (stdio mode: file only) |
dashboard.go | Gin Web Dashboard |
Approval Workflow
1. Agent calls spend(amount=5.0, resource="/api/delete")
2. MCP Guard detects high-risk (amount > threshold OR resource keyword matched)
3. Returns {status: "pending_approval", token: "xxx"}
4. Agent polls check_approval(token) for status
5. Human approves/rejects via Dashboard or Telegram
6. Agent receives final result (approved/rejected/budget_exceeded)
Testing
# All tests with race detection
go test -race -count=1 ./...
# Integration tests only
go test -race -run TestIntegration -v ./...
# Coverage
go test -race -cover ./...
Tech Stack
- Go 1.24 β Language
- mcp-go β MCP protocol Go SDK
- Gin β Web framework (Dashboard)
- modernc.org/sqlite β Pure Go SQLite (no CGO)
- zap β Structured logging
- HTMX + Tailwind CSS β Dashboard frontend
License
MIT
