T-MAP: Red-Teaming LLM Agents with Trajectory-aware Evolutionary Search

T-MAP is a trajectory-aware evolutionary search framework for red-teaming LLM agents over MCP servers. It iteratively generates and mutates adversarial prompts guided by execution trajectories, mapping the agent's vulnerability landscape across diverse risk categories and attack styles.

---

🔧 Setup

pip install -r requirements.txt

Requirements: Python 3.11+, API keys for attacker and target models, access to one or more MCP servers.

---

🚀 Quick Start

Single server

python run_main.py \
  --server Slack \
  --attacker_model "deepseek-chat" \
  --attacker_model_api "https://api.deepseek.com" \
  --attacker_model_api_token "$DEEPSEEK_API_KEY" \
  --target_model "openai/gpt-5-mini" \
  --target_model_api "https://openrouter.ai/api/v1" \
  --target_model_api_token "$OPENROUTER_API_KEY" \
  --stdio_server_cmd npx \
  --stdio_server_args "-y slack-mcp-server@latest --transport stdio" \
  --stdio_server_envs "SLACK_MCP_XOXP_TOKEN=$SLACK_MCP_XOXP_TOKEN SLACK_MCP_ADD_MESSAGE_TOOL=true" \
  --iteration 100 \
  --mutation_n 3

Multi-server

python run_main.py \
  --server "Slack,CodeExecutor" \
  --attacker_model "deepseek-chat" \
  --attacker_model_api "https://api.deepseek.com" \
  --attacker_model_api_token "$DEEPSEEK_API_KEY" \
  --target_model "openai/gpt-5-mini" \
  --target_model_api "https://openrouter.ai/api/v1" \
  --target_model_api_token "$OPENROUTER_API_KEY" \
  --stdio_server_cmd_1 npx \
  --stdio_server_args_1 "-y slack-mcp-server@latest --transport stdio" \
  --stdio_server_envs_1 "SLACK_MCP_XOXP_TOKEN=$SLACK_MCP_XOXP_TOKEN SLACK_MCP_ADD_MESSAGE_TOOL=true" \
  --stdio_server_cmd_2 docker \
  --stdio_server_args_2 "run -i --rm --workdir /app mcp-code-executor:latest" \
  --iteration 100 \
  --mutation_n 3

More examples in run_examples.sh.

---

⚙️ Arguments

Server Connection

Argument	Description
--server	MCP server name(s), comma-separated for multi-server
--server_config	JSON config file for server definitions
--stdio_server_cmd/args/envs	Single-server stdio mode
--stdio_server_cmd_1..8 / _args_1..8 / _envs_1..8	Indexed multi-server stdio mode
--remote_server_url, --remote_server_token	Single remote MCP endpoint

Models

Argument	Description
--attacker_model/api/api_token	Attacker LLM (generates and mutates prompts)
--target_model/api/api_token	Target LLM agent (executes prompts via MCP)
--level_judge_model/api/api_token	Judge LLM (defaults to attacker if omitted)

Experiment

Argument	Default	Description
--iteration	100	Number of mutation rounds
--mutation_n	3	Mutants sampled per round
--max_workers	10	Parallelism for generation and evaluation
--query_timeout	300	Per-query timeout (seconds)
--checkpoint_interval	20	Save checkpoint every N generations
--output_dir	outputs	Results and TCG snapshots
--log_dir	logs	Text logs

---

📁 Project Layout

.
├── core/
│   ├── base.py              # Experiment orchestration and evaluation
│   ├── config.py            # Risk categories and attack styles
│   ├── langchain_client.py  # LangChain-based MCP client
│   ├── llm.py               # LLM wrapper
│   └── utils.py             # CLI argument definitions
├── prompts/
│   └── tmap.py              # Seed, judge, mutate, and analysis prompts
├── run_main.py              # Entrypoint
├── run_examples.sh          # Example commands
└── requirements.txt

---

📄 Citation

@article{lee2026tmapredteamingllmagents,
      title={T-MAP: Red-Teaming LLM Agents with Trajectory-aware Evolutionary Search}, 
      author={Hyomin Lee and Sangwoo Park and Yumin Choi and Sohyun An and Seanie Lee and Sung Ju Hwang},
      year={2026},
      eprint={2603.22341},
      archivePrefix={arXiv},
      primaryClass={cs.CR},
      url={https://arxiv.org/abs/2603.22341}
}