Installing the `agentox` executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install agentox-cli

It will make the agentox command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall agentox-cli uninstalls.

Back to the crate overview.

Readme

AgentOx

MCP Security & Conformance Auditor — Forged in Rust

AgentOx is the open-source CLI tool for auditing MCP (Model Context Protocol) servers — checking protocol conformance, security surface, and behavioral contracts before any server ships to production.

Installation

cargo install agentox-cli

Or build from source:

git clone https://github.com/CarlosLadd/AgentOx.git
cd AgentOx
cargo install --path crates/agentox-cli

Quick Start

# Audit any MCP server via stdio
agentox audit --stdio "npx -y @modelcontextprotocol/server-filesystem /tmp"

# Output structured JSON for CI pipelines
agentox audit --stdio "npx -y @modelcontextprotocol/server-filesystem /tmp" --format json

# Run only security checks
agentox audit --stdio "npx -y @modelcontextprotocol/server-filesystem /tmp" --only security

Example Output

AgentOx Audit Report
Target: npx -y @modelcontextprotocol/server-filesystem /tmp
Server: filesystem v0.6.2
Protocol: 2025-11-25

[PASS] CONF-001 Initialize returns valid capabilities
[PASS] CONF-002 JSON-RPC 2.0 message structure
[PASS] CONF-003 tools/list returns valid tools
[PASS] CONF-004 Tool inputSchema is valid JSON Schema
[PASS] CONF-005 Malformed request handling
[PASS] CONF-006 Unknown method handling
[PASS] CONF-007 Error code correctness
[PASS] CONF-008 Capability negotiation
[PASS] CONF-009 Protocol version validation
[PASS] CONF-010 Initialized notification handling
[PASS] SEC-001 Prompt-injection echo safety
[PASS] SEC-002 Tool parameter boundary validation
[PASS] SEC-003 Error leakage detection
[PASS] SEC-004 Resource-exhaustion guardrail

Summary
  Total: 14, Passed: 14, Failed: 0
  Duration: 342ms

Conformance Checks (v0.3.0)

ID	Check	Severity on Fail
CONF-001	`initialize` returns valid `protocolVersion`, `capabilities`, `serverInfo`	CRITICAL
CONF-002	All responses are valid JSON-RPC 2.0	HIGH
CONF-003	`tools/list` returns valid tool definitions, no duplicates	HIGH
CONF-004	Tool `inputSchema` is valid JSON Schema with `type: "object"`	HIGH
CONF-005	Malformed requests return errors, server does not crash	CRITICAL
CONF-006	Unknown methods return `-32601`	HIGH
CONF-007	Error codes use standard JSON-RPC values	MEDIUM
CONF-008	Declared capabilities match supported methods	MEDIUM
CONF-009	Protocol version negotiation is handled correctly	HIGH
CONF-010	Initialization lifecycle is handled correctly	LOW

Security Checks (v0.3.0)

ID	Check	Severity on Fail
SEC-001	Prompt-injection style tool input is handled safely	HIGH
SEC-002	`tools/call` parameter boundary validation	HIGH
SEC-003	Error messages do not leak sensitive internals	MEDIUM
SEC-004	Bounded burst/large-input resilience	MEDIUM

CI/CD Integration

AgentOx exits with code 1 when findings are detected and 0 when all checks pass — making it a natural fit for CI pipelines.

GitHub Actions

- name: Audit MCP server
  run: |
    cargo install agentox-cli
    agentox audit --stdio "npx -y @modelcontextprotocol/server-filesystem /tmp" \
      --format json --no-color | tee audit-report.json

- name: Upload audit report
  uses: actions/upload-artifact@v4
  with:
    name: agentox-report
    path: audit-report.json

Shell Script

agentox audit --stdio "npx my-mcp-server" || {
  echo "MCP server failed audit — blocking deploy"
  exit 1
}

Roadmap

Version	Focus	Status
v0.1	Protocol Conformance (10 checks, stdio transport)	✅ Done
v0.2	Security Surface Analysis (initial `SEC-*` suite, stdio transport)	✅ Done
v0.3	HTTP/SSE transport + CI/CD packaging (GitHub Action, Docker image)	📋 Planned
v0.4	Behavioral Contracts (idempotency, schema-output alignment)	📋 Planned
v1.0	Stable API, HTTP/SSE transport, HTML reports	📋 Planned

Architecture

AgentOx is a Cargo workspace with a clean library/CLI separation:

crates/
├── agentox-core/   # Core audit engine (embeddable library)
│   ├── client/     # MCP transport + session
│   ├── checks/     # Audit checks (conformance, security, behavioral)
│   ├── protocol/   # JSON-RPC 2.0 + MCP 2025-11-25 types
│   └── report/     # Text + JSON report renderers
└── agentox-cli/    # Thin CLI wrapper (main.rs + clap)

Key design principle: AgentOx uses its own JSON-RPC types (not an external MCP SDK) so it can send intentionally malformed messages to test server robustness — something a well-behaved SDK would reject client-side.

Why Rust?

Single binary — cargo install agentox-cli, zero runtime, runs in any CI pipeline
Memory safety — auditing tools built in unsafe languages create irony
Speed — fuzz-test hundreds of variants per second; Python tools are too slow
'Ox' brand — Agent + Oxidize. The name and language are inseparable

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

To add a new check:

Create crates/agentox-core/src/checks/conformance/my_check.rs
Implement the Check trait
Register it in CheckRunner::register_conformance_checks()
Add a unit test in the same file

License

Licensed under either of:

MIT License (LICENSE-MIT)
Apache License, Version 2.0 (LICENSE-APACHE)

at your option.

Installing the agentox executable

Installing the `agentox` executable