Medusa Documentation

Complete guide to deploying, configuring, and operating the Medusa endpoint security platform for MCP infrastructure.

How It Works

Medusa is an endpoint DLP (Data Loss Prevention) platform for Model Context Protocol (MCP) servers. It sits between AI agents (Claude, Codex, Cursor) and the MCP servers they call, intercepting every tool call in real-time.

MCP Client

(Cursor, Claude Code)

▶

MCP Gateway

(local agent)

▶

MCP Server

(GitHub, Slack, Jira, etc.)

▼

Medusa Platform

PoliciesTelemetryAlerts & Reports

The agent runs a lightweight ONNX token-classification model (Medusa Model) directly on the endpoint. It scans every tool call argument and server response for sensitive data across 10 categories — without any data leaving the device.

Getting Started

Deploy the Medusa agent on any macOS, Linux, or Windows endpoint in under a minute.

1. Generate an API Key

Go to Settings in the dashboard and create a new API key.

2. Install the Agent

pipx install medusa-mcp
medusa-agent connect \
  --control-plane https://YOUR_PROJECT.supabase.co \
  --api-key sk-med_YOUR_KEY_HERE

The control plane URL is your Supabase project URL — the agent speaks directly to Supabase Edge Functions, not to the dashboard host. You can copy the exact command for your deployment from the Deploy page in the dashboard.

pipx installs the agent in an isolated venv. The connect step attaches it to your dashboard: creates ~/.medusa/, discovers MCP clients (Claude Desktop, Cursor, Codex), rewrites their configs to route through the proxy, registers with the dashboard, and starts the daemon.

3. Verify Connection

medusa-agent status

The agent should show State: Running with your customer ID and proxied servers. Check the Fleet page to confirm it appears online.

Agent Configuration

Agent configuration is stored at ~/.medusa/agent-config.yaml (permissions: 0600).

Key Fields

Field	Description	Default
api_key	Authentication key for dashboard	(required)
supabase_url	Dashboard backend URL	(set during install)
telemetry_interval_seconds	Event upload frequency	60
policy_sync_interval_seconds	Policy fetch frequency	300
dlp_confidence_threshold	Min confidence for DLP detections	0.5
dlp_model_enabled	Enable ONNX DLP scanning	true
auto_update_enabled	Auto-download new agent versions	true

MCP Client Auto-Discovery

The agent automatically discovers and proxies MCP servers configured in:

Claude Desktop — claude_desktop_config.json
Cursor — .cursor/mcp.json
OpenAI Codex — .codex/config.toml
Claude Code — .claude.json

The agent rewrites each MCP server entry to route through medusa-agent gateway-proxy, preserving the original config as a backup.

DLP Detection

The DLP engine uses a fine-tuned ONNX token-classification model (Medusa Model) that runs entirely on-device. No data is sent to external APIs for scanning.

Detection Categories

Secrets

API keys, tokens, passwords, connection strings

PII

Names, emails, phone numbers, SSNs, addresses

Financial

Credit cards, bank accounts, transactions

Health / PHI

Medical records, diagnoses, prescriptions

Injection

Prompt injection, jailbreak attempts

Source Code

Code snippets, function definitions

Legal

Contracts, legal opinions, litigation

HR / Employment

Reviews, salary, termination data

Insurance

Policy details, claims, underwriting

Business

Trade secrets, M&A, strategy docs

How Scanning Works

Every MCP tool call is intercepted by the gateway proxy. The DLP scanner extracts text from tool arguments, server responses, and resource content. The Medusa Model classifies each token with BIO labels (B-SECRET, I-SECRET, B-PII, I-PII, etc.) and merges contiguous tokens into detected spans with confidence scores.

Custom regex patterns can be added via the Policy Manager for organization-specific formats (internal IDs, proprietary tokens).

Policy Engine

Policies are configured in the dashboard and synced to agents every 5 minutes. They control what the proxy allows, blocks, redacts, or coaches.

Policy Scopes

Global — applies to all agents
Agent — applies to a specific agent
Group — applies to agents with a specific tag

Policy Controls

Control	Description
Server Blocklist	Block specific MCP servers by name
Server Allowlist	Only allow listed servers (whitelist mode)
Tool Blocklist	Block exact tool names or glob patterns
Argument Rules	Inspect tool arguments with regex patterns
Rate Limiting	Max tool calls per minute per agent
DLP Toggles	Enable/disable detection per category
Redact vs Block	Mask sensitive data or reject the request
Coaching Mode	Send warnings instead of blocking
Injection Protection	Detect and block prompt injection in responses

Verdicts

ALLOW

Forward as-is

BLOCK

Reject with error

REDACT

Mask and forward

COACH

Warn the AI agent

Dashboard

The dashboard provides real-time visibility into all MCP traffic across your agent fleet.

Dashboard

KPI cards, traffic chart, recent verdicts, DLP engine status

Policies

Configure DLP rules, tool blocking, argument inspection, rate limits

DLP Findings

Browse detections by category, view incident details with before/after content

Fleet

Monitor agents, MCP server inventory, health metrics, push updates

Settings

API keys, cloud integration, alerting channels, auto-update config

Profile

Account info, security credentials, fleet access, danger zone actions

API Reference

The agent communicates with the dashboard via Supabase Edge Functions. All endpoints require a Bearer token (API key).

POST/functions/v1/gateway-events

Upload telemetry events from the agent. Returns update directives (target_version, auto_update_enabled).

GET/functions/v1/gateway-policy

Fetch the resolved policy for this agent. Supports ETag caching (If-None-Match → 304). Returns HMAC-signed policy.

POST/functions/v1/agent-register

GET/functions/v1/agent-update

Check for available agent updates. Returns download URL and checksum.

Authentication

Authorization: Bearer sk-med_YOUR_API_KEY

API keys are generated in the Settings page. Keys are hashed with SHA-256 — the full key is only shown once at creation time.

Security

Medusa is built security-first. The agent runs with minimal privileges and all sensitive data is protected.

File Permissions

~/.medusa/ directory is 0700, config and database are 0600 (owner-only). API keys never stored in plaintext logs.

Model Integrity

The Medusa Model is verified via SHA-256 checksum against the manifest on every load. Tampered models are rejected.

Inference Safety

10-second timeout on model inference prevents adversarial inputs from hanging the proxy. Messages over 10MB are dropped.

Policy Signing

Policies are signed with HMAC-SHA256 by the edge function. The agent verifies the signature before applying — MITM injection is blocked.

Atomic Config Writes

MCP client configs are written atomically (temp file → rename) to prevent corruption on crash.

ReDoS Protection

Custom regex patterns are tested with a 1-second timeout before activation. Vulnerable patterns are rejected.

Agent Identity Validation

The gateway-events edge function verifies that the agent_id belongs to the authenticated customer before accepting events.