MCP

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 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
Choose your MCP client: In Proxyman Settings → MCP, select Codex or Claude Code, then use Copy Command. For Cursor, choose Manual 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 sensitive-data redaction enabled 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

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

PreviousCommand-line

NextSKILL.md

Last updated 5 days ago

Was this helpful?