mcpguard-adk
Exports OpenTelemetry audit and tool-trajectory traces to Google Cloud Trace via OTLP, enabling cloud observability of MCPGuard scans.
Provides OpenTelemetry OTLP v1/traces instrumentation and export for audit events and tool trajectories.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
MCPGuard-ADK
Open-source multi-agent Model Context Protocol (MCP) supply-chain, secret-leak, >200K token cost-cliff, and tool-trajectory auditor engineered on Google Agent Development Kit (ADK) 2.0, Agent2Agent (A2A) Protocol v1.0, and OpenTelemetry.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▄████▄ ███╗ ███╗ ██████╗██████╗ ██████╗ ██╗ ██╗ █████╗ ██████╗ ██████╗
██╔═══╝ ████╗ ████║██╔════╝██╔══██╗██╔════╝ ██║ ██║██╔══██╗██╔══██╗██╔══██╗
██║ ███╗ ██╔████╔██║██║ ██████╔╝██║ ███╗██║ ██║███████║██████╔╝██║ ██║
██║ ██║ ██║╚██╔╝██║██║ ██╔═══╝ ██║ ██║██║ ██║██╔══██║██╔══██╗██║ ██║
╚██████╔╝ ██║ ╚═╝ ██║╚██████╗██║ ╚██████╔╝╚██████╔╝██║ ██║██║ ██║██████╔╝
✦ ADK 2 ╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═════╝
Google ADK 2.0 Hybrid Graph • A2A v1.0 Ed25519/JCS • Gemini FinOps • Cloud Trace OTLP v0.3.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
╭─ ✦ 0-TOK AST ──────╮ ╭─ ◆ RISK ALERTS ────╮ ╭─ ● FINOPS SAVED ───╮ ╭─ ▸ A2A v1.0 JWS ───╮
│ 1053/1069 Clean │ │ 23 Findings │ │ -95.4% Spend │ │ Ed25519 OK │
│ $0.00 (0 Tokens) │ │ 11 Crit • 11 High │ │ $52.15 vs $1,144 │ │ ID 853af5cf368 │
╰────────────────────╯ ╰────────────────────╯ ╰────────────────────╯ ╰────────────────────╯
╭── ◆ Security & >200K Cost-Cliff Alerts (Auto-Redacted Pinpoint View) ───── ACTION REQUIRED ──╮
│ 4. CRITICAL MCPG-SEC-003 ▸ vulnerable_mcp_config.json:11:41 │
│ WHAT LEAKED : GitHub Personal Access Token: GITHUB_PERSONAL_ACCESS_TOKEN = ghp_1234•••• │
│ WHERE (FILE): examples/vulnerable_mcp_config.json (Line 11, Col 41) │
│ ┌── Source Pinpoint ────────────────────────────────────────────────────────────────── │
│ │ 10 │ "env": { │
│ │ 11 │ "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_1234••••••••••••••••••••••••••••1 │
│ │ │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ │
│ │ 12 │ }, │
│ └───────────────────────────────────────────────────────────────────────────────────── │
│ ✔ FIX: Replace literal value with `${GITHUB_PERSONAL_ACCESS_TOKEN}` and load from `.env` │
╰──────────────────────────────────────────────────────────────────────────────────────────────╯
╭── ✦ Google Cloud & ADK 2.0 Verification Scorecard (5/5) ─────────────────── 100% VERIFIED ─╮
│ ✔ [VERIFIED] ADK 2.0 Hybrid Graph │ Skipped 1053 clean files locally at $0.00 (0 tokens) │
│ ✔ [VERIFIED] Zero Context Bloat │ Sync McpToolset isolated in AgentTool (read-only) │
│ ✔ [VERIFIED] A2A v1.0 Ed25519 + JCS │ RFC 8037 EdDSA verified over RFC 8785 JCS AgentCard │
│ ✔ [VERIFIED] Cloud Trace OTLP SDK │ EVENT_ONLY active; W3C resourceSpans exported │
│ ✔ [VERIFIED] MCP Stdio & SARIF Gate │ JSON-RPC 2.0 serve-mcp + SARIF v2.1.0 + .test.json │
╰──────────────────────────────────────────────────────────────────────────────────────────────╯30-Second Quickstart ($0 Offline Scan — No API Key Required)
Run on Python 3.11+ against any local repository, monorepo, or the included deliberately vulnerable ./examples suite:
git clone https://github.com/Chitresh-Bhatia-264/MCPGuard-ADK.git
cd MCPGuard-ADK
pip install -e ".[dev]"
# 1. Run full scan + Live Voice Barge-In debrief on sample vulnerabilities
python -m mcpguard_adk.cli scan ./examples --live
# 2. Scan your own polyglot workspace (Python ADK + MCP + React/TS + .env)
python -m mcpguard_adk.cli scan /path/to/your/workspace
# 3. Launch the interactive Gemini CLI / Claude Code style slash-command shell
python -m mcpguard_adk.cli shellRelated MCP server: Grey Panda
Why MCPGuard-ADK?
Enterprise AI agent deployments hit two walls before production:
Security / AppSec: Over-broad MCP servers (
"/"host mounts, unpinnednpx -yexecution, plaintext API keys inmcp.jsonor.env, prompt-injection payloads in tool metadata, and client-side XSS sinks).FinOps / Token Cost Cliffs: Connecting
McpToolsetdirectly to a root orchestrator dumps 20+ tool schemas and raw file reads into global context—pushing uncompacted loops across Gemini 3.1 Pro's 200,000-token pricing cliff ($2.00$\rightarrow$$4.00/1M input,$12.00$\rightarrow$$18.00/1M output).
MCPGuard-ADK solves both in a single CI/CD gate using a 6-stage Google ADK 2.0 Hybrid Graph:
flowchart TD
A["Stage 1: Polyglot AST, TOML, .env & Manifest Pre-Filter<br/>(Deterministic Code Node • 0 LLM Tokens • <200ms / 1K files)"] -->|Clean / Unchanged| Z["Short-Circuit ($0.00)"]
A -->|Anomalies Detected| B["Stage 2: Diff & Risk Triage Router<br/>(Gemini 3.1 Flash-Lite • $0.25/$1.50 per 1M)"]
B -->|SECURITY| C["Stage 3: Security & MCP Auditor<br/>(AgentTool + Sync McpToolset [RO] • Gemini 3.8 Flash / 3.1 Pro)"]
B -->|COST_CLIFF / TRAJECTORY_DRIFT| D["Stage 4: Cost & Trajectory Optimizer<br/>(AgentTool Isolated Context • Gemini 3.8 Flash)"]
C --> E["Stage 5: HITL Gate & Hardened Patch Emitter<br/>(Workspace-Relative difflib Patch + SARIF v2.1.0 + .test.json)"]
D --> E
E -.->|--live flag| F["Stage 6: Live Voice Incident Debrief<br/>(runner.run_live() + LiveRequestQueue Mid-Sentence Barge-In)"]Built-In Detection Rules (Stage 1 Zero-Token Engine)
Rule ID | Severity | Target Files | Vulnerability / Anti-Pattern Detected |
|
|
| Over-broad host filesystem scope ( |
|
|
| Unpinned |
|
|
| Leaked credentials ( |
|
|
| Indirect prompt-injection payloads in MCP metadata & unescaped |
|
|
| Missing read-only |
|
|
| Asynchronous runtime initialization of |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Uncompacted |
|
|
| Wildcard ( |
Late-2026 Gemini Rate-Card & Cost-Cliff Benchmark
Architecture Pattern | Assumed Workload per PR Audit | Published Rate Card Applied (per 1M Tokens) | Transparent Per-PR Math | Cost per 1,000 PR Audits |
Naive Single-Agent Loop (>200K Cliff) | Uncompacted context reaches 250K in, 8K out on Gemini 3.1 Pro Preview |
|
|
|
Naive Single-Agent Loop (<=200K) | Compaction holds context at 120K in, 8K out on Gemini 3.1 Pro Preview |
|
|
|
MCPGuard-ADK Tiered Hybrid (2026 Promo) | Stage 1 skips clean files (0 tokens); 3.1 Flash-Lite triage (40K in / 2K out); 3.8 Flash audit (25K in / 4K out); 3.1 Pro escalation on 10% of PRs | 3.1 Flash-Lite: |
|
|
MCPGuard-ADK Async Batch (2027 Post-Promo) | Overnight Batch API (50% off Standard; 3.8 Flash at | Batch: 3.1 Flash-Lite |
|
|
Reproduce these calculations via CLI:
python -m mcpguard_adk.cli cost-sim --prs 1000IDE Integration (MCP Stdio Server) & A2A Protocol v1.0
1. Mount Inside Cursor, Claude Desktop, VS Code, or Gemini CLI (mcp.json)
{
"mcpServers": {
"mcpguard-adk": {
"command": "python",
"args": ["-m", "mcpguard_adk.cli", "serve-mcp"]
}
}
}Exposes mcpguard_audit_repository, mcpguard_simulate_cost_cliff, and mcpguard_verify_agent_card over JSON-RPC 2.0 stdio (supporting both newline-delimited and Content-Length framing).
2. Cross-Framework A2A Protocol v1.0 Server (Ed25519 + RFC 8785 JCS)
# Start HTTP+JSON and Server-Sent Events (SSE) A2A v1.0 endpoint
python -m mcpguard_adk.cli serve-a2a --host 127.0.0.1 --port 8080
# Inspect & cryptographically verify the EdDSA-signed AgentCard + RFC 8037 OKP JWKS
python -m mcpguard_adk.cli agent-card --jwksPublishes
GET /.well-known/agent-card.jsonsigned with asymmetric Ed25519 (EdDSA, RFC 8037) over RFC 8785 JSON Canonicalization Scheme (JCS) and public keys atGET /.well-known/jwks.json.Streams
TaskStatusUpdateEventand chunkedTaskArtifactUpdateEvent(append&lastChunk) using unified A2A v1.0Partmemberoneofpayloads.Protects
TaskPushNotificationConfigwebhooks against private-IP/cloud-metadata SSRF (169.254.169.254,metadata.google.internal) and JWTjtireplay attacks.
CLI Command Reference & CI/CD Gating
# Interactive slash-command shell (/scan, /react, /voice, /patch, /a2a, /quit)
python -m mcpguard_adk.cli shell
# Full scan + approve Stage 5 HITL gate + emit SARIF v2.1.0 + export W3C OTLP traces
python -m mcpguard_adk.cli scan ./examples --live --approve-patches \
--emit-sarif reports/mcpguard.sarif.json \
--export-otel reports/otel_traces.json
# Pull-Request CI Gate (scan only git-modified files; exit code 2 on CRITICAL/HIGH)
python -m mcpguard_adk.cli scan . --git-diff --fail-on high
# Launch interactive browser visualizer (ADK 2.0 Graph + >200K Cliff Sliders)
python -m mcpguard_adk.cli ui ./examples
# Run the 17-test verification suite (AST, FinOps, Ed25519 tamper detection, MCP stdio, OTel)
python -m pytest tests -vRepository Structure
MCPGuard-ADK/
├── mcpguard_adk/
│ ├── agent.py # ADK 2.0 Hybrid Graph, sync McpToolset, AgentTool & native ADK bridge
│ ├── cli.py # CLI entrypoints (scan, shell, serve-mcp, serve-a2a, ui, agent-card, cost-sim)
│ ├── cost_engine.py # Late-2026 Gemini rate-card, >200K Pro cliff & cache storage ROI math
│ ├── llm_client.py # Official google-genai SDK client with 0-cost offline fallback
│ ├── mcp_server.py # Spec-compliant JSON-RPC 2.0 MCP stdio server
│ ├── sarif.py # SARIF v2.1.0 exporter for GitHub Advanced Security
│ ├── tui.py # 24-bit TrueColor terminal dashboard, secret redaction & REPL shell
│ ├── web_studio.py # Interactive browser graph & FinOps studio
│ ├── a2a/ # A2A v1.0 Ed25519/JCS signer, JWKS verifier, SSE & SSRF/jti guards
│ ├── agents/ # Security auditor, FinOps optimizer & Live Voice barge-in debrief
│ ├── nodes/ # Stage 1 AST/TOML/.env pre-filter, Stage 2 router & Stage 5 difflib patcher
│ └── telemetry/ # Official OpenTelemetry SDK W3C tracer & OTLP/JSON exporter (EVENT_ONLY)
├── examples/ # Deliberately vulnerable MCP config & uncompacted Pro loop for testing
├── evals/ # ADK .test.json and multi-turn .evalset.json conformance suites
├── tests/ # 17 automated pytest suites
├── Dockerfile # Production container for Google Cloud Run
└── cloudbuild.yaml # Automated Google Cloud Build CI/CD pipelineLicense & Contributing
License: Apache License 2.0
Contributing & Good First Issues:
CONTRIBUTING.md•.github/ISSUE_TEMPLATE/good_first_issue.mdAI Code Editor Index:
llms.txt
If MCPGuard-ADK caught a misconfiguration or saved token spend, a star helps others discover it.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
LLM cost optimization gateway, repo token-waste auditor & model arbitrage MCP server.
Zero-install security baseline for AI coding agents — OWASP/CWE-cited rules over MCP.
Zero-secret MCP gateway for AI agents: risk-scored, audited calls with human-in-the-loop approval.
Lets coding agents check their own code for leaked secrets, risky dependencies and AI-code mistakes
Related MCP Servers
- AlicenseCqualityBmaintenanceLocal-first MCP runtime for coding agents with bounded workspace access, content-preconditioned writes, AST search, LSP navigation and diagnostics, and Git status/diff. Designed to give coding agents useful repository access without treating unrestricted shell access as the default integration boundary.133MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI coding assistants to scan, review, and explain AI, agent, and MCP security issues, run AISVS verification, and access OWASP-anchored standards controls from the IDE via stdio.1Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables local LLM tools and agentic IDEs to inspect repository token maps, retrieve clean token-bounded codebase snapshots, and audit code for hardcoded secrets via MCP over stdio.19 npm4MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to audit git diffs, scan for leaked secrets and unsafe APIs, detect breaking changes, triage issues, generate changelogs, and assess repository hygiene through native stdio JSON-RPC tools.7Apache 2.0