mcp-trustguard 0.1.0

TrustGuard integration for MCP (Model Context Protocol) - secure your AI tools

MCP TrustGuard

Security integration for MCP (Model Context Protocol) - protect your AI tools from malicious content.

Installation

pip install mcp-trustguard

Features

• MCPGuard - Scan tool descriptions and responses for threats
• ProtectedMCPClient - Wrap any MCP client with automatic security
• TrustGuardMiddleware - Add security to MCP servers

Quick Start

Scan Tools Before Registration

from mcp_trustguard import MCPGuard

guard = MCPGuard(api_key="ta_xxx...")

# Scan a tool description
result = guard.scan_tool(
    name="file_reader",
    description="Reads files from disk",
    schema={"type": "object", "properties": {...}}
)

if result.is_safe:
    register_tool(tool)
else:
    print(f"Blocked: {result.reasoning}")
    print(f"Threats: {[t['pattern_name'] for t in result.threats]}")

Protected MCP Client

Automatically filter unsafe tools and scan responses:

from mcp import Client
from mcp_trustguard import ProtectedMCPClient

# Wrap your MCP client
base_client = Client()
client = ProtectedMCPClient(
    base_client,
    api_key="ta_xxx...",
    block_unsafe_tools=True,
    block_unsafe_responses=True,
)

# Only returns safe tools
tools = await client.list_tools()

# Scans response before returning
result = await client.call_tool("web_search", {"query": "python tutorials"})

Server Middleware

Add security to your MCP server:

from mcp.server import Server
from mcp_trustguard import TrustGuardMiddleware

server = Server()
middleware = TrustGuardMiddleware(api_key="ta_xxx...")

@server.list_tools()
async def list_tools():
    tools = get_all_tools()
    return middleware.filter_tools(tools)  # Filters unsafe tools

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    # Scan arguments for prompt injection
    middleware.scan_arguments(name, arguments)
    return await execute_tool(name, arguments)

---

API Reference

MCPGuard

Core scanning functionality.

guard = MCPGuard(
    api_key="ta_xxx...",     # TrustGuard API key
    strict_mode=False,        # If True, block on MEDIUM threats
    timeout=30.0,             # Request timeout
)

# Scan a tool
result = guard.scan_tool(name, description, schema)
print(result.is_safe)         # bool
print(result.verdict)         # 'allow', 'caution', 'block'
print(result.threats)         # List of detected threats

# Scan a response
result = guard.scan_response(tool_name, response_content)

# Filter a list of tools
safe_tools = guard.filter_tools(tools, on_blocked="warn")

ProtectedMCPClient

Wraps an MCP client with automatic scanning.

client = ProtectedMCPClient(
    base_client,
    api_key="ta_xxx...",
    block_unsafe_tools=True,      # Filter tools from list_tools
    block_unsafe_responses=False,  # Raise on unsafe responses
    strict_mode=False,
)

tools = await client.list_tools()          # Filtered
result = await client.call_tool(name, args) # Scanned

# Check if a tool is safe
is_safe = client.is_tool_safe("web_search")

TrustGuardMiddleware

For MCP server integration.

middleware = TrustGuardMiddleware(
    api_key="ta_xxx...",
    strict_mode=False,
    log_events=True,
    on_threat_detected=my_callback,  # Optional callback
)

# Scan during registration
result = middleware.scan_tool_registration(name, description, schema)

# Filter tools for list_tools response
safe_tools = middleware.filter_tools(tools)

# Scan arguments
middleware.scan_arguments(tool_name, arguments, block_on_threat=True)

# Get unsafe tools
unsafe = middleware.get_unsafe_tools()

---

What Gets Detected

Tool Description Threats:

• Hidden instructions ("Always run X first...")
• Capability escalation attempts
• Data exfiltration patterns
• Schema manipulation

Response Threats:

• Prompt injection attempts
• Hidden instructions
• Malicious payloads

---

Error Handling

from mcp_trustguard import UnsafeToolError, UnsafeResponseError

try:
    result = await client.call_tool("suspicious_tool", args)
except UnsafeToolError as e:
    print(f"Tool blocked: {e.tool_name}")
    print(f"Reason: {e.result.reasoning}")
except UnsafeResponseError as e:
    print(f"Response blocked from: {e.tool_name}")
    print(f"Threats: {e.result.threats}")

---

Statistics

stats = guard.get_stats()
print(f"Tools scanned: {stats['tools_scanned']}")
print(f"Tools blocked: {stats['tools_blocked']}")
print(f"Responses scanned: {stats['responses_scanned']}")

License

MIT License

Links

• TrustAgents: https://trustagents.dev
• MCP Protocol: https://github.com/anthropics/mcp
• GitHub: https://github.com/jd-delatorre/trustlayer