@priventai/mcp-server

Privent Agent Security as an MCP server — a thin Assist-mode adapter over privent-backend.

Assist vs Enforcement: This package exposes optional tokenize/risk/audit tools. It does not intercept other MCP servers. Mandatory protection of third-party MCP traffic is the MCP Gateway (see docs/adr/0001-mcp-enforcement-model.md). Capability matrix: docs/capability-matrix.md.

Guardrails delete data; Privent turns [email protected] into [EMAIL_001] and can restore it.

5-minute setup (Cursor)

1. Get an AGENT_SDK API key (not EXTENSION).
2. Prefer the published package (npx):

{
  "mcpServers": {
    "privent": {
      "command": "npx",
      "args": ["-y", "@priventai/mcp-server"],
      "env": {
        "PRIVENT_BASE_URL": "https://api.privent.ai",
        "PRIVENT_API_KEY": "sk-..."
      }
    }
  }
}

Local clone (loads .env via the stdio wrapper) is still supported for development. Replace /absolute/path/to/privent-mcp with the absolute path to your clone; MCP clients do not expand ~ or resolve relative paths:

{
  "mcpServers": {
    "privent": {
      "command": "node",
      "args": ["/absolute/path/to/privent-mcp/scripts/run-stdio.mjs"]
    }
  }
}

3. Restart MCP / Cursor → privent_health → privent_tokenize_text → privent_detokenize_text.

On-prem: set PRIVENT_BASE_URL to your backend.

MCP Inspector (recommended on Windows)

STDIO mode is unreliable with Inspector on Windows. Use Streamable HTTP:

pnpm build
pnpm inspect

In the UI: Transport = Streamable HTTP, URL = http://127.0.0.1:8080/mcp → Connect → run privent_health.

Claude Desktop

See examples/claude_desktop_config.json.

Tools (default)

| Tool | Backend | |------|---------| | privent_health | GET /v1/health | | privent_risk_score | POST /v1/risk/score | | privent_tokenize_text | risk (optional) + POST /v1/vault/find-or-create-batch | | privent_detokenize_text | POST /v1/vault/retrieve-batch | | privent_destroy_session | POST /v1/vault/destroy | | privent_audit_events | POST /v1/audit/events |

Preview tools (off until enabled)

Code stays in the tree; tools are not registered unless you set the flag (and the backend is ready):

| Flag | Tools | |------|--------| | PRIVENT_ENABLE_DOCUMENTS=1 | privent_document_* → /v1/documents/jobs* | | PRIVENT_ENABLE_TOOL_EXEC=1 | privent_tool_exec_evaluate → /v1/tool-exec/evaluate | | PRIVENT_ENABLE_DETECT=1 | privent_detect → /detect (+ PRIVENT_EXTENSION_API_KEY) | | PRIVENT_ENABLE_RISK_BATCH=1 | privent_risk_score_batch → /v1/risk/batch |

Resources: privent://health, privent://docs/overview
Prompts: protect_before_llm, risk_gate, hipaa_style_pipeline

Typical flow

1. privent_tokenize_text(text, session_id)
2. LLM / tools work on redacted_text only
3. privent_detokenize_text(redacted, session_id)
4. optional: privent_destroy_session(session_id)

Tip: if risk/ML is slow, pass entities to privent_tokenize_text to skip detection.

Auth rules

• Key type must be AGENT_SDK
• Pass via PRIVENT_API_KEY / .env — never as a tool argument
• HTTP: optional Authorization: Bearer per request (else process env)
• Remote OAuth: PRIVENT_AUTH_MODE=oauth (see docs/oauth-design.md)

Develop

pnpm install
pnpm build
pnpm test
pnpm start          # stdio
pnpm start:http     # Streamable HTTP :8080/mcp
pnpm inspect        # HTTP + Inspector

Docker:

docker compose -f docker-compose.example.yml up --build
# http://localhost:8080/mcp

Env

| Variable | Default | Notes | |----------|---------|-------| | PRIVENT_BASE_URL | https://api.privent.ai | Cloud or on-prem backend | | PRIVENT_API_KEY | — | AGENT_SDK key | | PRIVENT_TIMEOUT_MS | 15000 | General HTTP timeout | | PRIVENT_RISK_TIMEOUT_MS | 60000 | Risk / ML path | | PRIVENT_ENABLE_* | off | Preview tools (documents / tool-exec / detect / risk batch) | | MCP_HOST / MCP_PORT | 0.0.0.0 / 8080 | HTTP transport |

Architecture

No vault crypto / PII detection / policy in this package — HTTP adapter only. Team overview: docs/privent-mcp-project-overview.md. Plan: docs/privent-mcp-server-plan.md.

Roadmap

Tracks are independent. Assist tools live at repo root; enforcement is Gateway package:

| Track | How it ships | Notes | |-------|--------------|--------| | Core text Agent Security | always on (Assist) | health / risk / vault / audit | | OAuth / remote MCP auth | PRIVENT_AUTH_MODE=oauth | Assist HTTP; Gateway GA uses OAuth claims | | Documents / tool-exec / detect / risk batch | PRIVENT_ENABLE_*=1 when backend GA | see capability matrix | | MCP Gateway (enforcement) | packages/gateway — local PoC → hosted GA | pnpm gateway:start:http | | Audit shadow / metrics | optional flags | PRIVENT_AUDIT_SHADOW, PRIVENT_METRICS |

License

Apache-2.0 — see LICENSE.