Connect an AI agent

ReqRes runs an MCP server that lets an AI agent read the traffic ReqRes captures. With your approval, the agent can also change rules, host filters and capture, and stop ReqRes recording a host.

How the MCP server works#

Your MCP client starts reqres-mcp, a small program inside ReqRes.app, and talks to it over standard input and output (stdio). reqres-mcp passes each call on to ReqRes over HTTP on this Mac.

• The server is named reqres.
• ReqRes listens on 127.0.0.1 only, and only while ReqRes is running.
• To connect, reqres-mcp reads a private handshake file in the app's container. The file holds the port and a random token.
• ReqRes writes a new token each time the server starts, and deletes the file when the server stops.
• The server has 33 tools: 18 read tools and 15 change tools. See MCP tools.

All 33 tools work in the free version. The free limits of 2 host filters and 1 rule apply to agents too. See Free version and Pro.

Before you start#

1. Move ReqRes to your Applications folder. The configuration holds the path to reqres-mcp inside ReqRes.app. Run from a disk image or the Downloads folder, that path can change on every launch.
2. Open ReqRes. It must be running whenever the agent calls a tool.
3. Check that Settings ▸ MCP ▸ Enable the AI bridge is on. It is on by default.

If ReqRes runs from another folder, Settings ▸ MCP shows "Move ReqRes to your Applications folder before copying the configuration — this path changes on every launch." The network extension needs /Applications as well. See Set up capture.

Claude Code#

Run this command in Terminal:

claude mcp add --scope user reqres "/Applications/ReqRes.app/Contents/MacOS/reqres-mcp"

--scope user adds the server for all your projects. Without it, Claude Code adds the server only for the folder you ran the command in.

Settings ▸ MCP shows the same command under Claude Code, with a Copy button.

Claude Desktop#

1. In ReqRes, open Settings ▸ MCP.
2. Click Copy next to MCP Configuration.
3. In Claude Desktop, open Settings ▸ Developer ▸ Edit Config.
4. Merge the reqres entry into mcpServers. Keep any servers already there.
5. Quit Claude Desktop and open it again.
6. Ask Claude to call capture_status.

The copied configuration looks like this:

{
  "mcpServers": {
    "reqres": {
      "command": "/Applications/ReqRes.app/Contents/MacOS/reqres-mcp",
      "args": []
    }
  }
}

Claude Desktop keeps its configuration in ~/Library/Application Support/Claude/claude_desktop_config.json.

Cursor, Windsurf and other clients#

Cursor reads ~/.cursor/mcp.json, which has the same shape as the Claude Desktop configuration. Add the same reqres entry to it.

Windsurf and any other client that starts a stdio MCP server work too. Set the server's command to this path, with no arguments:

/Applications/ReqRes.app/Contents/MacOS/reqres-mcp

Check the connection#

1. Ask the agent to call capture_status.
2. Read the reply. It says:
   • whether capture is running, starting or stopping;
   • whether setup is finished;
   • the proxy address, such as 127.0.0.1:8034;
   • how many requests this capture run holds;
   • while capture runs, whether new requests reach ReqRes, in a line that starts with Delivery:;
   • whether the ReqRes CA is installed and trusted, and the ReqRes version.

If ReqRes crashed or was force quit while capturing, capture kept running. For a few seconds after you open ReqRes again, the Delivery: line reads reconnecting. See What the Delivery line says.

The reply then lists each protocol with its status: supported, beta, relayed or not_captured. A request of a relayed or not_captured kind, such as HTTP/3, is missing or unread by design. See Supported protocols.

If ReqRes is not running or the MCP server is off, the agent gets an error that starts with "Cannot reach ReqRes". See Fix agent errors, missing agent traffic and the App column.

Settings ▸ MCP ▸ Server Status shows the state of the server:

See which agent is connected#

The icon at the bottom of the sidebar shows agent activity. While an agent is active, its name appears next to the icon. With several agents, the text next to the icon says how many, such as "2 agents".

ReqRes names an agent after the program that started reqres-mcp, usually your MCP client. An agent counts as active for 90 seconds after its last call.

Click the icon to open the "AI bridge" popover:

• It lists each active agent and when it last made a call.
• With no agent active, it reads "On. No agent has used it recently."
• Show its traffic filters the traffic list to that agent's requests.
• Open Settings opens ReqRes Settings.

If ReqRes has captured nothing from the agent, Show its traffic is dimmed. A command-line agent needs the proxy environment first. See Capture command-line tools and agents.

The menu bar menu also shows the agent's name followed by "connected".

Turn the MCP server off#

Use any of these:

• Turn off Settings ▸ MCP ▸ Enable the AI bridge. ReqRes remembers the choice.
• Click Turn Off Bridge in the "AI bridge" popover.
• Choose Turn Off Bridge in the menu bar menu. It appears while Enable the AI bridge is on.

Turning the server off stops it and deletes the handshake file. Changes an agent is waiting to have approved are denied. The activity log gives the reason "The AI bridge was turned off in ReqRes.", and the agent gets a connection error.

To turn it back on, turn on Enable the AI bridge. reqres-mcp reads the handshake file on every call, so a client that is already running picks up the new token.

Related#

• MCP tools
• Approve agent changes
• Fix agent errors, missing agent traffic and the App column