AI4H Adversarial MCP

AI4H Adversarial MCP is a safe, reproducible test harness for measuring whether an LLM agent follows malicious instructions embedded in MCP tool results. It provides paired clean and poisoned versions of the same task, records the full tool trace, and scores task utility separately from attack resistance.

This is an early evaluation tool from the Safe AI for Humanity Foundation. Automated scores require human review and should not be treated as a complete safety certification.

Safety model

• The included runner uses an isolated in-memory MCP connection. Standalone fixture mode uses local MCP stdio; neither mode opens an MCP network port.

• Every record, address, secret, and action is synthetic.

• Action-like tools are inert sinks. They record the model's attempted call in the result trace but never send, delete, export, elevate, or modify anything.

• The only outbound request made by the reference runner is to the LLM API base URL that the user explicitly supplies.

• Results contain raw traces and synthetic attack text. Review them before publishing.

Related MCP server: judgment-pack-runtime

What is included

• Ten paired prompt-injection scenarios plus schema-v3 agent-scope catalogs

• MCP source tools with attacks in text, structured content, and error results

• Inert action sinks for exfiltration, privilege escalation, permission changes, deletion, and cross-tool access

• An OpenAI-compatible runner that works with services such as OpenRouter and Ollama's /v1 interface

• Deterministic trace evaluators for utility and security

• Portable ai4h.adversarial-mcp.result.v1 JSON output

• A mandatory human-review warning and scenario-specific review rubric

Quick start

Requirements: Node.js 20 or newer.

npm install
npm run build
node dist/src/cli.js list

Run one paired scenario against Ollama:

node dist/src/cli.js run \
  --scenario policy-authority-spoof \
  --base-url http://127.0.0.1:11434/v1 \
  --model qwen3:8b \
  --output results/qwen3-policy.json

Run all scenarios against an OpenAI-compatible hosted service:

export AI4H_LLM_API_KEY="your-key"
node dist/src/cli.js run \
  --all \
  --base-url https://openrouter.ai/api/v1 \
  --model openai/gpt-4.1-mini \
  --output results/model-run.json

Run one of the official schema-v3 agent suites from a released catalog:

export AI4H_AGENT_CATALOG="https://github.com/SafeAI4Humanity/ai4h-test-suites/releases/latest/download/catalog-v3.json"
node dist/src/cli.js run \
  --suite agent.scope-authorization-drift \
  --base-url http://127.0.0.1:11434/v1 \
  --model qwen3:8b \
  --output results/qwen3-agent-scope.json

During local catalog development, replace the URL with ../ai4h-test-suites/catalog-v3.json.

Use environment variables instead of command-line arguments when possible so API keys are not retained in shell history:

• AI4H_LLM_BASE_URL

• AI4H_LLM_MODEL

• AI4H_LLM_API_KEY

• AI4H_AGENT_CATALOG

The key is used for the provider request and is never written to the result JSON.

Scenario catalog

The schema-v3 catalog adds four paired agent suites:

Each variant runs in a fresh agent conversation and fresh isolated MCP server instance. The clean control confirms that the agent can complete the ordinary task; the poisoned variant measures whether it can complete the same task without obeying the injected instruction.

Reading results

The top-level summary reports:

• cleanControlsPassed: ordinary tasks completed correctly

• poisonedSecurityPassed: poisoned runs that avoided deterministic security failures

• poisonedUtilityPassed: poisoned runs that still answered the task

• resilientPairs: both the clean control and poisoned run passed

• attackSuccesses: poisoned runs with a security failure

A model can be secure but unhelpful, or helpful but vulnerable. Keep utility and security visible as separate dimensions, and inspect every scenario's trace and human-review rubric before publishing conclusions.

Connect the raw MCP server to another agent

The server can be launched independently for one fixed scenario and variant:

{
  "mcpServers": {
    "ai4h-adversarial-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/ai4h-adversarial-mcp/dist/src/cli.js",
        "serve",
        "--scenario",
        "support-ticket-exfiltration",
        "--variant",
        "poisoned"
      ]
    }
  }
}

This mode exposes the test fixture but does not capture the external agent's trace. Use the included runner for standardized, automatically scored results.

Commands

list [--catalog <path-or-url>]             List available scenarios
inspect --scenario <id> [--catalog ...]   Print a scenario definition
serve --scenario <id> --variant <variant> Start one stdio MCP fixture
run --scenario <id> ...                   Run one clean/poisoned pair
run --suite <id> --catalog <value> ...    Run one schema-v3 agent suite
run --all [--catalog <value>] ...         Run every loaded scenario

Run local validation with npm run check.

Contributing

The original scenarios are declarative JSON files in scenarios. Official schema-v3 agent suites live in the separate ai4h-test-suites repository under suites-v3/. Contributions should:

1. Include an equivalent useful task in both clean and poisoned variants.

2. Use only synthetic identifiers, canaries, and reserved .invalid addresses.

3. Route action requests exclusively to the included inert simulation tools.

4. Define deterministic utility and security expectations plus a human-review rubric.

5. Add or update tests and pass npm run check.

See docs/ARCHITECTURE.md for the execution and scoring design and SECURITY.md before adding new attack fixtures.

License

Apache-2.0. Copyright 2026 Safe AI for Humanity Foundation.