Typewise/mcp-chaos-rig

A local MCP server that breaks on demand. Test your client against auth failures, disappearing tools, flaky responses, and token expiry, all from a web UI.
---
The problem
You're building an MCP client. You need to test OAuth flows, token refresh, tool discovery, error handling, and session lifecycle. Production servers don't fail on command. You need a server that does.
What Chaos Rig does
Run a local MCP server where you control everything:
- **Break authentication**: force 401s and 500s mid-session, expire tokens on demand, reject refresh tokens
- **Break tools**: disable tools to trigger tools/changed, switch schema versions live
- **Break reliability**: add random latency, make tool calls fail at configurable rates
- **See everything**: live request log shows inbound JSON-RPC calls and outbound SSE responses, with click-to-expand bodies
Test scenarios
| Scenario | How to test it |
| --------------------------- | ------------------------------------------------------------------------------------------------ |
| OAuth 2.1 consent flow | Use the interactive consent page: approve, decline, invalid code, tampered state |
| Fixed header auth | Switch to Headers mode, configure key-value pairs, verify client sends them |
| Missing/wrong headers | Send requests with missing or mismatched headers — 401 with details |
| Token rejection mid-session | Toggle "Reject OAuth" to 401 or 500 while client is connected |
| Token expiry and refresh | Set access token TTL to a short value, watch the client refresh |
| Reject refresh tokens | Toggle "Reject refresh tokens" to force re-authentication |
| Wrong client refreshing | Enable "Enforce refresh token ownership" — catches clients that lose credentials and re-register |
| No dynamic registration | Switch to "Pre-registered client only" — /register 404s, only your client_id works |
| Rotated client credentials | Change the pre-registered client_id mid-session — the old one now fails with invalid_client |
| Scope discovery conflict | Set different scopes in metadata vs WWW-Authenticate header, test which the client trusts |
| Tool disappearing | Disable a tool in the Tools tab. Clients receive tools/changed |
| Tool schema changing | Switch echo or add between v1 and v2 schemas |
| Flaky tool calls | Set failure rate 0-100%. Failed calls return isError: true |
| Slow responses | Enable slow mode with configurable latency range |
| PKCE code exchange | OAuth consent page offers "Wrong Code" and "Wrong State" options |
| Database-backed tools | CRUD operations on a real SQLite contact database |
---
Quick start
Control panel at localhost:4100/ui, MCP endpoint at http://localhost:4100/mcp. Requires Node 20+.
If you prefer a global install:
Or run from source:
Remote access
If your production environment needs to reach Chaos Rig, expose it via a tunnel (ngrok, Cloudflare Tunnel, etc.) and set BASE_URL so OAuth redirects resolve correctly:
Auth mode starts at Bearer, so a tunnel-facing rig usually wants AUTH_MODE too (none, bearer, headers, oauth). For OAuth with pre-registered credentials, see Client registration.
Auth state
All state is in-memory and resets on restart, back to whatever the environment seeds (AUTH_MODE, OAUTH_CLIENT_MODE, STATIC_*) or to the built-in defaults. Bearer starts with token test-token-123 (valid until changed). OAuth tokens expire per TTL. Refresh tokens track ownership per client when enabled. After restart, do one refresh with ownership off to re-seed, then turn it on.