MCP (Model Context Protocol)

Attesta provides two patterns for enforcing human-in-the-loop approval on MCP tool invocations, regardless of which client (VS Code, Cursor, Claude Code, Windsurf, etc.) calls the tools.

attesta_tool_handler — a decorator for MCP call_tool handlers. Use this when you author your own MCP servers in Python.
MCPProxy — a stdio proxy that wraps any existing MCP server with Attesta approval, requiring zero code changes to the upstream server.

Installation

pip install attesta

MCP support is included in the core package — no additional extras required.

Architecture

 Editor / IDE  <--stdio-->  Attesta MCPProxy  <--stdio-->  Real MCP Server
                                  |
                                  +-- risk scoring per tool call
                                  +-- domain-aware evaluation (custom profiles)
                                  +-- policy enforcement (approve / deny / audit)
                                  +-- tamper-proof audit trail

The proxy sits transparently between the MCP client and server. It intercepts tools/call JSON-RPC requests, evaluates them through Attesta, and either forwards the request to the upstream server (approved) or returns an error response directly (denied). All other messages (tool listings, notifications, etc.) pass through unchanged.

Pattern 1: Decorator (Custom MCP Servers)

Use attesta_tool_handler when you are writing your own MCP server in Python. Place it between @server.call_tool() and your handler function.

API

attesta_tool_handler(attesta, *, risk_overrides=None) -> Callable

Parameter	Type	Description
`attesta`	`Attesta`	A configured Attesta instance
`risk_overrides`	`dict[str, str] \| None`	Optional `{tool_name: risk_level}` mapping

Full Example

from mcp.server import Server
from mcp.types import TextContent
from attesta import Attesta
from attesta.integrations.mcp import attesta_tool_handler

server = Server("my-devops-server")
attesta = Attesta.from_config("attesta.yaml")


@server.list_tools()
async def list_tools():
    return [
        {
            "name": "run_bash",
            "description": "Execute a bash command",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "command": {"type": "string"},
                },
                "required": ["command"],
            },
        },
        {
            "name": "read_file",
            "description": "Read file contents",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "path": {"type": "string"},
                },
                "required": ["path"],
            },
        },
    ]


@server.call_tool()
@attesta_tool_handler(
    attesta,
    risk_overrides={"run_bash": "critical"},
)
async def call_tool(name: str, arguments: dict):
    """Only executes if Attesta approves the tool call."""
    if name == "run_bash":
        import subprocess
        result = subprocess.run(
            arguments["command"], shell=True, capture_output=True, text=True,
        )
        return [TextContent(type="text", text=result.stdout)]

    if name == "read_file":
        with open(arguments["path"]) as f:
            return [TextContent(type="text", text=f.read())]

    return [TextContent(type="text", text=f"Unknown tool: {name}")]

Behavior on Denial

When a tool call is denied, the decorator returns an MCP-compatible TextContent error instead of calling the handler:

[TextContent(
    type="text",
    text="Action denied by Attesta: run_bash (risk: critical, score: 0.92)",
)]

The MCP client (editor/IDE) displays this message to the user. The handler function is never executed.

The decorator sets metadata={"source": "mcp"} on all ActionContext objects. This allows you to write audit queries that filter for MCP-specific tool calls.

Pattern 2: MCPProxy (Zero Code Changes)

MCPProxy wraps any existing MCP server with Attesta approval. No modifications to the upstream server are needed. This is the recommended approach for enforcing organization-wide HITL policies across all MCP tools.

API

MCPProxy(attesta, upstream_command, *, risk_overrides=None)

Parameter	Type	Description
`attesta`	`Attesta`	A configured Attesta instance
`upstream_command`	`list[str]`	Command to start the upstream MCP server
`risk_overrides`	`dict[str, str] \| None`	Optional `{tool_name: risk_level}` mapping

Methods:

Method	Description
`run()`	Start the proxy. Blocks until the upstream server exits or the client disconnects.

CLI Usage

The simplest way to use the proxy is through the attesta mcp wrap CLI command:

# Wrap the filesystem MCP server
attesta mcp wrap -- npx @modelcontextprotocol/server-filesystem /home/user/projects

# Wrap a custom MCP server
attesta mcp wrap -- python my_mcp_server.py

# Wrap with a custom config file
attesta mcp wrap --config attesta.yaml -- npx @modelcontextprotocol/server-github

Editor Configuration

Configure your editor to use the proxy instead of calling the MCP server directly:

