Quick Start

Get Navil running in under 60 seconds.

1Install Navil

Terminal
# Core package
pip install navil

# With cloud dashboard
pip install navil[cloud]

# With LLM-powered analysis
pip install navil[llm]

# Everything
pip install navil[all]

2Scan your MCP config

Terminal
# Analyze your MCP config for vulnerabilities
navil scan config.json
config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": { "API_KEY": "your-api-key" }
    }
  }
}

3Start the security proxy

Terminal
# Proxy all MCP traffic through Navil
navil proxy --target http://localhost:3000

# With auth enforcement
navil proxy --target http://localhost:3000 --require-auth

That's it. Every tool call now passes through Navil's inspection engine. All traffic is logged to the dashboard for monitoring.

4Define access policies (optional)

policies.yaml
policies:
  - agent: "data-agent"
    rules:
      - tool: "database_query"
        action: "allow"
        conditions:
          max_rate: 100
          data_sensitivity: "low"
      - tool: "*"
        action: "deny"

  - agent: "file-agent"
    rules:
      - tool: "read_file"
        action: "allow"
        conditions:
          max_rate: 50
      - tool: "write_file"
        action: "rate_limit"
        conditions:
          max_rate: 10
          time_window: 60
      - tool: "delete_file"
        action: "deny"

CLI Commands

The Navil CLI manages your proxy, configuration, and cloud connection.

navil scan <config.json>

Analyze MCP configuration for security vulnerabilities (hardcoded credentials, insecure protocols, malicious patterns)

navil proxy

Start the security proxy — intercepts and inspects MCP traffic in real-time with JSON-RPC inspection

--target <url> --port <port> --verbose --require-auth

navil cloud serve

Launch the Navil cloud dashboard for visual security monitoring

--host <addr> --port <port> --no-demo

Example: proxy with auth
navil proxy --target http://localhost:3000 --port 9090 --require-auth

# All MCP traffic is now intercepted, inspected, and logged
# Access the dashboard at http://localhost:8484
Example: launch the dashboard
navil cloud serve --host 0.0.0.0 --port 8484

# Dashboard available at http://localhost:8484
# Real-time monitoring of agents, alerts, and policy decisions

API Reference

Base URL: https://api.navil.dev — All endpoints return JSON. Auth via JWT or API Key header.

Authentication

Register an organization or authenticate to receive a JWT token.

POST/v1/auth/registerPublic

Create org + admin user, returns JWT

POST/v1/auth/loginPublic

Authenticate with email & password

Register
POST /v1/auth/register
{
  "email": "admin@acme.io",
  "password": "secure_password",
  "organization_name": "Acme Corp"
}
Response
{
  "access_token": "eyJhbGci...",
  "token_type": "bearer"
}

Telemetry & Threat Intel

Submit security events from agents and fetch the global threat intelligence feed.

POST/v1/telemetryAPI Key

Submit security events (always 202)

GET/v1/threat-intelAPI Key

Fetch global IP blocklist

Submit event
POST /v1/telemetry
Authorization: Bearer navil_live_abc123...

{
  "agent_id": "worker-3",
  "events": [{
    "type": "prompt_injection",
    "data": {
      "action": "blocked",
      "payload": "ignore previous..."
    }
  }]
}
Response (202)
{ "status": "accepted" }

API Key Management

Create, list, and revoke API keys for your organization.

POST/v1/org/keysJWT

Create API key (shown once)

DELETE/v1/org/keys/:idJWT

Revoke an API key

GET/v1/org/agentsJWT

List all API keys for org

Key format: navil_live_{base62} — stored as SHA-256 hash. Plaintext shown once at creation.

Create key
POST /v1/org/keys
Authorization: Bearer eyJhbGci...

{ "label": "production-agent" }
Response
{
  "id": "key_abc123",
  "key": "navil_live_x7k9m2...",
  "label": "production-agent",
  "created_at": "2026-03-12T..."
}

Agent Nodes

Register agent nodes and maintain heartbeat connections.

POST/v1/nodes/registerAPI Key

Register or update an agent node

POST/v1/nodes/:id/heartbeatAPI Key

Send heartbeat (15min active window)

Nodes inactive for 15+ minutes are freed. Limits: Community 3, Pro 10, Team 50, Enterprise 500.

Register node
POST /v1/nodes/register
Authorization: Bearer navil_live_abc123...

{
  "node_id": "agent-prod-01",
  "hostname": "worker.acme.io",
  "version": "1.2.0"
}

Organization & Dashboard

Manage your organization profile, webhook URLs, and view dashboard stats.

GET/v1/org/meJWT

Get org profile, key count, webhook URLs

PATCH/v1/org/meJWT

Update name, webhook URLs

GET/v1/org/statsJWT

Active agents, events 24h, top anomalies

Update webhooks
PATCH /v1/org/me
Authorization: Bearer eyJhbGci...

{
  "slack_webhook_url": "https://hooks.slack.com/...",
  "discord_webhook_url": "https://discord.com/api/..."
}
Dashboard stats
GET /v1/org/stats

{
  "active_agents": 7,
  "events_24h": 1482,
  "top_anomalies": [
    "prompt_injection",
    "rate_limit_exceeded"
  ]
}

Team Members

List members, send invitations, and manage team access.

GET/v1/org/membersJWT

List all org members

POST/v1/org/invitesJWT Admin

Invite user with role (admin only)

DELETE/v1/org/members/:idJWT Admin

Remove member (admin only)

Invite member
POST /v1/org/invites
Authorization: Bearer eyJhbGci...

{
  "email": "dev@acme.io",
  "role": "member"
}

Analytics

Query time-series event data and top threat breakdowns.

GET/v1/org/analytics/timeseriesJWT

Event counts per day (1-30 days)

GET/v1/org/analytics/top-threatsJWT

Top 10 threat types by count

Time series
GET /v1/org/analytics/timeseries?days=7

{
  "data": [
    { "date": "2026-03-06", "count": 234 },
    { "date": "2026-03-07", "count": 189 },
    { "date": "2026-03-08", "count": 412 }
  ]
}