reqres-mcp

MCP server for the ReqRes Agent Sandbox - a deterministic HTTP world for AI agents. Same seed, same world version, byte-identical responses: stable ground truth for practicing pagination, auth flows, failure handling, and recovery.

Tools

| Tool | What it does | |---|---| | list_endpoints | Discover the sandbox: endpoints, 15 failure scenarios, chain presets | | query_users | Deterministic users (247 per seed), cursor pagination, expandable relations | | query_orders | Relational orders with {amount, currency, formatted} money objects | | trigger_scenario | Deliberate failures (429/5xx/timeout/malformed JSON) returned as data | | activate_chain | Arm a scripted failure sequence (5 presets, or define your own) | | get_trajectory | Replay the record of every call you made; JSONL export | | reset_state | Disarm the session chain and reset its server-side position |

Install

Free tier needs no key (100 req/day, 3 scenarios). For chains, trajectories, and all 15 scenarios, get a key at app.reqres.in/agents and set REQRES_AGENT_KEY.

Claude Code

claude mcp add reqres --env REQRES_AGENT_KEY=agt_your_key -- npx -y reqres-mcp

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "reqres": {
      "command": "npx",
      "args": ["-y", "reqres-mcp"],
      "env": { "REQRES_AGENT_KEY": "agt_your_key" }
    }
  }
}

Generic MCP config

{
  "command": "npx",
  "args": ["-y", "reqres-mcp"],
  "env": { "REQRES_AGENT_KEY": "agt_your_key" }
}

Environment

| Var | Default | Purpose | |---|---|---| | REQRES_AGENT_KEY | (none = free tier) | Your agt_... key | | REQRES_BASE_URL | https://reqres.in | Point at a self-hosted world | | REQRES_RUN_ID | auto (mcp-<hex>) | Trajectory run id for the session |

Determinism model

• Every response carries X-World-Version (currently v1.1.0). Pin it: same seed + same version = identical bytes; a version bump means fixtures may change.
• Default seed 42. Different seed, different stable universe.
• Failure scenarios and chains are deterministic too - chains are a pure function of (definition, call count).
• All calls in a session share a run id, so get_trajectory shows the whole session as one replayable trajectory.

Develop

npm install && npm run build && npm run smoke   # smoke = live free-tier test

MIT