Log inSubmit server
Agent Harness logo

Agent Harness

Chaos-tests MCP agents through fault-injecting proxy scenarios and reports duplicate writes, retry violations, verdicts, and scores.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Agent Harness

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "agent-harness": {
      "command": "npx",
      "args": [
        "-y",
        "cuonztech-agent-harness"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

We couldn’t confirm it starts correctly

The install command started, but didn't respond the way we expected when we tried to talk to it.

npx -y cuonztech-agent-harness

initialize succeeded but no response to tools/list.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked Today.

Overview

agent-harness is a chaos-testing proxy that sits between an MCP agent and a real MCP server. It injects conditions such as ghost-write timeouts, rate limits, malformed JSON, and server errors, then records whether the agent repeats a write. Use its scenario tests to evaluate duplicate safety and retry handling against a test or staging system. A doctor command checks runtime, startup, tool classification, report paths, and write-tool schemas before testing.

Use cases

  • Measure whether an agent duplicates payment or booking writes after a timeout
  • Test retry handling for MCP tools that return 429 responses
  • Check whether write tools expose schemas suitable for post-timeout verification
  • Compare agent behavior across controlled MCP failure scenarios

Key features

  • MCP proxy for real upstream servers
  • F1–F5 write-failure scenarios
  • Randomized chaos mode with configurable error rate
  • Duplicate-write and retry-after detection
  • JSON reports with verdicts and resilience scores
  • Preflight checks for runtime, startup, tools, and schemas

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked Today

Recent health check succeeded.

7/7 checks healthy over the last 21d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 1d ago via OSV.dev · cuonztech-agent-harness (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

npm downloads2kPackage downloads in the last 30 days.
Last commit4d agoMost recent push to the default branch.
Install checkInconclusiveStarted but did not complete the MCP handshake in our test.

How Agent Harness works

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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Agent Harness

agent-harness is an MCP server that connects an agent to a real upstream MCP server through a chaos-testing proxy. Its main tools are the proxy runner for injecting timeout, 429, malformed-JSON, and 500 scenarios, plus the doctor command for checking startup, tools, report paths, and write schemas.

Run it with Node.js 20 or newer through `npx cuonztech-agent-harness`; the quickstart uses `npx` rather than a separate installation command. Provide the upstream server command and arguments, then select `doctor` for preflight checks or `proxy` to start a test.

Use proxy mode with scenario F1 against a test or staging server and include `--allow-writes`. F1 executes the first write upstream but returns a timeout, allowing the report to detect whether the agent executes the same operation again.

Yes, the quickstart uses Claude Code as the agent connected to the harness. Start the proxy, configure Claude Code to use the harness as its MCP server, perform a write task, and stop the proxy before reading the final report.

The `doctor` command checks the Node.js version, upstream server startup, tool classification, report path, and write-tool schemas. It also identifies missing idempotency keys and whether a post-timeout lookup is possible without a previously known ID, without calling tools or writing data.

Related MCP servers

All in Developer Tools All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewAgent Harness AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/agent-harness?style=directory)](https://allmcps.com/mcp/agent-harness)
HTML Embed
<a href="https://allmcps.com/mcp/agent-harness"><img src="https://allmcps.com/api/badge/agent-harness?style=directory" alt="Agent Harness on AllMCPs" /></a>