Skip to content
Back to search

mcp-context-protector

MCP security wrapper

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/trailofbits--mcp-context-protector/badge.svg)](/listings/trailofbits--mcp-context-protector)

HTML

<a href="/listings/trailofbits--mcp-context-protector"><img src="/api/listings/trailofbits--mcp-context-protector/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Installation:

# 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 make it easier to launch `mcp-context-protector`, we recommend updating `mcp-context-protector.sh` to contain the full path to `uv`. Some MCP clients, including Claude Desktop, replace the `PATH` environment variable with a minimal set of paths when launching MCP servers, which can make your `claude_desktop_config.json` file unwieldy and hard to maintain. Including a full path to `uv` in the launcher helps mitigate this problem.

Now configure your client to run your MCP servers through `mcp-context-protector`, and tool configuration pinning will automatically be enabled. Here's a sample Claude Desktop config:

{
  "mcpServers": {
    "wrapped_acme_server": {
      "command": "/path/to/mcp-context-protector/mcp-context-protector.sh",
      "args": ["--command", "/path/to/node /path/to/acme/server.js"]
    }
  }
}

Alternatively, use `--command-args` to have `mcp-context-protector` concatenate all arguments that follow into one command string:

{
  "mcpServers": {
    "wrapped_acme_server": {
      "command": "/path/to/mcp-context-protector/mcp-context-protector.sh",
      "args": ["--command-args", "/path/to/node", "/path/to/acme/server.js", "--acme-enhanced"]
    }
  }
}

TL;DR: use `--command-args` if your MCP client mangles your stdio server command, but be careful with escaping of shell metacharacters.

