Connect Codex, Claude Code, or Cursor to Proxyman MCP to inspect captured HTTP/HTTPS traffic and create debugging rules from your AI assistant.
Proxyman MCP connects your AI assistant to the Proxyman macOS app running on your computer. Use it to inspect captured requests and responses, investigate failures, and create debugging rules. Keep Proxyman open and capture the traffic you want to investigate before asking your assistant to analyze it.
1. What is Proxyman MCP? #
Proxyman MCP (Model Context Protocol) is a feature that enables AI assistants (Codex, Claude Code, Cursor, and other MCP-compatible tools) to directly interact with the Proxyman macOS app. It allows AI to inspect HTTP traffic, create debugging rules, and control Proxyman - all through natural language conversations.
The architecture consists of two components:
- MCP HTTP Server - Runs inside Proxyman app on localhost with token-based authentication
- MCP CLI Server - A stdio-based MCP server that AI tools connect to, which forwards commands to Proxyman
Check out the Proxyman SKILL.md for your AI Agents
✅ Example Prompts
- Show me the last 10 API requests to api.example.com
- Create a breakpoint for all POST requests to /api/users
- Export the failed request as a cURL command
- Enable SSL proxying for *.stripe.com
- Create a new Script to change the status code, headers, body.
- Create Map Local, Breakpoint Tools with given URL
2. Benefits #
| Benefit | Description |
|---|---|
| AI-Powered Debugging | Ask AI to analyze captured traffic, find specific requests, or explain API responses |
| Hands-Free Rule Creation | Create breakpoints, map local/remote rules through conversation |
| Faster Workflow | Export cURL commands, filter flows, and manage sessions without switching context |
| Secure by Design | Localhost-only server with per-session token authentication |
| IDE Integration | Works with Codex, Claude Code, Cursor and other MCP-compatible tools |
3. How to add Proxyman MCP #
- Enable MCP in Proxyman - Open Proxyman → Settings → MCP Tab
- Turn on Enable MCP Server to start the MCP Server
- Choose your MCP client: In Proxyman Settings → MCP, selectCodex orClaude Code , then useCopy Command . ForCursor , chooseManual and add the displayed configuration to Cursor's MCP settings.
- Use the setup below for your client and installation. The command generated by Proxyman uses the path of your installed app, which may differ from these examples. Keep Redact Sensitive Data Before Sending to AI turned on for normal debugging.
Codex
- Production Version:
codex mcp add proxyman -- "/Applications/Proxyman.app/Contents/MacOS/mcp-server"
- Setapp Version:
codex mcp add proxyman -- "/Applications/Setapp/Proxyman.app/Contents/MacOS/mcp-server"
Claude Code
- Production Version:
claude mcp add proxyman --transport stdio -- "/Applications/Proxyman.app/Contents/MacOS/mcp-server"
- Setapp Version:
claude mcp add proxyman --transport stdio -- "/Applications/Setapp/Proxyman.app/Contents/MacOS/mcp-server"
Manual
For Cursor and other MCP clients, add the configuration from Proxyman's Manual tab to the client's MCP settings. Select the configuration for your installed Proxyman app. These examples show the mcpServers entry:
- Production Version:
{ "mcpServers": { "proxyman": { "command": "/Applications/Proxyman.app/Contents/MacOS/mcp-server" } }}
- Setapp Version
{ "mcpServers": { "proxyman": { "command": "/Applications/Setapp/Proxyman.app/Contents/MacOS/mcp-server" } }}
- Start using Proxyman MCP
- Ensure Proxyman is running
- Ask your AI assistant to interact with Proxyman, for example: "Show the latest requests to api.example.com."
- If the client cannot find Proxyman, check that MCP is enabled and the configured app path is correct, then reconnect the client. If it connects but finds no flows, make a new request and use the missing-traffic checklist .
4. Available Tools #
The tables below list common tools. Your MCP client shows the full list of tools for your installed Proxyman version. See the Changelogs for more tools.
Read-Only Tools
| Tool | Description |
|---|---|
get_version |
Returns Proxyman version and build number |
get_proxy_status |
Returns recording state, proxy port, and SSL proxying status |
get_flows |
Lists captured HTTP/HTTPS flows with optional filters ( limit ,host_filter ,method_filter ,status_filter ) |
get_flow_detail |
Returns full details of a specific flow including headers, body preview, query params, and cookies |
list_rules |
Lists all debugging rules (breakpoints, map local, map remote, blacklist) |
get_ssl_proxying_list |
Returns SSL proxying include/exclude domain lists |
get_certificate_status |
Returns root certificate installation status |
Write Tools
| Tool | Description | Required Params |
|---|---|---|
create_breakpoint |
Creates a breakpoint to /inspect matching requests | url (pattern) |
create_map_local |
Returns custom responses for matching URLs | url (pattern) |
create_map_remote |
Redirects requests from one URL to another | from_url ,to_url |
create_blacklist |
Blocks requests matching a URL pattern | url (pattern) |
create_scripting_rule |
Creates a Scripting rule with custom JavaScript | url ,script_content |
enable_ssl_proxying |
Enables HTTPS decryption for a domain | domain |
Session Control
| Tool | Description |
|---|---|
clear_session |
Clears all captured flows from current session |
toggle_recording |
Starts or stops traffic recording |
Flow Operations
| Tool | Description |
|---|---|
export_flow_curl |
Exports a captured request as a runnable cURL command |
filter_flows |
Advanced filtering with multiple criteria (url, host, method, status, headers, body) supporting AND/OR combinations |
App Control
| Tool | Description |
|---|---|
open_proxyman |
Launches Proxyman if not running |
quit_proxyman |
Quits the Proxyman app |
Changelogs #
MCP v3 (Proxyman macOS ≥ 6.8.0)
| Name | Description |
|---|---|
| get_version | Get the current Proxyman macOS app version and build number |
| get_proxy_status | Get current proxy status including recording state, port number, and SSL proxying status |
| get_flows | Get recent HTTP/HTTPS flows from Proxyman's active session data source |
| get_flow_detail | Get detailed information about a specific flow including headers, body, query params, and cookies |
| list_rules | List all active debugging rules (breakpoints, map local, map remote, blacklist, scripting, dns spoofing, network condition, whitelist) |
| get_ssl_proxying_list | Get the current SSL Proxying configuration including enabled status and domain lists |
| create_breakpoint | Create a new breakpoint rule to and inspect/modify requests or responses matching a URL pattern |
| create_map_local | Create a Map Local rule to return a custom response for matching requests |
| create_map_remote | Create a Map Remote rule to redirect requests from one URL to another |
| create_blacklist | Create a Blacklist rule to block requests matching a URL pattern |
| create_scripting_rule | Create a Scripting rule with custom JavaScript to modify requests/responses |
| enable_ssl_proxying | Enable SSL Proxying for a specific domain to decrypt HTTPS traffic |
| clear_session | Clear all captured flows from the current session |
| toggle_recording | Start or stop recording HTTP traffic |
| export_flow_curl | Export a captured HTTP request as a cURL command |
| filter_flows | Filter captured HTTP/HTTPS flows using advanced filter criteria |
| get_certificate_status | Get the current status of Proxyman's root certificate |
| install_certificate | Install and trust the Proxyman root CA certificate |
| uninstall_certificate | Remove the Proxyman root CA certificate from the Keychain |
| inject_terminal | Launch a terminal app with Proxyman proxy environment variables injected |
| get_terminal_manual_command | Get a bash source command for manually setting proxy environment variables |
| answer_setup_question | Answer setup questions about capturing HTTPS from iOS, Android, browsers, etc. |
| search_docs | Search the built-in Proxyman setup and troubleshooting doc index |
| list_setup_workflows | List the supported setup workflows Proxyman MCP can guide users through |
| list_popular_workflows | List popular setup workflows using Proxyman's curated fallback ranking |
| open_proxyman_screen | Open a specific Proxyman guide or setup screen in the macOS app |
| run_guided_setup | Run a one-click automation in Proxyman for browsers or Android emulators |
| list_reverse_proxies | List configured Reverse Proxy entries |
| create_reverse_proxy | Create a Reverse Proxy entry for localhost or custom local port routing |
| generate_code | Generate code from a captured HTTP flow in 18+ languages/frameworks |
| create_dns_spoofing | Create a DNS Spoofing rule to redirect a hostname to a different IP address |
| list_dns_spoofing | List all DNS Spoofing rules and their enabled status |
| update_dns_spoofing | Update an existing DNS Spoofing rule |
| get_external_proxy | Get the current External Proxy (upstream proxy) configuration |
| set_external_proxy | Configure an External Proxy setting for a specific protocol kind |
| toggle_no_caching | Toggle the No Caching feature (strips cache-related headers) |
| inject_electron | Launch an Electron app with Proxyman proxy configuration injected |
| open_proxyman | Launch the Proxyman macOS application |
| quit_proxyman | Quit the Proxyman macOS application |
MCP v2 (Proxyman ≥ v6.7.0)
- Built-in knowledge base covering iOS, Android, browsers, terminal, VPN, localhost, and third-party libraries
- New commands: answer_setup_question, search_docs, list_setup_workflows, open_proxyman_screen, run_guided_setup, create_reverse_proxy
- MCP resources and prompt templates for chat clients
- Reverse proxy create/list support
Security #
- The server binds to
127.0.0.1only (no network exposure) - Per-session cryptographic token stored in
~/Library/Application Support/com.proxyman.NSProxy/mcp-handshake.json - The handshake file has
0600permissions (owner-only access) - Sensitive data (auth tokens, passwords, API keys) is automatically redacted in responses
source & further reading
proxyman.com — original article