MCP

The MCP (Model Context Protocol) adapter intercepts tool calls on an MCP server, records each invocation through an Arclasp chain, and only forwards the call to the underlying handler when the policy engine allows it. If you’re building MCP servers exposing tools to Claude Desktop, Cursor, or any other MCP client, this is how you add governance without changing your tool code.

Install

pip install "arclasp[mcp]"

This installs the official Anthropic mcp Python SDK if not already present.

Supported MCP Python SDK versions: 1.0.x. The protocol is still evolving — pin the specific version range you’ve tested against.

Quick start

The mcp SDK (>= 1.0) no longer exposes a patchable call-handler attribute, so there’s no server-patching shortcut. Wire governance directly inside your @server.call_tool() handler by calling handle_tool_call():

import asyncio
import arclasp
from arclasp.mcp import ArclaspMcpAdapter
from mcp.server import Server

arclasp.init(api_key="prail_...", backend_url="https://api.proofrail.dev")

server = Server("my-tools")

async def dispatch(name: str, arguments: dict):
    if name == "query_database":
        return await query_database(arguments)
    if name == "send_email":
        return await send_email(arguments)
    raise ValueError(f"Unknown tool: {name}")

async def main():
    async with arclasp.Chain("mcp-session") as chain:
        adapter = ArclaspMcpAdapter(chain=chain, agent_name="my-tools")

        @server.call_tool()
        async def handle_call_tool(name: str, arguments: dict):
            return await adapter.handle_tool_call(
                tool_name=name,
                arguments=arguments,
                handler=dispatch,
            )

        # `read_stream`, `write_stream`, and `init_options` come from your
        # chosen MCP transport (stdio, SSE, etc.) — see the `mcp` SDK's own
        # transport docs for how to construct them. This isn't a turnkey
        # value; it depends on how you're serving the MCP connection.
        await server.run(read_stream, write_stream, init_options)

asyncio.run(main())

Every tool call passed through handle_tool_call() goes through Arclasp’s policy engine before dispatch runs. Denied calls raise ActionDeniedError in your handler — catch it and return an MCP-compatible error to the client. MCP integration records the governed invocation and policy decision before tool execution. Tool return values and execution exceptions are not persisted as MCP action evidence in this release.

Two usage patterns

The MCP adapter supports two integration styles depending on how much control you want over dispatching.

Pattern 1: `handle_tool_call()` — wrap your existing dispatch

Route calls through the adapter from inside your @server.call_tool() handler, as shown above. This gives you full control over the dispatching logic while recording every call. This is the recommended approach for most cases.

ArclaspMcpAdapter.install() exists on the class but raises RuntimeError — it is not supported with mcp >= 1.0, which removed the patchable _call_tool_handler attribute the old implementation relied on. Do not call it; use handle_tool_call() inside your own handler instead.

Pattern 2: `@adapter.tool()` decorator — per-tool wrapping

For more granular control, decorate individual tool implementations:

@adapter.tool("query_database")
async def query_database(name: str, arguments: dict):
    return {"rows": await db.fetch(arguments["sql"])}

@adapter.tool("send_email")
async def send_email(name: str, arguments: dict):
    return await mailer.send(arguments)

Each decorated function records a governance event before executing. Use this when you want explicit governance scope per tool rather than blanket coverage.

What gets recorded

For each tool invocation:

A tool_call event with the tool name as action_name and the arguments as the payload
agent_name is the value you passed to ArclaspMcpAdapter
parent_agent_name if you supplied one (useful for tracking MCP client identity)

The MCP session corresponds to an Arclasp chain. Each tool call within the session is one event in that chain.

Policy enforcement

When a policy denies a tool call:

from arclasp.exceptions import ActionDeniedError

try:
    result = await adapter.handle_tool_call(name, arguments, handler)
except ActionDeniedError as exc:
    # The MCP server should return an error to the client
    return {"error": str(exc)}

Catch ActionDeniedError inside your @server.call_tool() handler (as shown above) and convert it to whatever error shape your MCP transport expects — the adapter itself does not do this conversion for you. For approval-required decisions, handle_tool_call blocks until the approver responds. The MCP client sees a delayed response (until approval times out, your client may consider the call hung — set reasonable client timeouts).

Identifying the MCP client

If your MCP server knows which client is connected, pass that identity as parent_agent_name:

adapter = ArclaspMcpAdapter(
    chain=chain,
    agent_name="my-tools",
    parent_agent_name="claude-desktop",  # or "cursor", "custom-client", etc.
)

This appears in the audit trail and helps with cross-organization tracking when multiple clients connect to the same server.

Session lifetime

An Arclasp chain corresponds to an MCP session. The natural pattern:

# One chain per MCP server lifetime
async def main():
    async with arclasp.Chain("server-lifetime") as chain:
        adapter = ArclaspMcpAdapter(chain=chain, agent_name="my-tools")

        @server.call_tool()
        async def handle_call_tool(name: str, arguments: dict):
            return await adapter.handle_tool_call(
                tool_name=name, arguments=arguments, handler=dispatch,
            )

        await server.run(read_stream, write_stream, init_options)  # runs until server exits

For long-running servers with many sessions, you might want a chain per session instead. This requires more custom wiring — see the SDK’s arclasp/mcp/adapter.py for the underlying primitives.

Edge cases

Calling install(). It exists on ArclaspMcpAdapter for backward compatibility but always raises RuntimeError — it is not supported with mcp >= 1.0. Use handle_tool_call() inside your own @server.call_tool() handler instead. Multiple tools registered. Since dispatching happens in your own handler, every tool your handler routes through handle_tool_call() is covered — there’s no separate registration step with the adapter. Tool with no arguments. Works fine — arguments={} is a valid payload. Streaming tool responses. MCP tools that stream responses are tracked at the request level only. The response stream is forwarded to the client unchanged; Arclasp doesn’t intercept individual stream chunks. Tool errors. If the underlying handler raises, the exception propagates after the governance event is recorded. The event records the governed invocation — the error itself is part of the MCP response.

Where to go next

LangGraph adapter

For LangGraph-orchestrated agent workflows.

LangChain adapter

For LangChain agent executors and chains.

Policies

What decisions get applied to your tool calls.

SDK reference

The complete ArclaspMcpAdapter API.

Get Started

Concepts

Framework Integration

Guides

Other

MCP

MCP

Install

Quick start

Two usage patterns

Pattern 1: `handle_tool_call()` — wrap your existing dispatch

Pattern 2: `@adapter.tool()` decorator — per-tool wrapping

What gets recorded

Policy enforcement

Identifying the MCP client

Session lifetime

Edge cases

Where to go next

LangGraph adapter

LangChain adapter

Policies

SDK reference

​MCP

​Install

​Quick start

​Two usage patterns

​Pattern 1: handle_tool_call() — wrap your existing dispatch

​Pattern 2: @adapter.tool() decorator — per-tool wrapping

​What gets recorded

​Policy enforcement

​Identifying the MCP client

​Session lifetime

​Edge cases

​Where to go next

LangGraph adapter

LangChain adapter

Policies

SDK reference

MCP

Install

Quick start

Two usage patterns

Pattern 1: `handle_tool_call()` — wrap your existing dispatch

Pattern 2: `@adapter.tool()` decorator — per-tool wrapping

What gets recorded

Policy enforcement

Identifying the MCP client

Session lifetime

Edge cases

Where to go next