{
  "mcp.servers": {
    "filesystem": {
      "command": "attesta",
      "args": [
        "mcp", "wrap", "--",
        "npx", "@modelcontextprotocol/server-filesystem", "/home/user/projects"
      ]
    }
  }
}

{
  "mcpServers": {
    "filesystem": {
      "command": "attesta",
      "args": [
        "mcp", "wrap", "--",
        "npx", "@modelcontextprotocol/server-filesystem", "/home/user/projects"
      ]
    }
  }
}

{
  "mcpServers": {
    "filesystem": {
      "command": "attesta",
      "args": [
        "mcp", "wrap", "--",
        "npx", "@modelcontextprotocol/server-filesystem", "/home/user/projects"
      ]
    }
  }
}

Programmatic Usage

from attesta import Attesta
from attesta.integrations.mcp import MCPProxy

attesta = Attesta.from_config("attesta.yaml")

proxy = MCPProxy(
    attesta,
    upstream_command=["npx", "@modelcontextprotocol/server-filesystem", "/path"],
    risk_overrides={
        "write_file": "high",
        "delete_file": "critical",
    },
)

# Blocks until the upstream server exits
proxy.run()

How the Proxy Works

Startup

The proxy spawns the upstream MCP server as a child process via subprocess.Popen, connected by stdin/stdout pipes. The upstream server’s stderr passes through to the terminal for debugging.

Request Interception

The proxy reads JSON-RPC messages from its own stdin (the MCP client). When it sees a tools/call request, it extracts the tool name and arguments for evaluation.

Attesta Evaluation

The tool call is evaluated through attesta.evaluate() with an ActionContext containing:

function_name: the tool name from the request
kwargs: the tool arguments
metadata: {"source": "mcp_proxy"}

Forwarding or Denial

Approved: the original request is forwarded to the upstream server’s stdin. The response flows back through the proxy to the client.
Denied: the proxy generates a JSON-RPC error response directly. The request never reaches the upstream server.

Denial Response Format

Denied tool calls return a JSON-RPC response with isError: true:

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Action denied by Attesta: run_bash (risk: critical, score: 0.92). This action requires human approval that was not granted."
      }
    ],
    "isError": true
  }
}

Protocol Support

The proxy auto-detects the framing format used by the MCP client and server:

Format	Description	Used By
Content-Length framing	`Content-Length: N\r\n\r\n{...}` (official MCP/LSP spec)	Most MCP servers
Newline-delimited JSON	One JSON object per line	Some MCP implementations

Both formats are supported transparently. The proxy always writes responses using Content-Length framing.

Logging

The proxy logs all approval and denial decisions to stderr (visible in the terminal, not sent to the MCP client):

[attesta] Attesta MCP proxy started, wrapping: npx @modelcontextprotocol/server-filesystem /path
[attesta]   [approved] read_file (risk: low, score: 0.15)
[attesta]   [DENIED]   write_file (risk: high, score: 0.72)
[attesta]   [DENIED]   run_bash (risk: critical, score: 0.95)

The proxy runs attesta.evaluate() synchronously using asyncio.run() for each intercepted tool call. This means tool calls are evaluated one at a time, which adds latency. For most MCP use cases (editor-driven tool calls), this is acceptable because humans are in the loop anyway.

CLI Reference: mcp wrap

Full CLI options for attesta mcp wrap

Vercel AI SDK

TypeScript tool wrappers and middleware

Code Integrations

No-Code Platforms

MCP (Model Context Protocol)

Installation

Architecture

Pattern 1: Decorator (Custom MCP Servers)

API

Full Example

Behavior on Denial

Pattern 2: MCPProxy (Zero Code Changes)

API

CLI Usage

Editor Configuration

Programmatic Usage

How the Proxy Works

Denial Response Format

Protocol Support

Logging

CLI Reference: mcp wrap

Vercel AI SDK

​Installation

​Architecture

​Pattern 1: Decorator (Custom MCP Servers)

​API

​Full Example

​Behavior on Denial

​Pattern 2: MCPProxy (Zero Code Changes)

​API

​CLI Usage

​Editor Configuration

​Programmatic Usage

​How the Proxy Works

​Denial Response Format

​Protocol Support

​Logging

CLI Reference: mcp wrap

Vercel AI SDK

Installation

Architecture

Pattern 1: Decorator (Custom MCP Servers)

API

Full Example

Behavior on Denial

Pattern 2: MCPProxy (Zero Code Changes)

API

CLI Usage

Editor Configuration

Programmatic Usage

How the Proxy Works

Denial Response Format

Protocol Support

Logging