MCP server

Opfor can run as an MCP server, exposing its workflow as tools that any MCP-compatible assistant (Cursor, Claude Desktop, Windsurf) can call. Your assistant runs a full red-team from chat — no terminal required.

This is different from attacking an MCP server as a target. Here, opfor is the MCP server. To test an MCP server, see MCP mode in the CLI.

How it works

The assistant calls three tools in sequence:

opfor_list_evaluators

Discover available evaluator IDs and suites. Call this first when you haven’t named specific evaluators.

opfor_setup

Configure a target and write opfor.config.json. Returns the config path.

opfor_run

Generate attacks on the fly, run them, judge responses, and write HTML + JSON reports.

No pre-generated attack file is needed — opfor_run handles generation, execution, and reporting in one shot.

Install

git clone https://github.com/KeyValueSoftwareSystems/agent-opfor.git
cd opfor
npm install
npm run build

Or run directly via npx without cloning (see the npx tab above).

Register the server

Cursor
Claude Desktop
npx (recommended)

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-scoped):

{
  "mcpServers": {
    "opfor": {
      "command": "node",
      "args": ["/absolute/path/to/opfor/runners/mcp/dist/index.js"]
    }
  }
}

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "opfor": {
      "command": "node",
      "args": ["/absolute/path/to/opfor/runners/mcp/dist/index.js"]
    }
  }
}

No clone or global install needed:

{
  "mcpServers": {
    "opfor": {
      "command": "npx",
      "args": ["-y", "@keyvaluesystems/agent-opfor-mcp"]
    }
  }
}

The server reads API keys from your project’s .env automatically — no env block needed in the config.

Usage

Once registered, just talk to your assistant:

Red team my chatbot at http://localhost:4000/chat

It calls opfor_list_evaluators → opfor_setup → opfor_run and returns a findings summary in chat, with reports saved to disk.

Tools reference

`opfor_list_evaluators`

No parameters. Returns every evaluator ID, severity, standards map, and all predefined suites.

`opfor_setup`

Configures a run and writes opfor.config.json. Returns the config path to pass to opfor_run.

Target

Parameter	Type	Required	Description
`target_name`	string	Yes	Human-readable name
`target_kind`	`agent` \| `mcp`	Yes	`agent` for HTTP/chatbot, `mcp` for servers

Agent target (target_kind = "agent"):

Parameter	Type	Required	Description
`agent_endpoint`	string	For HTTP	URL to attack
`agent_request_format`	`auto` \| `openai` \| `json`	No	Defaults to `auto`
`agent_api_key_env`	string	No	Env var name holding the target API key (e.g. `TARGET_API_KEY`)
`agent_model`	string	No	Model name sent to the target in the `model` field
`agent_script_path`	string	For scripts	Path to a local `.js`/`.py` script
`agent_description`	string	No	What the agent does
`agent_session_send_in`	`body` \| `header`	No	Where the session id is sent (stateful targets)
`agent_session_send_name`	string	No	Body dot-path or header name for the sent id
`agent_session_receive_in`	`body` \| `header` \| `set-cookie`	No	Where a server-owned target returns its id (enables capture)
`agent_session_receive_name`	string	No	Response dot-path / header / cookie name holding the returned id

Client-owned targets set only agent_session_send_*; server-owned targets (the target returns its own id) also set agent_session_receive_*. See session handling.MCP target (target_kind = "mcp"):

Parameter	Type	Required	Description
`mcp_transport`	`stdio` \| `url`	No	Defaults to `stdio`
`mcp_command`	string	For stdio	Command to start the server
`mcp_args`	string[]	No	Arguments for the command
`mcp_env`	object	No	Env vars for the server process
`mcp_url`	string	For url	Server URL (SSE / Streamable HTTP)

Evaluators, LLM, and run settings

Evaluator selection (pick one):

Parameter	Type	Description
`suite_id`	string	Suite ID (e.g. `owasp-mcp-top10`)
`evaluator_ids`	string[]	Specific evaluator IDs

LLM configuration:

Parameter	Type	Required	Description
`attack_llm`	object	Yes	LLM for generating attacks
`judge_llm`	object	No	LLM for judging (defaults to `attack_llm`)

LLM object: { provider, model, api_key_env, base_url? }.Run settings:

Parameter	Type	Description
`effort`	`adaptive` \| `comprehensive`	Defaults to `adaptive`
`turns`	number (1–10)	Turns per attack; `1` = single-turn (default)
`attack_objective`	string	Free-text mission steering every evaluator’s attacks
`judge_hint`	string	Free-text steering for the judge’s verdict
`business_use_case`	string	Free-text domain/business context for the target agent
`output_dir`	string	Where to write the config (default `.`)
`config_path`	string	Full config path (overrides `output_dir`)

`opfor_run`

Runs the full evaluation from a config produced by opfor_setup.

Parameter	Type	Required	Description
`config_path`	string	Yes	Path to the `opfor.config.json`
`output_dir`	string	No	Report directory (default: config dir)
`effort_override`	`adaptive` \| `comprehensive`	No	Override config effort
`turns_override`	number (1–10)	No	Override config turns
`objective_override`	string	No	Override the attack objective from config
`judge_hint_override`	string	No	Override the judge hint from config
`business_use_case_override`	string	No	Override the business use case from config

API key resolution

The server resolves keys in order:

The env var named in the LLM config’s api_key_env
The provider’s default env var (e.g. OPENAI_API_KEY for openai)

It loads .env from the working directory automatically — keys never go in the MCP config JSON.

Providers

Supported providers and their default env vars.

Get Started

CLI

Browser Extension

Skills

SDK

Evaluators & Suites

Trace-aware Testing

Reference

MCP server

How it works

Install

Register the server

Usage

Tools reference

`opfor_list_evaluators`

`opfor_setup`

`opfor_run`

API key resolution

Providers

​How it works

​Install

​Register the server

​Usage

​Tools reference

​opfor_list_evaluators

​opfor_setup

​opfor_run

​API key resolution

Providers

How it works

Install

Register the server

Usage

Tools reference

`opfor_list_evaluators`

`opfor_setup`

`opfor_run`

API key resolution