Longer explanation: Some clients (including, as of this writing, Cursor) will construct their MCP server commands by concatenating the arguments together into a space-delimited string. That is, `mcp-context-protector.sh --command "cmd arg1 arg2 --arg3"` will become `mcp-context-protector.sh --command cmd arg1 arg2 --arg3`, and `mcp-context-protector` will think `arg1` through `--arg3` are meant as arguments to the wrapper, not to the child command. The `--command-args` option addresses this issue.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 191 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # mcp-context-protector
  2. ## Overview
  3. mcp-context-protector is a security wrapper for MCP servers that addresses risks associated with running untrusted MCP servers, including line jumping, unexpected server configuration changes, and other prompt injection attacks. Implementing these security controls through a wrapper (rather than through a scanner that runs before a tool is installed or by adding security features to an MCP host app) streamlines enforcement and ensures universal compatibility with all MCP apps.
  4. ## Features
  5. - Trust-on-first-use pinning of server configurations
  6. - Automatic blocking of unapproved configuration changes
  7. - Guardrail scanning and quarantining of tool responses
  8. - ANSI control character sanitization
  9. - Assisted editing of `mcp.json` files
  10. ## Quickstart
  11. Installation:
  12. ```
  13. # Install uv
  14. curl -LsSf https://astral.sh/uv/install.sh | sh
  15. # Download mcp-context-protector
  16. git clone https://github.com/trailofbits/mcp-context-protector
  17. # Install dependencies
  18. cd mcp-context-protector
  19. uv sync
  20. ```
  21. To make it easier to launch `mcp-context-protector`, we recommend updating `mcp-context-protector.sh` to contain the full path to `uv`. Some MCP clients, including Claude Desktop, replace the `PATH` environment variable with a minimal set of paths when launching MCP servers, which can make your `claude_desktop_config.json` file unwieldy and hard to maintain. Including a full path to `uv` in the launcher helps mitigate this problem.
  22. Now configure your client to run your MCP servers through `mcp-context-protector`, and tool configuration pinning will automatically be enabled. Here's a sample Claude Desktop config:
  23. ```
  24. {
  25. "mcpServers": {
  26. "wrapped_acme_server": {
  27. "command": "/path/to/mcp-context-protector/mcp-context-protector.sh",
  28. "args": ["--command", "/path/to/node /path/to/acme/server.js"]
  29. }
  30. }
  31. }
  32. ```
  33. Alternatively, use `--command-args` to have `mcp-context-protector` concatenate all arguments that follow into one command string:
  34. ```
  35. {
  36. "mcpServers": {
  37. "wrapped_acme_server": {
  38. "command": "/path/to/mcp-context-protector/mcp-context-protector.sh",
  39. "args": ["--command-args", "/path/to/node", "/path/to/acme/server.js", "--acme-enhanced"]
  40. }
  41. }
  42. }
  43. ```
  44. TL;DR: use `--command-args` if your MCP client mangles your stdio server command, but be careful with escaping of shell metacharacters.
  45. Longer explanation: Some clients (including, as of this writing, Cursor) will construct their MCP server commands by concatenating the arguments together into a space-delimited string. That is, `mcp-context-protector.sh --command "cmd arg1 arg2 --arg3"` will become `mcp-context-protector.sh --command cmd arg1 arg2 --arg3`, and `mcp-context-protector` will think `arg1` through `--arg3` are meant as arguments to the wrapper, not to the child command. The `--command-args` option addresses this issue.
  46. ## Security risks and controls
  47. | Risk | Relevant control |
  48. | -------- | ------- |
  49. | Line jumping | Server configuration blocking, approval and pinning; guardrail evaluation of server instructions and tool descriptions |
  50. | Server configuration changes/rug pulls | Server configuration pinning |
  51. | User deception through ANSI control characters | ANSI control character sanitization |
  52. | Other prompt injection attacks | Tool response guardrails and quarantining |
  53. ## Server configuration pinning
  54. mcp-context-protector uses a trust-on-first use pinning system for MCP server configurations. Any deviation from the approved/known-good server configuration will block downstream tool calls until the user explicitly approves the changed server configuration. Server approval is handled through mcp-context-protector's command-line interface.
  55. Server configuration comparisons compare server instructions, tool descriptions, and tool input schemas to determine whether a server configuration is equivalent to any approved one. Comparisons are semantic and ignore irrelevant factors like tool order and parameter order.
  56. The database of server configurations is stored in a JSON-encoded file whose default location is `~/.mcp-context-protector/servers.json`. If a server configuration is in that file, it's approved and will run without tool blocking and without requiring user approval. The wrapper server checks downstream server configurations as soon as the connection is initiated and again whenever the wrapper receives a notification that the downstream server's tools have changed (`notifications/tools/list_changed`).
  57. Servers are uniquely identified in this file by their type and an identifier, which is either a URL or the command string that launches the server. mcp-context-protector does not care about changes to a server's name in the host app's configuration (such as the `claude_desktop_config.json` file). If the command string (or URL) is unchanged, it's treated as the same server, and if the command string has changed, even in inconsequential ways, it's treated as a different server, and the configuration will need to be approved exactly as if mcp-context-protector were seeing the server for the first time.
  58. To approve a server's configuration and allow the host app to connect to it, run the CLI app with the argument `--review-server`. The wrapper server will connect to the downstream server, retrieve its configuration, and display it in the shell. If you approve the configuration, it will be added to the database, and you can restart your host app to use it normally.
  59. ## Tool response guardrails and quarantine
  60. If mcp-context-protector is launched with a guardrail provider, it will use the chosen provider to scan every tool response for prompt injection attacks. If an attack is detected, the response will be saved in a quarantine database at `~/.mcp-context-protector/quarantine.json`. The host app will receive a response that includes the guardrail provider's output.
  61. To review the response and release it from the quarantine, run the app with the argument `--review-quarantine`, optionally with the `--quarantine-id <ID>` argument to specify which quarantined response you want to review. The app will then display the tool call and response in the shell and let you review it. If you approve the response, the LLM app can then use the `quarantine_release` tool to retrieve the response and continue as normal.
  62. ## Configuring mcp-context-protector
  63. `mcp-context-protector` is packaged with `uv` and can be run with `uv run mcp-context-protector`. To start a server through the wrapper, run the `mcp-context-protector.sh` launcher script with the arguments `--command <COMMAND>`, `--command-args <CMD> <ARG1> <ARG2>` or `--url <URL>`:
  64. ```
  65. # Start the wrapper with an stdio server
  66. /path/mcp-context-protector.sh --command "DOWNSTREAM_SERVER_COMMAND ARG1 ARG2"
  67. # Start the wrapper with an stdio server (alternative)
  68. /path/mcp-context-protector.sh --command-args DOWNSTREAM_SERVER_COMMAND ARG1 ARG2
  69. # Start the wrapper with an HTTP server
  70. /path/mcp-context-protector.sh --url DOWNSTREAM_SERVER_URL
  71. ```
  72. If your downstream server requires the older SSE transport, use `--sse-url <URL>`.
  73. To include support for tool response scanning, include the `--guardrail-provider` argument:
  74. ```
  75. mcp-context-protector.sh --command DOWNSTREAM_SERVER_COMMAND --guardrail-provider LlamaFirewall
  76. ```
  77. Review functions:
  78. ```
  79. mcp-context-protector.sh --review-all-servers
  80. mcp-context-protector.sh --review-quarantine --quarantine-id <ID>
  81. ```
  82. ## Management of mcp.json files
  83. `mcp-context-protector` can also help add the wrapper server to any existing configuration files that follow the `mcp.json` standard. To edit a specific file, use the `--manage-all-mcp-json` flag. All configuration files found at known locations on the filesystem will automatically be detected. Use the CLI interface to add and remove the wrapper from MCP servers. Configuration files located in project directories or code repositories will not be detected automatically. To edit a project's MCP configuration file, or any other specified file, use `--manage-mcp-json-file FILENAME`.
  84. The following MCP clients' configuration files will automatically be detected:
  85. * Claude Code
  86. * Claude Desktop
  87. * Continue.dev
  88. * Cursor
  89. * Visual Studio Code
  90. * Windsurf
  91. ## Usage
  92. ```
  93. usage: mcp-context-protector [-h] [--command COMMAND] [--command-args COMMAND_ARGS [COMMAND_ARGS ...]] [--url URL] [--sse-url SSE_URL] [--list-guardrail-providers]
  94. [--review-server] [--review-quarantine] [--review-all-servers] [--manage-mcp-json-file MANAGE_MCP_JSON_FILE] [--manage-all-mcp-json]
  95. [--wrap-mcp-json CONFIG_FILE] [--environment ENV] [--server-config-file SERVER_CONFIG_FILE] [--guardrail-provider GUARDRAIL_PROVIDER]
  96. [--visualize-ansi-codes] [--quarantine-id QUARANTINE_ID] [--quarantine-path QUARANTINE_PATH]
  97. options:
  98. -h, --help show this help message and exit
  99. --server-config-file SERVER_CONFIG_FILE
  100. The path to the server config database file (default: ~/.mcp-context-protector/servers.json)
  101. --guardrail-provider GUARDRAIL_PROVIDER
  102. The guardrail provider to use for checking server configurations
  103. --visualize-ansi-codes
  104. Make ANSI escape codes visible by replacing escape characters with 'ESC'
  105. --quarantine-id QUARANTINE_ID
  106. The ID of a specific quarantined response to review
  107. --quarantine-path QUARANTINE_PATH
  108. The path to the quarantine database file (default: ~/.mcp-context-protector/quarantine.json)
  109. --command COMMAND Start a wrapped server over the stdio transport using the specified command
  110. --command-args COMMAND_ARGS [COMMAND_ARGS ...]
  111. Start a wrapped server over the stdio transport using the specified command arguments (space-separated). Supports arguments with dashes (e.g.
  112. docker run --rm -i)
  113. --url URL Connect to a remote MCP server over streamable HTTP at the specified URL
  114. --sse-url SSE_URL Connect to a remote MCP server over SSE at the specified URL
  115. --list-guardrail-providers
  116. List available guardrail providers and exit
  117. --review-server Review and approve changes to a specific server configuration (must be used with --command, --command-args, --url or --sse-url)
  118. --review-quarantine Review quarantined tool responses
  119. --review-all-servers Review all unapproved server configurations
  120. --manage-mcp-json-file MANAGE_MCP_JSON_FILE
  121. Interactively manage an MCP JSON configuration file
  122. --manage-all-mcp-json
  123. Find and manage all MCP JSON configuration files from known locations
  124. --wrap-mcp-json CONFIG_FILE
  125. Wrap all MCP servers in the specified JSON config file with context-protector
  126. --environment ENV, -e ENV
  127. Select specific environment/profile for multi-environment config
  128. ```
  129. ## License
  130. ```
  131. Copyright 2025 Trail of Bits
  132. Licensed under the Apache License, Version 2.0 (the "License");
  133. you may not use this file except in compliance with the License.
  134. You may obtain a copy of the License at
  135. http://www.apache.org/licenses/LICENSE-2.0
  136. Unless required by applicable law or agreed to in writing, software
  137. distributed under the License is distributed on an "AS IS" BASIS,
  138. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  139. See the License for the specific language governing permissions and
  140. limitations under the License.
  141. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.