MCP tools

ReqRes has 33 MCP tools: 18 read tools and 15 change tools.

Filters shared by several tools#

list_sessions, wait_for_session, wait_for_sessions and list_destinations take the same filters. Every filter is optional.

The country comes from an offline lookup of the server's address, at country level. See See where requests go.

What a row says#

list_sessions returns one short row per request. Tokens in the row say what the request spoke and how far it got:

• Protocol. Each request row carries proto=h1, proto=h2 or proto=ws. HTTP/2 rows appear only with Capture HTTP/2 (beta) on. See Capture HTTP/2 and gRPC.
• RPC status. A gRPC-Web, Connect or native gRPC call carries grpc= with its status. A gRPC-Web error arrives as HTTP 200, so grpc=NOT_FOUND next to 200 is the failure.
• Relayed connections. A connection ReqRes did not decrypt is one kind=relay row: the endpoint, the bytes each way and how long it was open. It has no method, status, headers or body. HTTPS is relayed until the ReqRes CA is installed and trusted.
• Failed requests. A request that did not complete is still a row, marked outcome=failed, aborted or timed_out, with the phase it broke in: dns, connect, tlsUpstream (the server's certificate), tlsClient (the app refused ReqRes's certificate), request or response. cancelled_by_app marks a request the app gave up on. See See why a request failed.
• Live rows. A request still open is listed as IN_FLIGHT waiting (no response yet) or IN_FLIGHT streaming (bytes so far). When it finishes, the finished row replaces it under the same uid. ENDED_WITHOUT_FINAL_ROW marks one whose end was never recorded, for example because capture stopped.
• WebSockets. A WebSocket connection is its 101 Switching Protocols row. list_messages reads its messages.

What the Delivery line says#

While capture is on, capture_status has a Delivery: line, and diagnose_setup a Delivery to ReqRes check. They say whether what capture records reaches the copy of ReqRes the agent is talking to. Requests already in the list stay there, whatever the line says.

If the extension cannot reconnect within a few seconds, for example because capture was started from System Settings or by an earlier ReqRes build, ReqRes restarts capture once by itself. It does not restart a capture it started itself that never connected, and it does not restart after you or an agent asked for a start or a stop.

When the line says "NOT reaching ReqRes", ask the user to click Restart Capture in the traffic list or the menu bar menu, or call stop_capture and then start_capture. Each asks for approval first, unless the user allowed agent changes.

While the line reads reconnecting, not connected yet or "NOT reaching ReqRes", breakpoints hold nothing: a request that matches one goes through, because nobody could answer it. A request held before ReqRes went away is listed again once ReqRes reconnects, with what is left of its 60 seconds.

Read tools (18)#

Read tools never ask for approval. ReqRes redacts credential-shaped values in everything they return, except for hosts you send unmasked. See Control what agents see.

diagnose_setup runs the same checks as Capture ▸ Diagnose Setup…. See Run Diagnose Setup. capture_environment warns first when capture is stopped, and names the certificate step when the ReqRes CA is not installed. See Capture command-line tools and agents.

list_messages and wait_for_message read what ReqRes kept: the first 200 and the last 2,000 messages of a connection, and the first 64 KB of each message. An agent reads up to 4,096 bytes of each payload. See Read WebSocket messages.

get_session views#

The view argument chooses what get_session returns.

• from starts a page: an event number for events, or a message position for rpc, requests first. Take nextFrom from the previous page.
• events and assembled show only complete events. An incomplete event at the end is withheld as "N bytes pending".
• events and assembled read the current capture run only.

See Read streaming responses.

Change tools (15)#

Each change tool asks you first, unless you allowed agent changes. exclude_host and replay_request ask every time. answer_paused_request never asks per call: the Let agents answer held requests switch controls it. See Approve agent changes.

Limits that apply to several change tools:

