MCP Guardian — Security Layer for AI Agent Tool Usage

Problem statement

SOC teams are connecting AI agents to MCP servers that expose real tools — SIEM queries, EDR isolate calls, ticketing writes, IOC enrichment APIs. By default an agent gets a flat, undifferentiated tool surface: any tool, any argument, no review.

That's a privilege concentration problem dressed up as an integration convenience. Without a guardrail layer, a single prompt injection or a confused-deputy attack can drive consequential calls through the agent's identity.

Why it matters

AI agents in security workflows are highly privileged callers. They sit in front of containment, blocking, and notification systems. A compromised or manipulated agent does not just produce a bad answer — it changes infrastructure state, silences alerts, or exfiltrates investigation context through tool arguments.

MCP Guardian moves the trust boundary from "is the agent safe?" to "is this specific tool call, with these specific arguments, allowed right now under these specific approvals?" — a much smaller and more verifiable question.

Threat model

• Prompt injection via untrusted content — alert payloads, email bodies, web fetches that steer the agent toward unsanctioned tools.
• Scope escalation — calling a legitimate tool with arguments outside the agent's authorized scope (e.g. isolating a host the agent had no business touching).
• Data exfiltration through tool arguments — encoding sensitive context inside a URL, query, or webhook field.
• Confused-deputy abuse — relying on the agent's identity to invoke a tool the calling user could not invoke directly.
• Audit erasure — agents that fail without leaving structured evidence of what they tried to do.

Architecture diagram

Key features

• Per-tool policy. Allow-lists declared in code, evaluated against tool name + arguments before the call leaves the proxy.
• Argument validation. JSON-schema validation for every tool's parameters; rejects calls with extra or coerced fields.
• Redaction. Field-level redaction for known sensitive shapes (secrets, internal hostnames, PII) on both input args and tool outputs.
• Approval modes. auto, review, and blocked per tool, switchable per session.
• Tamper-evident audit. Hash-chained append-only log of every tool call, argument, response, and approval decision.
• Replay. Reconstruct any session deterministically from the audit log.

Guardrails & controls

• Policy engine (OPA-style rules) evaluated before a tool call hits the network.
• Scope identity carried explicitly (session_id, agent_id, operator_id) and checked on every call.
• Pre-call and post-call hooks for content classification (prompt-injection detectors, output exfil checks).
• Rate caps per identity per tool, separate from upstream tool rate limits.
• Forced approval on a configurable set of consequential tools (containment, user disable, notification).

Tech stack

Language

Python 3.12

Framework

FastAPI · async MCP shim

Policy

Rego-style rules, evaluated locally

Storage

Append-only audit (Postgres / SQLite for dev)

Eval

Replay harness with red-team prompts

Distribution

Docker image · GitHub Actions CI

Example workflow

An agent receives a phishing alert and decides to enrich the URL and isolate the source host.

1. Agent emits tools.virustotal.lookup({ url }). Guardian validates schema, applies redaction, evaluates policy. Allowed; logged.
2. Agent then emits tools.crowdstrike.isolate({ host_id }). Guardian recognizes a consequential tool; switches to review mode and surfaces the call to the on-call analyst with context.
3. Analyst approves with one click. Guardian executes, captures response, hash-chains the result to the prior log entries.
4. Session is closed; audit chain is sealed and made available for review and replay.

Screenshots

Visual placeholders. Replace with real screenshots from the project.

Lessons learned

• Schemas are the guardrail. The single most useful control is strict argument schemas; most "bad" calls fail validation before policy is ever consulted.
• Approval UX is half the project. Analysts will refuse a guardrail that costs them more time than the action saves. Context budget — what does the analyst need to see in 5 seconds — drove most design decisions.
• Redaction belongs at the proxy. Trying to teach the agent to self-redact never converges; doing it at the boundary is deterministic.

Future roadmap

• Multi-agent session graph — track delegation chains across agents calling agents.
• Pluggable detection backends for prompt-injection and exfil classifiers.
• Signed audit exports for compliance review and incident reconstruction.
• SDK shims for common SOAR platforms so playbooks can call agents through the guardian without bespoke glue.