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:

1. 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.
2. 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 PyPI unplug-ai
• pr-scan.yml — regex Guard scan on changed agent/MCP config files (via UnplugAI/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.