Skip to main content
Best for: teams implementing MCP servers or MCP tool handlers directly in Python and wanting tool-level boundary protection without changing their server design.

​
Install

pip install verifiedx
This page is for standalone MCP tool handlers you own directly. If MCP is being surfaced through OpenAI Agents or another higher-level SDK, use that native adapter page instead.

​
Net-new VerifiedX code

This is the actual VerifiedX delta in an existing MCP server. 
from verifiedx import init_verifiedx, wrap_tool_handler

verifiedx = init_verifiedx()

handlers = {
    "search_memories": wrap_tool_handler(
        "search_memories",
        search_memories,
        verifiedx=verifiedx,
    ),
    "add_memory": wrap_tool_handler(
        "add_memory",
        add_memory,
        verifiedx=verifiedx,
        policy_scope="memory_write",
    ),
}

# In your existing callTool path:
return handlers[tool_name](params)
That is the important part. The rest of your MCP server stays the same: your listTools() output, transport, server wiring, and request routing do not need to be redesigned.
If a tool is definitely a durable memory write, pass policy_scope="memory_write" instead of relying only on name heuristics.
wrap_tool_handler(...) is a thin adapter over VerifiedX core boundary wrappers. It uses the same preflight, decision-receipt, execution-report, and runtime-loopback path as the rest of the product.
Your MCP tool surface is the config here. VerifiedX uses your existing tool names, descriptions, schemas, and params shape as the source of truth for what to preflight.

​
Optional: wrap tool definitions too

If your server returns tool definitions directly, you can also wrap them before returning them from listTools(): 
from verifiedx import wrap_tool_definition

wrapped_definitions = [
    wrap_tool_definition(definition, verifiedx=verifiedx)
    for definition in tool_definitions
]
Boundary protection lives in wrap_tool_handler(...). wrap_tool_definition(...) just enriches the tool definitions you expose from your MCP server.

​
Full example

from verifiedx import (
    init_verifiedx,
    wrap_tool_definition,
    wrap_tool_handler,
)

tool_definitions = [
    {
        "name": "search_memories",
        "description": "Search customer memory entries.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {"type": "string"},
            },
            "required": ["query"],
        },
    },
    {
        "name": "add_memory",
        "description": "Persist a customer memory entry.",
        "input_schema": {
            "type": "object",
            "properties": {
                "namespace": {"type": "string"},
                "key": {"type": "string"},
                "value": {},
            },
            "required": ["namespace", "key", "value"],
        },
    },
    {
        "name": "set_workflow_status",
        "description": "Update internal workflow status.",
        "input_schema": {
            "type": "object",
            "properties": {
                "workflow_id": {"type": "string"},
                "status": {"type": "string"},
                "reason": {"type": "string"},
            },
            "required": ["workflow_id", "status", "reason"],
        },
    },
]

definitions_by_name = {definition["name"]: definition for definition in tool_definitions}

verifiedx = init_verifiedx()

wrapped_tool_definitions = [
    wrap_tool_definition(definition, verifiedx=verifiedx)
    for definition in tool_definitions
]

def search_memories(params):
    return {
        "ok": True,
        "hits": [
            {"key": "cust_123.preference", "query": params["query"]},
        ],
    }

def add_memory(params):
    return {
        "ok": True,
        "saved": {
            "namespace": params["namespace"],
            "key": params["key"],
            "value": params["value"],
        },
    }

def set_workflow_status(params):
    return {
        "ok": True,
        "workflow_updated": {
            "workflow_id": params["workflow_id"],
            "status": params["status"],
            "reason": params["reason"],
        },
    }

handlers = {
    "search_memories": wrap_tool_handler(
        "search_memories",
        search_memories,
        verifiedx=verifiedx,
        definition=definitions_by_name["search_memories"],
    ),
    "add_memory": wrap_tool_handler(
        "add_memory",
        add_memory,
        verifiedx=verifiedx,
        policy_scope="memory_write",
        definition=definitions_by_name["add_memory"],
    ),
    "set_workflow_status": wrap_tool_handler(
        "set_workflow_status",
        set_workflow_status,
        verifiedx=verifiedx,
        definition=definitions_by_name["set_workflow_status"],
    ),
}

def list_tools():
    return wrapped_tool_definitions

