Network egress firewall for AI agents — check URLs against allow/deny policy before fetching via @mukundakatta/agentguard-mcp

@mukundakatta/agentguard-mcp v0.1.0 — Verified Recipe

Package: @mukundakatta/agentguard-mcp (wraps agentguard v0.1.1) Transport: stdio Entry: dist/server.js Install: npm install @mukundakatta/agentguard-mcp

Tools (3)

1. `check_url` ({url, policy, method?}) — Check if a URL is allowed under a network policy. Returns {allowed, reason, detail}. No actual HTTP request made.
2. `check_urls_batch` ({urls[], policy, method?}) — Batch-check multiple URLs against the same policy. Returns per-URL decisions + summary: {total, allowed_count, denied_count}.
3. `validate_policy` ({policy}) — Sanity-check a policy spec. Returns {valid, issues[]}.

Policy Spec

{
  "allow": ["api.openai.com", "*.anthropic.com"],
  "deny": ["evil.anthropic.com"],
  "methods": ["GET", "POST"]
}

• allow: host patterns (exact or *.suffix wildcards)
• deny: host patterns that override allow (deny wins)
• methods: HTTP methods to permit (omit = any)

Test Results: 17 calls, 100% success, p50=0ms

check_url (11 calls):

• Exact host match → {allowed: true, reason: "matched_allowlist"} ✓
• Wildcard *.anthropic.com matches docs.anthropic.com ✓
• Deny wins over wildcard allow — evil.anthropic.com in deny → {allowed: false, reason: "denylist_match"} ✓
• Host not in allow → {allowed: false, reason: "not_in_allowlist", detail: "malicious-site.com"} ✓
• Method DELETE blocked → {allowed: false, reason: "method_blocked", detail: "DELETE"} ✓
• Method GET allowed ✓
• No methods restriction → any method OK ✓
• Deep subdomain us-east-1.api.anthropic.com matches *.anthropic.com ✓
• Non-standard port ignored (host still matches) ✓
• IP address allowed when in allow list ✓
• IP not in allow → blocked ✓

check_urls_batch (1 call, 5 URLs):

• Mixed 3 allowed / 2 denied → correct per-URL results + summary ✓

validate_policy (5 calls):

• Good policy → {valid: true, issues: []} ✓
• Empty allow list → warns "every request will be denied" ✓
• Overly broad * → warns "equivalent to no firewall" ✓
• Host includes scheme → warns "use bare host" ✓
• Host includes path → warns "agentguard matches host only" ✓

Key Gotchas

• Host-level only — no path/query matching. allow: ["api.openai.com"] allows ALL paths on that host
• Deny always wins — even if a deny pattern is also in the allow list
• Wildcard depth unlimited — *.example.com matches a.b.c.example.com
• Ports ignored for matching — api.openai.com:8443 matches allow for api.openai.com
• IP addresses supported — both IPv4 and hostnames work in allow/deny
• No CIDR notation — use exact IPs, not ranges
• Sub-millisecond after JIT — first call ~2ms, rest 0ms
• No request made — purely policy evaluation, safe to call speculatively

4 reason values:

• matched_allowlist — host in allow (and not in deny)
• denylist_match — host in deny (detail shows pattern)
• not_in_allowlist — host not matched (detail shows host)
• method_blocked — method not in methods list (detail shows method)

When To Use

Gate every agent tool-call that makes an HTTP request. Before fetch(url), call check_url with the agent's policy. Block disallowed destinations before the request happens — especially useful for RAG pipelines, web scraping agents, and API integration agents where prompt injection could redirect fetches to attacker-controlled hosts.