• Rules need capture. A rule created while capture is stopped does nothing until capture starts. The tool result says so.
• Patterns cover the path and the query. /search does not match /search?q=x; write /search*. A regex starts with /, never with ^. See Write a URL pattern that matches.
• Mocks answer without the server. An override with a response_body, or a map_local file ReqRes can read, answers the app and never contacts the server. An override without a body sends the app's request to the server, and replaces the status and headers of the real answer. A map_local file that is missing or unreadable also sends the request on, and the server's response comes back unchanged.
• Some captures cannot be mocked. mock_from_session refuses a request still in flight. Without a response_body, it also refuses a response with no body, a body ReqRes kept only in part, a body under an encoding ReqRes did not decode, and, in override mode, a binary body, which needs map_local. Without a response_status, an override mock also refuses a captured status outside 200 to 599, such as a WebSocket's 101.
• Exports go to one folder. export_sessions writes to MCP Exports in ReqRes's Application Support folder. The agent names the file, not the folder. See Review and undo agent changes.
• Replay repeats only safe methods. A request captured as POST, PUT, PATCH or DELETE is refused, even when the agent asks for GET.
• Replay sends real credentials. The request goes out with the captured headers.
• Replay follows capture. With capture on, the replay goes through ReqRes. Your rules apply and it appears in the traffic list only when the host is not excluded and, for HTTPS, the ReqRes CA is installed and trusted. Otherwise ReqRes relays it untouched: the real server answers and no rule applies. An HTTPS replay without a trusted CA leaves one kind=relay row, and a replay to an excluded host leaves none. With capture off, it goes straight to the server.
• A busy port stops capture. If another program holds the proxy port, start_capture does not start capture, and ReqRes offers another port in its window. See Change the proxy port.
• Held requests need a switch. answer_paused_request works only while Settings ▸ Breakpoints ▸ Let agents answer held requests is on. It is off by default. See Hold a request with a breakpoint.
• Rule paths come back masked. list_rules and the rule a change tool returns show a credential-named value in the path as REDACTED. The stored rule keeps the real value and matches on it. A path sent back to update_rule exactly as shown keeps the stored one, and a path holding the mask any other way is refused. See Control what agents see.

Status and headers of a rule#

• An extend rule keeps the server's status. It sends the request to the server and changes only what it names in the response. A response_status from 200 to 599 answers in place of the server's, a 404 or a 500 included. Left out, or 0, the server's status stays.
• An override answers with its own status. It is 200 when response_status is left out. 0 is refused.
• A map_local rule uses no status. Its file answers 200. When the file is missing, the server's response comes back unchanged.
• Only an override gets a Content-Type by default. When its response_headers name none, a new override is given Content-Type: application/json; charset=utf-8, because its response carries only the rule's headers. An extend or map_local rule gets no response headers unless you give them, so the server's Content-Type, or the file's, stands.
• A change of mode keeps the status and the response headers. update_rule keeps both unless you send new ones. An override made extend keeps its status, such as 200, in place of the server's, so send response_status 0 with the change to keep the server's. An extend rule that keeps the server's status needs a response_status to become an override. A map_local rule has no status of its own, so one made extend or override without a response_status takes the status a new rule in that mode starts with: 200 for an override, the server's for an extend rule. A rule made an override keeps its stored response headers as well, so it answers with no Content-Type unless they name one. Send response_headers with the change. The approval panel says what the rule keeps.
• A rule never sets a request's Content-Length or Transfer-Encoding. request_headers are set over the app's own headers, except these 2, which describe the app's body and stay as the app sent them.
• A rule from before ReqRes 1.1 can still answer 200. Rules saved before ReqRes 1.1 can carry status 200 and the JSON Content-Type in every mode. At its first launch, ReqRes 1.1 reset each extend rule that sets a request header and still had that untouched response: status 200, that Content-Type alone and no body. Such a rule now keeps the server's status and headers. ReqRes 1.1 also removed that Content-Type from each map_local rule whose only response header it was. Other rules keep what they saved, so an older extend rule can still answer 200 in place of the server's status. list_rules shows each rule's status.

Errors#

When ReqRes refuses a call, the agent receives the HTTP status, an error code and a message.

For errors before a call reaches ReqRes, such as "Cannot reach ReqRes", see Fix agent errors, missing agent traffic and the App column.