# agent-harness [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/cuonztech/agent-harness  
**GitHub Stars:** 0  
**npm Downloads (last month):** 2012  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/agent-harness

## Description
MCP chaos-testing toolkit. Default: simulated demo. Configure proxy mode to test a real agent.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "agent-harness": {
    "command": "npx",
    "args": ["-y","cuonztech-agent-harness"]
  }
}
```

## Documentation

## What agent-harness does

agent-harness evaluates how an MCP agent behaves when a tool call produces an ambiguous or failed result. It proxies requests between the agent and an upstream MCP server, tracks write operations, injects controlled failures, and creates a report after the run ends.

The main safety question is whether the same write operation is executed more than once. The harness compares a write tool and its arguments without the idempotency-key field, so changing or omitting that key does not make a repeated operation count as new.

Results include PASS, FAIL, and NOT_TESTED. FAIL covers duplicate execution and retrying a request before a supplied `retry_after` interval. NOT_TESTED is used when the run provides no verifiable write outcome or leaves execution ambiguous. Reports can also contain a 0–100 resilience score based on duplicate safety and failure handling. A run with a violation is capped at 49 points.

## How it works

The proxy is started with an upstream command and arguments, then remains available for the agent. The agent connects to the harness as its MCP server; the harness forwards requests to the configured upstream process unless a test condition changes the result. Stop the proxy after the agent finishes so the final report is written.

Scenario mode applies faults to write calls rather than fixed call numbers:

- F1 executes the first write upstream but returns a timeout, testing handling of a possible ghost write.
- F2 returns HTTP 429 with a default 60-second retry interval without executing the write.
- F3 returns truncated JSON without executing the write.
- F4 passes the first two writes through unchanged and checks duplicate handling without injecting an error.
- F5 returns HTTP 500 for the first write, then allows the next attempt to succeed.

The alternative `--mode chaos` applies a generic server failure randomly, according to `--error-rate`, to reads or writes. Chaos mode never creates a ghost write.

## Setup and configuration

Node.js 20 or newer is required. The package can be run with `npx cuonztech-agent-harness`. Configure the upstream MCP server with `--upstream-command` and one or more `--upstream-arg` values, and select a report destination with `--report-file`.

Run `doctor` before testing to validate the Node version, upstream startup, tool classification, report path, and tool schemas. A proxy run uses `proxy`, a selected `--scenario`, and usually `--allow-writes` when the test may execute a real write. The upstream should be a test or staging system; F1 genuinely executes its first write. `--audit-tools off` disables the tool-audit option shown in the quickstart.

The report file is initialized with a NOT_TESTED placeholder when the process starts. Treat the verdict as final only after the proxy exits and the agent has performed its test actions.

## Tools and capabilities

- Proxy an agent connection to an upstream MCP server.
- Inject F1–F5 failure and duplicate-safety scenarios.
- Apply probabilistic generic failures with chaos mode.
- Identify duplicate writes independently of idempotency-key changes.
- Produce compact results, JSON reports, verdicts, scores, and exit-status outcomes.
- Inspect write-tool schemas and whether an agent can look up an operation after a timeout.

## Limitations and notes

The harness observes MCP tool calls, not the messages an agent presents to its user. It does not understand the business rules of the upstream system, and its output is a self-test rather than a production certification.

F1 can modify data because the write is sent upstream before the timeout is returned. Use a disposable or staging system and explicitly allow writes. F3 and F5 do not execute their failed first attempts, so an immediate retry is safe in those scenarios and they provide limited evidence about cautious versus incautious behavior. A PASS without an injected fault, including F4, is a baseline rather than proof of resilience.

_Full upstream README: https://allmcps.com/mcp/agent-harness/readme_