Proxyman MCP

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs; this page is available as Markdown.

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

{% hint style="info" %} Check out the Proxyman SKILL.md for your AI Agents {% endhint %}

✅ 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

• Enable MCP in Proxyman

• Open Proxyman → Settings → MCP Tab

• Toggle Enable MCP Server to start the MCP Server

• Configure your MCP client (e.g., Cursor, Claude Desktop)

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

• 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

Agent Instructions

This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the ask query parameter, and the optional goal query parameter:

GET https://docs.proxyman.com/mcp.md?ask= &goal= 

ask is the immediate question: it should be specific, self-contained, and written in natural language. goal is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.