def call_tool(tool_name, params):
    handler = handlers.get(tool_name)
    if handler is None:
        return {"ok": False, "error": f"Unknown tool: {tool_name}"}
    return handler(params)
Do not use raw install_runtime(...) for this path. The Python MCP surface is wrap_tool_handler(...), with optional wrap_tool_definition(...) for listTools() metadata.

​
Composed systems

If this MCP tool call is part of a larger multi-agent or agent+human workflow, pass upstream context into VerifiedX so the current tool invocation has better system and situational awareness before it takes a high-impact action. This is useful when a supervisor agent, parent workflow, or human reviewer already has context that the current MCP tool should use before taking action. VerifiedX does not require a fixed schema for this. Pass the upstream context you already have in any JSON-serializable shape. 
upstream = {
    "source": "workflow_supervisor",
    "workflow_id": "WF-2203",
    "approval_status": "approved_with_follow_up",
    "human_review": {
        "reviewer": "ops_lead",
        "result": "approved",
    },
    "prior_agent_output": {
        "summary": "Billing verification is complete.",
    },
}

with verifiedx.with_upstream_context(upstream):
    result = handlers["set_workflow_status"](
        {
            "workflow_id": "WF-2203",
            "status": "awaiting_human",
            "reason": "billing verification is missing",
        }
    )
Upstream context is supporting workflow context from outside the current tool invocation. It is not proof that this tool already executed any local action.

​
Async handlers

If your MCP handler is async, wrap_tool_handler(...) preserves that shape: 
async def add_memory(params):
    return {"ok": True, "saved": params}

guarded_add_memory = wrap_tool_handler(
    "add_memory",
    add_memory,
    verifiedx=verifiedx,
    policy_scope="memory_write",
)

result = await guarded_add_memory(
    {"namespace": "crm", "key": "cust_123.preference", "value": "sms"}
)

​
What the wrapper already does

Once wrapped, VerifiedX handles the MCP tool boundary directly. That includes:
  • Injecting _meta.verifiedx into request params and result payloads
  • Recording retrieval-like tools into run history as support inputs
  • Preflighting high-impact tools before the handler runs
  • Observing tool-result ingress with sourceUri: "mcp://<tool_name>"
  • Emitting MCP tool-result events with sourceLineage: ["mcp_tool"]

​
What gets preflighted

VerifiedX infers the protected boundary from the MCP tool name and params. That includes:
  • memory_write
  • external_message_send
  • record_mutation
  • system_change
Retrieval-like tools stay in run history as support inputs instead of being treated as mutations. Examples from the actual Python MCP wrapper behavior:
  • search_memories records retrieval history
  • add_memory with namespace, key, and value preflights as memory_write
  • send_email infers external_message_send
  • update_customer_record infers record_mutation
  • set_workflow_status infers system_change
The explicit override today is mainly policy_scope="memory_write" for durable memory writes. Other action classes are inferred from the MCP tool name and params shape.

​
What to expect at runtime

Protected MCP boundaries can return:
  • allow
  • allow_with_warning
  • replan_required
  • goal_fail_terminal
Every outcome includes a structured decision receipt. If a tool is replanned, the side effect does not execute. The wrapped handler returns the normal VerifiedX blocked result shape, including:
  • ok: false
  • blocked: true
  • boundary_outcome
  • safe_next_steps
  • decision_receipt
In a standalone MCP server, you will usually consume that blocked result locally and let the caller replan. When the same tool is composed inside a larger orchestration layer, the same receipt can signal either local replan or upstream replan.

​
Validation coverage

The standalone Python MCP wrapper is directly covered in this repo. That includes:
  • Retrieval history carrying into a later memory-write preflight
  • Durable memory writes preflighting as memory_write
  • Internal workflow updates preflighting as system_change
  • Blocked external sends returning the normal loopback result and suppressing the side effect

​
Pricing note

One protected action check equals one real boundary preflight. Taint, event ingest, execution reports, and decision reads are all included at that price. The Free Sandbox includes every language, provider, framework, and adapter. VerifiedX does not replace your MCP server or orchestration. It returns receipts your system can keep local, route downstream, or pass upstream.
For the full raw runtime reference, see the Python SDK. If your MCP tools are being used through OpenAI Agents, see the OpenAI Agents SDK page.