@volji/protect

Runtime AI agent security proxy. Wraps any MCP executor and reports every tool call to the Volji audit pipeline — blast radius scoring, immutable traces, HITL queuing.

Install

npm install @volji/protect

Requires Node.js 18+ and a Volji license key. Start a free trial at volji.io.

Quickstart

import { wrapWithVolji } from '@volji/protect'

const protect = wrapWithVolji(myMcpServer, { licenseKey: 'VOLJI-PT-xxxxxxxxxxxxxxxx-xxxxxxxx' })
const result = await protect.call('write_file', { path: './out.json', content: data }, { agentId: 'my-agent', sessionId: 'sess-001' })

That's it. Every call is scored and logged in your Volji dashboard with zero latency overhead — telemetry is fire-and-forget.

API

wrapWithVolji(server, options)

| Parameter | Type | Description | |-----------|------|-------------| | server | { call(tool, args): Promise<unknown> } | Your MCP executor or client | | options.licenseKey | string | Volji license key (from your dashboard) | | options.apiUrl | string | Override API URL (default: Volji production) |

Returns a ProtectedServer with one method:

protect.call(tool, args, context)

| Parameter | Type | Description | |-----------|------|-------------| | tool | string | MCP tool name | | args | object | Tool arguments | | context.agentId | string | Stable identity of the calling agent | | context.sessionId | string | Conversation or workflow session ID | | context.parentAgentId | string? | Orchestrator agent ID (for swarm detection) |

The call is never blocked — observe-only in v0.1. The actual tool executes and results pass through unchanged. Errors are re-thrown after the trace is recorded.

Blast radius scoring

Each tool call is scored 0–100 based on tool name patterns:

| Pattern | Score | |---------|-------| | Read-only (default) | +5 | | File writes (write_file, delete_file, ...) | +30 | | Database mutations (execute_sql, insert_record, ...) | +25 | | External egress (http_request, send_email, webhook, ...) | +20 |

Scores above 75 = critical, 50–74 = high, 25–49 = medium, below 25 = low.

Full-featured usage (AuditProxy)

For HITL, permission enforcement, swarm detection, and blocking, use the lower-level AuditProxy class directly:

import { AuditProxy } from '@volji/protect'

const proxy = new AuditProxy({
  executor:         myMcpClient,
  agentPermissions: new Map([['my-agent', ['read:files', 'write:files']]]),
  toolPermissions:  new Map([['write_file', ['write:files']]]),
  blockCritical:    true,
  hitl: {
    requireApprovalAbove: 'high',
    mode: 'async',
    onApprovalRequired: async (entry) => {
      // post to Slack, Zendesk, etc.
      return awaitHumanDecision(entry)
    },
  },
  onTrace: async (entry) => {
    console.log(entry.decision, entry.blastRadius.score)
  },
})

const result = await proxy.call({
  tool:      'write_file',
  arguments: { path: './report.csv', content: csvData },
  agentId:   'report-agent',
  sessionId: 'weekly-run-001',
})

Environment variable

Set VOLJI_DEBUG=1 to log telemetry send failures to stderr (silenced by default).

License

Commercial. See volji.io/terms.