mcp.md

description	Explain how to use MCP on Proxyman with Cursor or Claude Code

MCP

1. What is Proxyman MCP?

Proxyman MCP (Model Context Protocol) is a feature that enables AI assistants (Claude, 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

✅ 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 seamlessly with Cursor and other MCP-compatible tools

3. How to add Proxyman MCP

1. Enable MCP in Proxyman
   • Open Proxyman → Settings → MCP Tab
   • Toggle Enable MCP Server to start the MCP Server
2. Configure your MCP client (e.g., Cursor, Claude Desktop)
3. Add Proxyman MCP to your Agents:

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:

{% code overflow="wrap" %}

claude mcp add proxyman --transport stdio -- "/Applications/Proxyman.app/Contents/MacOS/mcp-server"

{% endcode %}

• Setapp Version:

{% code overflow="wrap" %}

claude mcp add proxyman --transport stdio -- "/Applications/Setapp/Proxyman.app/Contents/MacOS/mcp-server"

{% endcode %}

Manual

Depend on what your AI Agents are, you have to edit the Agent Settings, to use Proxyman MCP. Here is the sample setting.json:

• 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"
    }
  }
}

4. Start using Proxyman MCP

• Ensure Proxyman is running
• Ask your AI assistant to interact with Proxyman.

4. Available 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 pause/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)
enable_scripting_tool	Create Script
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 pause 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.1 only (no network exposure)
• Per-session cryptographic token stored in ~/Library/Application Support/com.proxyman.NSProxy/mcp-handshake.json
• The handshake file has 0600 permissions (owner-only access)
• Sensitive data (auth tokens, passwords, API keys) is automatically redacted in responses