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

Tools

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).

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.