playbooks

home / mcp / trail context mcp wrapper

Trail Context MCP Wrapper

Security wrapper for MCP servers providing trust-on-first-use pinning, guardrails, and quarantined tool responses.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "trailofbits-mcp-context-protector": {
      "url": "DOWNSTREAM_SERVER_URL"
    }
  }
}

mcp-context-protector acts as a security wrapper for MCP servers, enforcing trust-on-first-use pinning, guardrail scanning, and configuration protection so you can run potentially untrusted MCP servers with fewer risks. It centralizes security controls, adapts to different MCP clients, and helps prevent prompt injection and configuration rug pulls.

How to use

Prepare your environment and connect your MCP client to the wrapper to ensure tool configuration pinning and guardrail checks are applied to every downstream server call.

How to install

Prerequisites: you need a runtime environment capable of running the wrapper and the downstream MCP server. The typical setup uses uv as a runner for JavaScript-based tooling.

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Download mcp-context-protector
git clone https://github.com/trailofbits/mcp-context-protector
# Install dependencies
cd mcp-context-protector
uv sync
```

To simplify launching, consider updating the launcher to point directly to the uv executable, since some MCP clients override PATH when starting servers.

Additional content

Server configuration pinning uses trust-on-first-use to approve and pin downstream server configurations. Any deviation from an approved configuration will block tool calls until you explicitly approve the change. Approving a server is done via the CLI by running the wrapper with the argument --review-server. The wrapper connects to the downstream server, retrieves its configuration, and presents it for your approval. Once approved, the configuration is saved and you can restart your host application to apply it normally.

Guardrail scanning can be enabled by providing a guardrail provider. If a prompt injection is detected in a tool response, the offending output is quarantined in ~/.mcp-context-protector/quarantine.json. You can review quarantined responses with --review-quarantine and release approved responses with the quarantine_release flow.

Configuring MCP wiring involves using the wrapper to start the downstream server. You may run the wrapper in stdio mode or through HTTP, and you can pass a direct command or a command string to the downstream server. The following forms are supported: - Start the wrapper with a stdio server using a direct command: - /path/mcp-context-protector.sh --command "DOWNSTREAM_SERVER_COMMAND ARG1 ARG2" - This form keeps the downstream command intact and lets the wrapper apply its protections. - Start the wrapper with a stdio server using expanded command arguments: - /path/mcp-context-protector.sh --command-args DOWNSTREAM_SERVER_COMMAND ARG1 ARG2 - This is useful if your MCP client mangles the stdio command by concatenating arguments into a single string. - Start the wrapper with an HTTP server: - /path/mcp-context-protector.sh --url DOWNSTREAM_SERVER_URL If you need ANSI escape character sanitization or to inspect ANSI codes visually, use the --visualize-ansi-codes option to replace escape sequences with readable markers.

Configuration examples

# Start the wrapper with an stdio server
/path/mcp-context-protector.sh --command "DOWNSTREAM_SERVER_COMMAND ARG1 ARG2"

# Start the wrapper with an stdio server (alternative)
/path/mcp-context-protector.sh --command-args DOWNSTREAM_SERVER_COMMAND ARG1 ARG2

# Start the wrapper with an HTTP server
/path/mcp-context-protector.sh --url DOWNSTREAM_SERVER_URL

Management of MCP JSON and review commands

The wrapper can manage MCP JSON configuration files to wrap existing MCP servers in context protection. Use the CLI to add or remove the wrapper from MCP server configurations. You can also review and approve changes to a server configuration with --review-server and review all unapproved servers with --review-all-servers.

Notes and best practices

Place the full path to the wrapper launcher in your MCP client configuration to avoid issues when clients replace the PATH environment variable. When using --command-args, be mindful of shell metacharacters and escaping to prevent unintended command interpretation.

Security risks and controls

Critical risks include line jumping, rug pulls, ANSI control character manipulation, and other prompt injection attacks. Implement protective measures such as server configuration pinning, guardrail scanning, and quarantining of suspicious responses to mitigate these risks.

Usage overview

This guide covers how to use the wrapper with a downstream MCP server, how to start the wrapper, how to approve or review server configurations, and how to enable guardrails for tool responses. It also describes how to manage MCP JSON files and how to review quarantined tool outputs when protective checks trigger quarantines.

Tools and capabilities

Access to features such as trust-on-first-use pinning, automatic blocking of unapproved configuration changes, guardrail scanning and quarantining of tool responses, ANSI control character sanitization, and assisted editing of mcp.json files gives you a comprehensive security layer for MCP servers.

Available tools

review-server

Review and approve changes to a specific server configuration (must be used with --command, --command-args, --url or --sse-url)

review-quarantine

Review quarantined tool responses to decide whether to release or reject the content

quarantine_release

Retrieve a quarantined tool response for continued use after approval

guardrail_scanning

Apply guardrail checks to tool responses and flag potential prompt injection for quarantine