@mastyf_ai/cli
Advanced tools
Runtime security, cost governance, and health monitoring proxy for MCP infrastructure.
MCP Mastyf AI sits between AI agents and MCP servers, enforcing active security policies, tracking real token costs, monitoring server health, and providing enterprise observability — all through a YAML-configurable engine with hot-reload.
It works as a transparent proxy, a standalone CLI, an MCP server (so agents can self-audit), and a pnpm monorepo — install only what you need.
# Install globally
npm install -g @mastyf_ai/server
# Scan your MCP servers for CVEs, secrets, and injection attacks
mastyf-ai scan --all
# Proxy with active policy enforcement
mastyf-ai proxy --policy ./default-policy.yaml --blocking-mode block
# Generate a full security-cost-health report
mastyf-ai report --all --format markdown --output mastyf-ai-report.md
# Run as an MCP server (AI agents can self-audit)
mastyf-ai # stdio transport, auto-starts MCP server
.env files, docker-compose.yml, and environment variablesalg: none confusion attacks), audience/issuer validation, agent identity extractiontools/call traffic and counts tokens via tiktoken (o200k_base for OpenAI, char-ratio estimates for Anthropic/Google/DeepSeek/Meta/Mistral)/healthz and /readyz endpoints — Liveness and readiness probes for K8s deploymentpackages/core (detection engine), packages/cli, packages/server (MCP server), plus root src/ (proxy, scanners, services, policy, auth)IHistoryDb, ISecurityScanner, ICostAuditor, IHealthMonitor, IPolicyEngine for testability and swappable implementationsMASTYF_AI_STRICT_MODE=true refuses startupgh-pages on tagged releasesnpm audit, CycloneDX SBOM generation, npm provenance attestationvitest.config.ts)mastyf-ai audit --all queries proxy databases for real token counts and estimates costs per modelscripts/full-cost-report.cjs reads Cline model config from ~/.cline/data/globalState.json, auto-detects pricing, queries proxy DBs for precise MCP tool call costs, and computes LLM conversation cost estimatesMASTYF_AI_DB_PATH env var allows running multiple proxy instances (e.g., github + filesystem) with separate databases, preventing lock conflictstools/call through the proxy is logged with request/response tokens, duration, and estimated costHistoryDatabase constructor now checks MASTYF_AI_DB_PATH env var as fallback, enabling multiple concurrent proxy instances without lock conflictscreateContainer() respects MASTYF_AI_DB_PATH for all CLI commands (scan, audit, health, report, proxy)/tmp symlink — Launch scripts use /private/tmp to avoid proper-lockfile stat errors on macOS# Global CLI
npm install -g @mastyf_ai/server
# As an MCP server (for AI assistant integration)
npx @mastyf_ai/server
# From source (monorepo)
git clone https://github.com/mastyf-ai/mastyf-ai.git
cd mastyf-ai
pnpm install
pnpm build
pnpm start
mastyf-ai scanmastyf-ai scan --all # Scan all discoverable MCP configs
mastyf-ai scan --config ./mcp.json # Scan a specific config
mastyf-ai scan --fail-on-critical # Exit 1 if any CRITICAL CVE found
mastyf-ai scan --fail-on-secrets # Exit 1 if any hardcoded secret found
mastyf-ai scan --threshold-score 60 # Exit 2 if any server scores below 60
Outputs per-server CVE list, auth status, typo-squat risk, secrets found, and composite security score (0–100).
mastyf-ai auditmastyf-ai audit --all # Audit costs for all servers
mastyf-ai audit --server github # Filter to a specific server
mastyf-ai audit --threshold-cost 0.01 # Exit 2 if total cost exceeds $0.01
Outputs per-server token usage, estimated cost (USD), and tool-level breakdown.
mastyf-ai healthmastyf-ai health --all # Health-check all servers
mastyf-ai health --fail-on-overload # Exit 1 if any server has tool overload
mastyf-ai health --threshold-latency 1000 # Exit 2 if latency exceeds 1000ms
Outputs per-server latency, success rate, tool count, and overload warnings.
mastyf-ai reportmastyf-ai report --all # Full security-cost-health report
mastyf-ai report --format markdown # Output as markdown
mastyf-ai report --format json # Output as JSON
mastyf-ai report --output mastyf-ai-report.md # Write to file
mastyf-ai report --threshold-score 75 # Exit 2 if overall score below 75
Generates a comprehensive report with overall score (weighted: security 40%, health 30%, cost efficiency 30%).
mastyf-ai proxymastyf-ai proxy --config ./mcp.json --policy ./default-policy.yaml --blocking-mode block
mastyf-ai proxy --policy ./policy.yaml --dry-run # Simulate without activating
mastyf-ai proxy --auth-issuer https://accounts.google.com --auth-audience my-app
mastyf-ai proxy --auth-required # Fail-closed auth
Starts the transparent proxy. Policy modes: audit (passive), warn (flag only), block (active enforcement). With --dry-run, evaluates policy against historical call records without activating the proxy.
Policies are YAML files evaluated against every tools/call in real time. The pipeline normalizes payloads (decoding hex/unicode/URL/HTML entity obfuscation), performs semantic shell analysis, then evaluates rules in order.
# default-policy.yaml
version: '1.0'
policy:
mode: block
default_action: block # fail-closed — blocks anything not explicitly allowed
rules:
- name: block-shell-injection
action: block
patterns:
- curl\s|wget\s
- rm\s+-rf
- ;\s*\w
- '&&|\|\|'
- \$\{
- '`[^`]+`'
- /etc/passwd|/etc/shadow
- name: deny-dangerous-tools
action: block
tools:
deny:
- execute_command
- bash
- sh
- eval
- exec
- system
- spawn
- fork
- popen
- source
- name: rate-limit-tool-calls
action: flag
maxCallsPerMinute: 120
- name: token-budget
action: flag
maxTokens: 50000
Hot-reload: Edit the YAML file — the policy engine swaps atomically without restarting the proxy.
RBAC example:
- name: admin-only-tool
action: block
tools:
deny: [dangerous_operation]
rbac:
scopes: [admin]
clientIds: [^trusted-agent-]
MCP Mastyf AI runs as a first-class MCP server, exposing security tools to AI assistants:
{
"mcpServers": {
"mastyf-ai": {
"command": "npx",
"args": ["@mastyf_ai/server"]
}
}
}
Available tools:
scan_security — CVE, auth, typo-squat, and secret scanningaudit_costs — Token usage and cost estimationcheck_health — Latency, success rate, and tool countfull_report — Complete security-cost-health report (JSON/markdown/text)Available resources:
mastyf-ai://latest-scan — Most recent security scan resultsAvailable prompts:
audit-config — Generates audit instructions for an MCP config| Layer | What it catches |
|---|---|
| Payload normalization | Hex escaping, Unicode escapes, URL encoding, HTML entities, shell obfuscation |
| Regex triage | Cross-tool chaining, privilege escalation, exfiltration URLs, stealth directives, Unicode obfuscation (38 patterns, 8 categories) |
| Schema analysis | Injection in parameter defaults, suspicious parameter names, enum injection |
| Shell AST | Command substitution, pipe chains, redirects, logical chains, 33 dangerous commands, Unicode homoglyphs |
| LLM semantic | Context-aware verdict on tool descriptions — catches adversarial intent regex can't see |
| Secret patterns + entropy | 50+ named patterns + Shannon entropy for base64/hex secrets |
| Policy engine | Tool denylists, regex patterns, rate limits, token budgets, RBAC, default-deny |
| Response inspection | Prompt injection in tool RESPONSES, data exfiltration URLs, base64-encoded payloads |
helm repo add mastyf-ai https://mastyf-ai.github.io/mastyf-ai
helm install mastyf-ai mastyf-ai/mastyf-ai \
--set persistence.enabled=true \
--set metrics.enabled=true \
--set secrets.mode=external \
--set secrets.existingSecret=mastyf-ai-secrets
The Helm chart includes:
/healthz, /readyz on port 9090)docker run -v $(pwd)/mcp.json:/etc/mastyf-ai/config.json \
-v $(pwd)/policy.yaml:/etc/mastyf-ai/policy.yaml \
ghcr.io/mastyf-ai/mastyf-ai:latest \
proxy --config /etc/mastyf-ai/config.json --policy /etc/mastyf-ai/policy.yaml
| Variable | Default | Description |
|---|---|---|
MASTYF_AI_DB_PATH | ~/.mastyf-ai/history.db | SQLite database path |
MASTYF_AI_SECRET_ALLOWLIST | — | Comma-separated safe high-entropy strings |
MASTYF_AI_MAX_PAYLOAD_BYTES | 10485760 (10 MB) | Max JSON-RPC payload size |
MASTYF_AI_SECRET_PROVIDER | env | Secret backend: env, hashicorp-vault, aws-secrets-manager |
MASTYF_AI_ALLOW_MODE_OVERRIDE | false | Allow CLI --blocking-mode to override policy file mode |
MASTYF_AI_STRICT_MODE | false | Exit on Redis-not-configured in multi-replica/K8s |
METRICS_ENABLED | false | Expose Prometheus metrics |
METRICS_PORT | 9090 | Prometheus metrics port |
DASHBOARD_ENABLED | false | Enable web dashboard |
DASHBOARD_PORT | 4000 | Dashboard port |
DASHBOARD_METRICS_PUBLIC | false | Allow unauthenticated metrics access |
REDIS_URL | — | Redis connection for HA rate limiting and sessions |
ALERT_WEBHOOK_URL | — | Slack or Discord webhook for critical alerts |
ALERT_MIN_SEVERITY | warning | Minimum severity for webhook alerts |
ANTHROPIC_API_KEY | — | API key for LLM semantic analysis layer |
NVD_API_KEY | — | NIST NVD API key for CVE lookups |
MCP_PRICING_MODEL | gpt-4o | Default model for cost estimation |
┌──────────────────────────┐
│ MCP Mastyf AI Proxy │
│ ┌────────────────────┐ │
AI Client ──JSON-RPC→│ Policy Engine │──→ Upstream MCP Server
│ │ (audit/warn/block) │ │ │
│ └────────┬───────────┘ │ │
│ │ │ │
│ ┌────────▼───────────┐ │ │
│ │ HistoryDatabase │ │ │
│ │ (better-sqlite3 │ │ │
│ │ WAL + lockfile) │ │ │
│ └────────────────────┘ │ │
└──────────────────────────┘ │
│
┌─────────────────────────────────────────┘
│
┌─────────▼──────────┐ ┌──────────────┐ ┌──────────┐
│ Security Scanner │ │ Cost Auditor │ │ Health │
│ • CVE (OSV+NVD) │ │ • tiktoken │ │ Monitor │
│ • Auth probing │ │ • litellm │ │ • JSON- │
│ • Typo-squat │ │ • per-model │ │ RPC │
│ • Secret (50+ │ │ pricing │ │ probe │
│ + entropy) │ │ │ │ • latency│
│ • Command AST │ └──────────────┘ └──────────┘
│ • Response inspect │
└────────────────────┘
tools/call JSON-RPC to proxy/metrics# Clone and install
git clone https://github.com/mastyf-ai/mastyf-ai.git
cd mastyf-ai
pnpm install
# Build all packages
pnpm build
# Run tests
pnpm test
# Run tests with coverage
pnpm test:coverage
# Type-check
pnpm typecheck
# Run specific test suites
cd packages/core && npx vitest run
cd packages/server && npx vitest run
cd packages/cli && npx vitest run
# Run corpus evaluation
pnpm eval
# Development mode (hot-reload)
pnpm dev
A WAF inspects HTTP traffic patterns; MCP Mastyf AI operates at the MCP protocol layer — it understands tools/call semantics, tool names, argument schemas, and agent identities. It can block execute_command calls while allowing read_file, enforce per-tool rate limits, and validate JWT claims with algorithm pinning. It also scans MCP servers for CVEs, secrets, and typo-squatting — things a WAF cannot do.
Typically 5–25ms for policy evaluation (regex + schema + semantic shell analysis). JWT validation adds another 5–15ms. The total proxy overhead is under 50ms for most calls. If LLM semantic analysis is enabled, that adds 200–800ms per tool definition scan (not per call — it runs once during manifest verification, not on every intercepted request).
Yes. Set the policy mode to audit:
policy:
mode: audit
This logs every decision without blocking or flagging. Use it to understand what your agents are calling before enforcing rules. You can also run mastyf-ai proxy --policy ./policy.yaml --dry-run to simulate blocking against historical call records.
The proxy does not pass traffic through if the engine is unavailable — it returns a JSON-RPC error to the client. This is intentional fail-safe behavior. The policy engine is a synchronous, in-process evaluator (no network calls for regex/schema rules), so crashes are extremely unlikely. The LLM semantic layer gracefully degrades to an info-level "skipped" result if the API is unreachable.
Yes, with caveats. The proxy works single-instance or multi-replica, but rate limiting and session state require Redis (REDIS_URL) in multi-replica mode. Without Redis, rate limits are per-pod and session tokens from pod A are invalid on pod B. Set MASTYF_AI_STRICT_MODE=true to refuse startup if Redis is missing in a multi-replica/K8s environment. For the audit database, use separate DB paths (MASTYF_AI_DB_PATH) per instance, or migrate to PostgreSQL (planned for v2.4).
Only if you configure ANTHROPIC_API_KEY. The semantic scanner sends tool definitions (name + description + inputSchema) to Claude for security analysis — never the actual tool call arguments or response content. Tool definitions are metadata, not user data. You can disable the semantic layer entirely with --skip-semantic or by not setting the API key.
Add them to the MASTYF_AI_SECRET_ALLOWLIST environment variable (comma-separated) to suppress false positives. For custom detection patterns, you can extend src/scanners/secret-scanner.ts and rebuild. The entropy threshold (4.5 bits per character) is also configurable in source.
Yes. The @mastyf_ai/core package exports the detection engine directly:
import { scanServer, fetchToolsFromStdio } from '@mastyf_ai/core';
const tools = await fetchToolsFromStdio({ command: 'npx', args: ['@my-mcp-server'] });
const result = await scanServer('my-server', tools, 'stdio');
// result.status: 'clean' | 'warning' | 'critical'
// result.tools: per-tool scan results with issues
The root package (@mastyf_ai/server) exports the full CLI, proxy, and MCP server.
The default-policy.yaml shipped with the package blocks shell injection patterns (curl, wget, rm -rf, command chaining, /etc/passwd), explicitly denies dangerous tools (execute_command, bash, sh, eval, exec, etc.), rate-limits at 120 calls/min, flags tokens over 50K, and applies default_action: block — meaning anything not explicitly allowed is blocked. You can override this with your own policy file.
The TypeScript codebase is platform-agnostic, but the stdio proxy spawns child processes and uses Unix signal handling. Windows support via WSL2 is fully functional. Native Windows cmd.exe / PowerShell is experimentally supported but not the primary target. The HTTP/SSE proxy transport works on any platform.
Set ALERT_WEBHOOK_URL to a Slack or Discord webhook URL, and optionally ALERT_MIN_SEVERITY (default: warning). The alerter fires on policy blocks, circuit breaker state changes, and cost threshold breaches. Messages include server name, rule triggered, and timestamp.
~/.mastyf-ai/history.db by default. Override with MASTYF_AI_DB_PATH. The database uses SQLite with WAL mode, advisory file locking, and automatic purging of records older than 30 days. For tests, pass ':memory:' to use an in-memory database.
Use dry-run mode:
mastyf-ai proxy --policy ./new-policy.yaml --dry-run
This evaluates the policy against every call record in your history database and prints a per-server block/pass breakdown without activating the proxy. If the block rate is unexpectedly high or low, adjust rules before deploying.
The proxy validates JWT bearer tokens in the Authorization header of tools/call requests. However, AI clients like Cline and Claude Desktop don't natively generate OAuth tokens. You have three options:
env.AUTH_TOKEN in your MCP server config. The proxy passes it as a Bearer token to upstream servers and validates it if --auth-required is set.AUTH_TOKEN. Rotate it manually or via vault.RBAC scopes are defined in your policy YAML under rules[].rbac.scopes and mapped to JWT claims (the scope or scopes claim in the token). DPoP (RFC 9449) requires the client to sign a proof-of-possession JWT per request — this is functional in code but not yet supported by any mainstream AI client.
For OpenAI models (GPT-4o, o1, o3), counting uses tiktoken with o200k_base encoding — these are exact (±1%). For other providers:
| Provider | Method | Typical accuracy |
|---|---|---|
| Anthropic (Claude) | Char ratio (0.30) | ±5–15% |
| Google (Gemini) | Char ratio (0.22) | ±10–25% |
| DeepSeek | Char ratio (0.27) | ±8–20% |
| Mistral | Char ratio (0.25) | ±8–20% |
| Meta (Llama) | Char ratio (0.25) | ±8–20% |
Results are flagged with isEstimate: true when char-ratio counting is used. Treat non-OpenAI cost figures as estimates, not accounting-grade numbers.
MCP Mastyf AI uses logarithmic compound scoring: each additional CVE in the same severity tier adds diminishing penalty. 1 critical CVE = −30, 2 = −60, 5 = −100, 10 = −130, 100 = −230. This prevents a single vulnerable package from zeroing the entire score while still scaling penalty with volume. CVE recency and EPSS (Exploit Prediction Scoring System) integration is planned for v2.4.
mTLS requires:
opensslSet MCP_TLS_CA_PATH=/path/to/ca.pem and MCP_TLS_CLIENT_CERT_PATH=/path/to/client.crt, MCP_TLS_CLIENT_KEY_PATH=/path/to/client.key per server in your MCP config's env section. A mastyf-ai certs init helper command is planned for v2.4 to automate this.
The proxy fails closed — malformed YAML causes a startup error and the proxy refuses to start. It does not silently fall back to the last good policy or default to audit mode. Use --dry-run to validate new policies before deploying:
mastyf-ai proxy --policy ./new-policy.yaml --dry-run
See CONTRIBUTING.md for guidelines. The monorepo uses pnpm workspaces with turbo for build orchestration. Run pnpm install && pnpm build && pnpm test to verify your setup. All PRs must pass the coverage thresholds in root vitest.config.ts and the red-team corpus evaluation (F1 ≥ 85%).
MCP Mastyf AI is production-grade for controlled environments (single-instance or Redis-backed multi-replica with MASTYF_AI_STRICT_MODE). The database layer uses better-sqlite3 with WAL mode and advisory file locking — crash-safe and non-blocking. It handles the core use case — active policy enforcement with audit trails — reliably. For high-trust enterprise deployments, a third-party security audit is planned for v2.5. See SECURITY.md for details on our security posture.
MIT — see LICENSE.
Built with TypeScript, better-sqlite3, pino, prom-client, jose, shell-quote, tiktoken, commander, chalk, and lru-cache.
FAQs
CLI binary for scanning MCP tool definitions
We found that @mastyf_ai/cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A new federal program will let vetted U.S. cybersecurity firms help investigate and disrupt foreign cybercrime groups under government direction.
Research
/Security News
The campaign amassed more than 75,000 installs by targeting Russian-speaking users seeking access to blocked services.
Company News
Open source maintainers are under more pressure than ever. We're raising our open source program from the Team plan to the Business plan, free.