agent-guard-mcp

License: MIT Go Reference

MCP 가드 서버 — AI 에이전트를 위한 예산 관리, 승인 워크플로우 및 감사 로깅 기능을 제공합니다.

Claude Code, Cursor, ChatGPT 및 MCP 프로토콜을 지원하는 모든 AI 에이전트와 함께 사용할 수 있습니다.

주요 기능

예산 관리 — 일일 크레딧 한도 설정을 통해 에이전트의 과도한 지출을 방지합니다.
고위험 승인 — 설정된 금액 임계값을 초과하거나 민감한 리소스 키워드와 일치하는 작업 시 사람의 승인을 요구합니다.
승인 워크플로우 — 에이전트 요청 → 토큰 생성 → 대시보드 또는 텔레그램을 통한 사람의 승인 절차를 거칩니다.
감사 로그 — 모든 지출, 승인 및 거부 작업이 커서 기반 페이지네이션과 함께 기록됩니다.
웹 대시보드 — Gin + HTMX + Tailwind 기반의 실시간 대시보드.
텔레그램 알림 — 고위험 작업에 대한 즉각적인 승인 링크 전송.
멀티 전송 — stdio / SSE / StreamableHTTP 자동 감지 지원.

MCP 도구

도구	설명
`check_budget`	오늘의 예산 상태 조회
`spend`	지출 실행 (고위험 자동 감지)
`request_approval`	사람의 승인 명시적 요청
`approve`	대기 중인 토큰 승인
`reject`	대기 중인 토큰 거부
`check_approval`	승인 상태 폴링
`get_audit_log`	필터링 및 페이지네이션을 통한 감사 로그 조회
`get_pending_approvals`	대기 중인 모든 승인 요청 목록 조회

빠른 시작

요구 사항

Go 1.24 이상
CGO 불필요 (순수 Go SQLite 드라이버 사용)

소스에서 빌드

git clone https://github.com/dygogogo/agent-guard-mcp.git
cd agent-guard-mcp
go build -o mcp-guard main.go

사전 빌드된 바이너리 다운로드

사용 중인 플랫폼에 맞는 최신 릴리스를 다운로드하세요:

플랫폼	amd64	arm64
macOS	darwin-amd64.zip	darwin-arm64.zip
Linux	linux-amd64.zip	linux-arm64.zip
Windows	windows-amd64.zip	windows-arm64.zip

또는 최신 릴리스 페이지를 방문하세요.

설정

환경 변수 또는 .env 파일을 통해 설정합니다:

변수	설명	기본값
`MCP_TRANSPORT`	전송 방식: stdio / sse / http	자동 감지 (TTY → http)
`BUDGET_LIMIT`	일일 예산 한도 (크레딧)	10.0
`HIGH_RISK_THRESHOLD`	고위험 금액 임계값	2.0
`HIGH_RISK_RESOURCES`	고위험 리소스 키워드 (쉼표로 구분)	delete,send
`DB_PATH`	SQLite 데이터베이스 경로	./mcp-guard.db
`DASHBOARD_PORT`	대시보드 HTTP 포트	8080
`APPROVAL_BASE_URL`	승인 링크용 기본 URL	http://localhost:8080
`LOG_LEVEL`	로그 레벨: debug/info/warn/error	info
`PAYER_ID`	결제자 식별자	hostname
`TELEGRAM_BOT_TOKEN`	텔레그램 봇 토큰 (선택 사항)	-
`TELEGRAM_CHAT_ID`	텔레그램 채팅 ID (선택 사항)	-

실행

# 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 통합

Claude Code의 MCP 설정에 추가하세요:

{
  "mcpServers": {
    "agent-guard-mcp": {
      "command": "mcp-guard",
      "env": {
        "MCP_TRANSPORT": "stdio",
        "BUDGET_LIMIT": "10"
      }
    }
  }
}

아키텍처

┌─────────────┐     MCP Protocol     ┌────────────────┐
│  AI Agent   │ ◄──────────────────► │  MCP Guard      │
│ (Claude,    │   stdio / HTTP       │  Server         │
│  Cursor...) │                      │                  │
└─────────────┘                      │  ┌────────────┐ │
                                     │  │  BudgetStore │ │
┌─────────────┐    HTTP              │  │  (SQLite)    │ │
│  Dashboard  │ ◄──────────────────► │  └────────────┘ │
│  (Gin+HTMX) │                      └────────────────┘
└─────────────┘

┌─────────────┐    Webhook
│  Telegram   │ ◄────── Approval notifications
└─────────────┘

핵심 파일

파일	설명
`main.go`	진입점, 전송 방식 선택, 정상 종료 처리
`server.go`	8개의 도구가 등록된 MCP 서버
`store.go`	BudgetStore 인터페이스 + SQLite 구현
`approval.go`	고위험 감지, 승인 워크플로우, 텔레그램 연동
`config.go`	환경 설정, 자동 전송 방식 감지
`logger.go`	zap 로깅 (stdio 모드: 파일 전용)
`dashboard.go`	Gin 웹 대시보드

승인 워크플로우

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)

테스트

# All tests with race detection
go test -race -count=1 ./...

# Integration tests only
go test -race -run TestIntegration -v ./...

# Coverage
go test -race -cover ./...

기술 스택

Go 1.24 — 언어
mcp-go — MCP 프로토콜 Go SDK
Gin — 웹 프레임워크 (대시보드)
modernc.org/sqlite — 순수 Go SQLite (CGO 없음)
zap — 구조화된 로깅
HTMX + Tailwind CSS — 대시보드 프론트엔드

라이선스

MIT

中文

agent-guard-mcp

agent-guard-mcp

주요 기능

MCP 도구

빠른 시작

요구 사항

소스에서 빌드

사전 빌드된 바이너리 다운로드

설정

실행

Claude Code 통합

아키텍처

핵심 파일

승인 워크플로우

테스트

기술 스택

라이선스

Resources

Latest Blog Posts

MCP directory API