mcp-guardian-ai

# MCP Guardian **Agent intent enforcement for MCP tool calls — pre-execution security for AI agents.** MCP Guardian is not a firewall for MCP servers. It's a **declarative intent guardrail** for agent behavior. It validates every tool call against declared intent policies *before execution*. If the call doesn't match the policy, the MCP server never sees it. ## Install ```bash pip install mcp-guardian-ai ``` This pulls in all dependencies: `openai-agents`, `pydantic`, `pyyaml`. Or install everything explicitly: ```bash pip install mcp-guardian-ai openai-agents pydantic pyyaml ``` Set your OpenAI API key (used by the LLM intent evaluator — the fast check tier runs without it): ```bash export OPENAI_API_KEY=sk-... ``` > **Note:** The PyPI package is `mcp-guardian-ai`. The Python import is `mcp_guardian`. For development from source: ```bash git clone https://github.com/mcp-guardian/mcp-guardian.git cd mcp-guardian pip install -e ".[dev]" ``` ## Three Ways to Use It ### Path 1: Pure Python (no files needed) ```python import asyncio from agents import Agent, Runner from agents.mcp import MCPServerStreamableHttp from mcp_guardian import GuardianToolGuardrail, IntentPolicy policy = IntentPolicy( name="read-only", description="Read files only — no writes, no shell", expected_workflow="Read and list files to answer user questions", forbidden_tools=["write_*", "execute_*", "delete_*"], ) guardrail = GuardianToolGuardrail(policy=policy) async def main(): async with MCPServerStreamableHttp( name="my-server", params={"url": "https://my-mcp-server.example.com/mcp"}, ) as server: tools = await guardrail.wrap_mcp_tools([server]) agent = Agent(name="Worker", model="gpt-4o", tools=tools) result = await Runner.run(agent, "List all files") print(result.final_output) # Print audit log for entry in guardrail.audit_log: verdict = str(entry.verdict) icon = "✓" if verdict == "…