MCP for AI agents
Let Claude Code, Codex CLI, Gemini CLI, Cursor or Claude Desktop read your captures and, when you allow it, add rules and control capture.
WireLens for Mac includes wirelens-mcp, a Model Context Protocol server. With it, an agent in your editor can find the request behind a bug, read its body and export it. If you allow changes, it can also create and edit every kind of rule, write and test a script, release a request that a breakpoint is holding, and start capture.
The server comes with the app, at /, and always matches the app's version.
The MCP server is free. Rules an agent adds count against the same free allowances as the app, and tools that reach a Pro feature, such as the upstream proxy, protobuf schemas, HTTP/3 decryption or the Network Extension, need WireLens Pro. Without it, those calls return an error that says so.
Install#
The easiest way is Tools ▸ MCP Server. It finds the clients on this Mac, including Claude Code, Claude Desktop, Codex CLI, Gemini CLI and Cursor, and shows each one as registered, detected or not found with its config file. Click Install on a client, or Install in N Detected Clients for all of them. Help ▸ Install MCP Server… opens the same pane.
The Allow changes switch is on by default. It adds --allow-mutations, which lets the agent create, edit and delete rules, release paused requests and delete captured traffic. Turn it off before installing for an agent that should only look.
Every install points at the full path inside the app, and the server always matches the version of WireLens that recorded your capture.
From a terminal#
claude mcp add --scope user wirelens -- /Or let WireLens write the config file itself. wirelens is the app's own command line tool: give it its full path unless you have linked it onto your PATH:
/Client names are claude-code, claude-desktop, codex, gemini and cursor. mcp install with no name installs into every client it finds. mcp status lists each client with its state, config file and install command; mcp install prints how to reload the client afterwards.
--project writes a config in the current folder instead of your user config: .mcp.json for Claude Code, .cursor/mcp.json for Cursor and .codex/config.toml for Codex. Claude Desktop and Gemini CLI have no project config; for them it writes the user config.
By hand#
| Client | Config file | Shape |
|---|---|---|
| Claude Code | ~/.claude.json | mcpServers |
| Claude Desktop | ~/ | mcpServers |
| Codex CLI | ~/.codex/config.toml | [mcp_ (TOML) |
| Gemini CLI | ~/ | mcpServers |
| Cursor | ~/.cursor/mcp.json | mcpServers |
Any other MCP client works the same way: point it at the same binary, and add --allow-mutations if you want it to change things.
Codex is the only one whose config is TOML:
[mcp_servers.wirelens]
command = "/Installing into Codex changes only that table. The rest of config.toml, comments included, stays as it was.
Reading, and changing#
The server only reads unless it is started with --allow-mutations. Without the flag, the tools that change things are left out of the list the agent sees.
Tools#
Always available
| Tool | Does |
|---|---|
capture_status | Whether capture is running, the port, which hosts are decrypted and whether the certificate is trusted. The first call when traffic is missing. |
diagnose_setup | Ranks likely setup problems against what is actually happening, for a symptom you describe |
proxy_env, run_guided_setup | The environment variables and copy-paste steps for runtimes that ignore the macOS proxy setting (curl, Node, Python, Go, Docker and others) |
list_simulators | Simulators on this Mac and whether each one trusts the WireLens certificate |
search_docs | WireLens's own troubleshooting and rule guides |
list_flows, get_flow | Find flows by host, path, method and status; read one |
get_flow_body | Read a body, or one field of it with a JSON path |
search_bodies | Search inside payloads |
list_hosts, list_sessions | Totals by host and by capture run |
llm_spend | What AI-model calls cost, in total and per model, for a capture run or any filter (Pro). get_flow shows one call's tokens, and with Pro its cost |
list_, get_ | WebSocket connections and their frames |
list_rules, get_rule, get_rules | Rules as a short list with ids and order, one rule in full, or the whole configuration |
export_rules | Save rules to a file that import_rules reads back, on this Mac or another |
script_reference, generate_script, test_script | The scripting API, a script built from a list of edits, and a trial run against a captured request |
list_paused_flows | What a breakpoint is holding right now, and how long each has left |
export_har, export_curl, export_session | Take traffic elsewhere |
generate_code | Client code for one captured flow (curl, HTTPie, Python Requests and more) |
With --allow-mutations
| Tool | Does |
|---|---|
ensure_ready | Gets capture working in one call: opens WireLens if it is closed, adds hosts to SSL Proxying, starts capture, installs the certificate, and reports what still needs a person |
control_capture | start, stop, status, or clear (deletes captured traffic) |
control_system_proxy | enable, disable or restore the macOS system proxy |
control_ | status, install, enable, disable or uninstall the experimental Network Extension. Installing ends in macOS prompts that you approve in System Settings. |
control_certificate | status, install, export or uninstall the root certificate, for your user or the whole system |
quit_app | Quit WireLens. Captured traffic stays. |
set_ssl_include, toggle_ssl_host, set_ | Which hosts get decrypted |
set_allow_list, set_block_list | Capture Allow List and Block List |
set_throttle, set_ | Network Conditions |
add_map_local, add_map_remote, add_rewrite, add_breakpoint, add_script_rule, add_dns_spoof, add_reverse_proxy, add_, add_block_rule | Create a rule of any kind |
toggle_rule, update_rule, move_rule, duplicate_rule | Change a rule in place, reorder it, or copy it |
remove_rule, remove_rules, import_rules | Delete one rule or several, or load a saved set |
resume_paused_flow | Continue (with edits if you want), abort or extend a request or response held at a breakpoint |
annotate_flows, reveal_flow, delete_flows, rename_session, delete_session | Comment on, colour, open, rename and delete captured traffic |
send_request, replay_flow | Send traffic through the proxy |
set_setting, set_upstream_proxy, set_protobuf_schema | Switch a setting, chain to an upstream proxy, point the inspector at a Protobuf descriptor set |
setup_simulator | Install the WireLens certificate into a simulator and check that it is trusted |
inject_electron | Launch an Electron app with its traffic going through WireLens |
Prompts and resources#
Clients that show MCP prompts offer five ready-made tasks:
| Prompt | Asks for |
|---|---|
why_ | A host. Works out why it shows no headers or bodies. |
mock_this_endpoint | A URL and an optional status. Turns the captured request into a Map Local mock. |
find_ | A value, such as an order id or an error message, and an optional host |
summarise_api_errors | An optional host and start time. Reviews recent failures, including ones that answered 200. |
prepare_capture_for | A host, app or runtime to capture |
The server also offers five resources: wirelens://, wirelens://, wirelens://guide/cli (the command line reference for the installed version), wirelens:// (how rules are evaluated) and wirelens:// (live capture status).
Working with rules#
Each add_ tool accepts everything the matching pane in Tools does. A Map Local rule can carry its own headers and a delay. A breakpoint can pause the request, the response or both, with its own timeout. Any rule can take a scope that narrows it by method, status, header, body text or the app that sent the request.
update_rule changes the fields you name and leaves the rest of the rule as it was, including its id and its place in the list. Rules in a list are tried in order and the first match wins. list_rules shows the order and move_rule changes it.
export_rules and import_rules move a set of rules between Macs. import_rules has a dry_run that reports what would change.
Writing a script#
script_reference gives the agent the scripting API. generate_script builds a script from plain edits such as "set this header" or "change this JSON field", and can turn a captured response into a mock. test_script runs a script against a captured request and reports what it would change, along with anything it logged and any error. add_script_rule installs it. See Scripting.
Paused requests#
A breakpoint holds a real request until someone answers it. list_paused_flows shows what is waiting, and with an id returns the headers and body. resume_paused_flow continues it, with edits if you want them, aborts it, or gives it more time. The same request is in the Waiting Traffic window (⇧⌘B), and whichever side answers first decides.
Simulators#
A simulator uses your Mac's network. The only setup it needs is the WireLens certificate in its own trust store. list_simulators shows which simulators have it. setup_simulator installs it into every booted simulator, or into one you name, and then reads the simulator's trust store to confirm. Pass boot: true to start a simulator that is shut down. It covers iOS, watchOS, tvOS and visionOS simulators. See Capture other devices.
What keeps it safe#
- Credentials are hidden. Bodies and headers come back with tokens and keys replaced. The agent has to pass
reveal_secretsto get the real value, and you see it do so. - A rule needs a pattern. A rule with an empty pattern is refused.
- Deleting is labelled. Tools that delete rules or captured traffic are marked destructive, for clients that ask before running them. Deleting every rule of a kind takes an explicit
confirm_allfrom the agent. - Reading leaves your capture untouched. The server reads while the app keeps recording.
- The app owns capture. Starting capture and changing network settings are requests to the running app.
ensure_readyopens WireLens when it is closed; the other control tools report that the app is closed.
Over HTTP#
For clients that cannot start a local process, wirelens-mcp --http serves the same tools over HTTP as well as stdio, at http://. It listens on this Mac only.
| Flag | Does |
|---|---|
--http | Turn on the HTTP transport. The port is picked at random and printed. |
--http-port N | Use a fixed port |
--http-token TOKEN | Use your own bearer token. Without it, a token is generated. |
The address and token are written to ~/, readable only by you. The server keeps serving HTTP after its stdin closes. An administrator can lock the HTTP transport off on a Mac with wirelens mcp policy off.
Good first prompts#
- "Capture is on but my app is missing. What is wrong?" The agent starts with
capture_statusanddiagnose_setup. - "Find the failing checkout request and tell me what the server said." It searches with
list_flowsand reads only the part of the body it needs. - "Mock
/v2/catalogwith an empty list so I can test the empty state." With changes allowed, it adds a Map Local rule and checks it withsend_request. - "Pause the next POST to
/checkoutand change the amount to 1." It adds a breakpoint for POST only, waits for the request withlist_paused_flows, and sends it on with the new body. - "Get my booted simulator ready to capture
api.example.com." It installs the certificate withsetup_simulator, adds the host to SSL Proxying and starts capture. - "Add
X-Debug: 1to every request to the staging API." It writes a script, tries it on a captured request withtest_script, then installs it.
Something here is unclear, or wrong for your setup? Contact support or write to support@wirelens.app.