Basic Usage & Strict Integrity

The MCP Firewall sits between your application and the MCP Server. It intercepts tool discovery and execution to enforce your security policy. To use it, you wrap your existing MCP session with the mcp_guard function.

from mcp import ClientSession
from deconvolute import mcp_guard

# Wrap your existing MCP session
safe_session = mcp_guard(original_session)

# Use as normal; the firewall intercepts discovery and execution
await safe_session.initialize()

# Allowed: read_file is in your policy
result = await safe_session.call_tool("read_file", path="/docs/report.md")
print(result.content[0].text)

# Blocked: execute_code not in policy
# Returns a valid result with isError=True to prevent crashes
result = await safe_session.call_tool("execute_code", code="import os; os.system('rm -rf /')")

if result.isError:
    print(f"Firewall blocked: {result.content[0].text}")
    # Output: "Tool 'execute_code' not in approved policy"

TODO

Custom Policy Path

You can specify a custom location for your policy file if you do not want to use the default deconvolute_policy.yaml in your working directory.

from deconvolute import mcp_guard

safe_session = mcp_guard(
    original_session,
    policy_path="./config/production_policy.yaml"
)

TODO

Agent Identification

Pass an agent_id to identify which agent runtime is connecting through the proxy. This value is attached to every audit event and surfaces in the enterprise platform, allowing security teams to filter and group activity by agent across sessions.

from deconvolute import mcp_guard

safe_session = mcp_guard(
    original_session,
    policy_path="./config/production_policy.yaml",
    agent_id="my-agent-id"
)

TODO

If omitted, events are recorded without an agent identifier. Use a short stable string that identifies the agent runtime or deployment, such as "cowork", "copilot", or "internal-agent-v1".

Initialization Order & Server Identity

Deconvolute extracts the server's identity (name and version) during the initialization handshake to enforce anti-downgrade and version constraints. Because of how the underlying SDK manages this state, the order in which you wrap and initialize your session matters.

1. Wrap First, Initialize Second (Preferred)

The most secure and streamlined approach is to wrap the session before initialization. The proxy will automatically intercept the handshake, validate the server's version, and block the connection if it detects a policy violation.

from deconvolute import mcp_guard

# 1. Wrap the raw session
safe_session = mcp_guard(session)

# 2. Initialize the guarded session
# If the server version violates your policy, this will raise a ServerIdentityError
await safe_session.initialize()

TODO

2. Initialize First, Wrap Second

In complex asynchronous architectures, you might need to initialize sessions in a worker pool before wrapping them with a security policy.

Because the raw session discards the server's identity metadata after initialization, you must explicitly pass the InitializeResult into mcp_guard using the init_result parameter. This state hydration ensures the firewall can still perform strict version validation.

from deconvolute import mcp_guard

# 1. Initialize the raw session first
init_result = await session.initialize()

# 2. Wrap the session and inject the initialization result
# If the server version violates your policy, this will raise a ServerIdentityError immediately
safe_session = mcp_guard(
    session,
    init_result=init_result
)

TODO

Transport Layer Protection

mcp_guard operates at the application payload layer, enforcing your policy against what tool calls do. For network-facing agents connecting over SSE, you should also protect the transport layer against DNS-based attacks. For details, see section Transport Origin Validation.