Unplug MCP
Model Context Protocol server for Unplug — LLM defense layer.
Integrates with Claude Code, Cursor, Windsurf, and any MCP-compatible client.
Installation
pip install unplug-mcp
Optional ML span scanner:
pip install "unplug-mcp[ml]"
Run without a prior install (recommended for MCP clients):
uvx unplug-mcp
See examples/mcp.json for copy-paste client configs.
Usage
Local mode (default)
Add to your MCP client configuration:
Cursor — .cursor/mcp.json or Settings → MCP:
{
"mcpServers": {
"unplug": {
"command": "unplug-mcp",
"args": []
}
}
}
With uvx (no pip install):
{
"mcpServers": {
"unplug": {
"command": "uvx",
"args": ["unplug-mcp"]
}
}
}
Claude Desktop — claude_desktop_config.json:
{
"mcpServers": {
"unplug": {
"command": "unplug-mcp",
"args": []
}
}
}
Hosted server mode
Point at your Unplug API (same wire format as Guard(mode="server")):
{
"mcpServers": {
"unplug": {
"command": "unplug-mcp",
"env": {
"UNPLUG_MODE": "server",
"UNPLUG_SERVER_URL": "https://api.unplug-ai.org/v1",
"UNPLUG_API_KEY": "up_live_xxx"
}
}
}
}
Configuration
| Variable | Default | Purpose |
|---|---|---|
UNPLUG_MODE |
local |
local or server |
UNPLUG_CONFIG |
— | Path to Unplug TOML config |
UNPLUG_SERVER_URL |
— | Hosted API base URL (server mode) |
UNPLUG_API_KEY |
— | API key (server mode) |
UNPLUG_ACTIVE_MODEL |
— | ML model name override |
UNPLUG_MODEL_PATH |
— | Local ML checkpoint path |
Tools
| Tool | Purpose |
|---|---|
scan_text |
Scan text for injection/leakage (default source=retrieved, session-tainting) |
scan_tool_result |
Scan tool output before the agent reads it |
check_destructive |
Gate side-effect tool calls |
wrap_untrusted_content |
Boundary markers + scan for RAG/web content |
session_status |
Session taint state for agent hardening |
notify_taint_source |
Record an untrusted content source in session state |
notify_trusted_user_turn |
Host-only: clear session taint after a real user message |
scan_text source parameter
scan_text defaults to source="retrieved" so scans participate in session taint and
check_destructive can require human review after untrusted input (fail-closed for agent hosts).
source |
Session taint | When to use |
|---|---|---|
retrieved (default) |
Yes | RAG chunks, docs, or any content when provenance is unclear |
user, system |
No (clean session only) | Host-attested direct user or system messages only |
web_fetch, email, file, external, … |
Yes | Mapped to retrieved; prefer wrap_untrusted_content for web/RAG |
Once the session is tainted, later scan_text calls cannot downgrade gates by claiming
source="user". Only the host may clear taint via notify_trusted_user_turn (see below).
Session taint reset (host-only)
notify_trusted_user_turn replaces the old reset_session_taint tool. It requires
confirm_trusted_user_turn=true; without it the session stays tainted (fail-closed).
Threat model: Prompt injection in untrusted content may instruct an agent to call
taint-reset tools. Agents must never call notify_trusted_user_turn after reading
retrieved, web, email, or tool output. MCP hosts (Cursor, Claude Desktop) should:
- Wire
notify_trusted_user_turn(confirm_trusted_user_turn=true)to user-turn hooks (when a new human message arrives), not to agent tool lists. - Omit this tool from configs where the agent can invoke every registered MCP tool.
Naive calls without confirmation leave destructive tools gated at review.
All tools fail closed: scan failures return safe=false and action=block so agents never proceed on errors. session_status and taint helpers conservatively mark the session tainted when they cannot read state.
CI
ci.yml— lint + pytest against PyPIunplug-aipr-scan.yml— regex Guard scan on changed agent/MCP config files (viaUnplugAI/unplug-scan-action@v1)publish-pypi.yml— PyPI release on GitHub Release or manual dispatch
Development
uv sync --extra dev
uv run pytest -q
uv run unplug-mcp
Local SDK path override (monorepo): tool.uv.sources in pyproject.toml.
Distribution
See MARKETPLACE.md for MCP registry listing steps and PUBLISH.md for PyPI release workflow.
Related
- unplug-ai — Python SDK
- unplug-scan-action — GitHub Actions agent scan
- unplug-server — hosted scan API
License
Apache-2.0 — see LICENSE.
Metadata
Release files for unplug-mcp 0.1.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| unplug_mcp-0.1.6.tar.gz | 135.8 kB | Without provenance | Details for unplug_mcp-0.1.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| unplug_mcp-0.1.6-py3-none-any.whl | Python 3 | none | any | Details for unplug_mcp-0.1.6-py3-none-any.whl |
Total release size: 163.8 kB
Release files / unplug_mcp-0.1.6.tar.gz
| Download URL | unplug_mcp-0.1.6.tar.gz |
|---|---|
| Size | 135.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c47a404c25deb83b2e8ec94d40bcc5eef10780ca3f53630318bf5124126c061e
|
|
BLAKE2b-256 checksum How to use checksums |
0a144c5dfadb2c2b5d0de73fce960fc0a4507a3f36493df21938f6268a433c54
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.14
|
Release files / unplug_mcp-0.1.6-py3-none-any.whl
| Download URL | unplug_mcp-0.1.6-py3-none-any.whl |
|---|---|
| Size | 28.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
62b34eb46997209a0272c5274b8fe271e7b57771f45ec5e4540e2094eb74fbdd
|
|
BLAKE2b-256 checksum How to use checksums |
7f186b8b1fdb4d916debb27e792b2188c4e3f72c0cc8f209a1067cef1d1a7196
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.14
|
Security for unplug-mcp 0.1.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.