The Proxygen MCP server exposes Proxygen’s tools to AI agents through the Model Context Protocol. Once connected, an agent like Claude Code, Gemini CLI or Codex can inspect traffic, modify requests, manage rewrites and scripts, run tests, and configure the proxy — all against your live Proxygen document.

Overview

Proxygen’s MCP server runs on localhost and is reached through a small bridge binary bundled with the app. It requires a per-session authentication token so only agents launched from your machine can use it.

The MCP is designed to prepare a workspace for you to inspect and continue from, not to replace the UI. When an agent creates an editor, a rewrite rule, a test, or a transform recipe, the result is visible in the corresponding Proxygen tool so you can review, adjust, and keep working with it.

Typical uses:

  • Ask an agent to explore traffic, summarize an API, or pick out interesting requests
  • Have an agent draft rewrite rules or scripts based on a natural-language description
  • Generate test configurations and payloads from example requests in history
  • Extract values from responses across many messages
  • Reproduce or modify requests in an editor
  • Configure TLS interception, history filters, and recording settings

Enable the server from Preferences → MCP by turning on Enable MCP server.

Setting up agents

Open Preferences → MCP. The Agent Setup popup and the settings.json button generate the configuration needed to register Proxygen with common agents.

Registration command

The popup offers one-line registration commands for three agents. Selecting an entry copies the command to your clipboard; paste it into a terminal to register Proxygen with that agent.

  • Claude Code

    claude mcp add proxygen --transport stdio -- <path-to-proxygen-mcp>

  • Gemini CLI

    gemini mcp add proxygen <path-to-proxygen-mcp>

  • Codex

    codex mcp add proxygen -- <path-to-proxygen-mcp>

The command shown in Proxygen contains the absolute path to the bundled proxygen-mcp bridge binary.

JSON configuration

For agents that are configured through a JSON settings file rather than a CLI command, use the settings.json button. It copies a ready-to-paste snippet to your clipboard:

{
  "mcpServers": {
    "proxygen": {
      "command": "/path/to/Proxygen.app/Contents/MacOS/proxygen-mcp"
    }
  }
}

Merge this into your agent’s MCP settings file.

Examples

Once Proxygen is registered with an agent, you can drive it with natural language. The examples below show the kinds of requests the tools are designed to handle — the agent picks the right tools and parameters and leaves results visible in Proxygen for you to continue from.

Exploring and summarizing traffic

  • “Give me a summary of the last hour of history — which hosts, status codes, and content types are present.”
  • “Build a sitemap of everything under api.example.com and highlight endpoints that only appear once.”
  • “Look through messages 400–650 and flag any request that took longer than 2 seconds, adding a note with the elapsed time.”
  • “Find every 5xx response in the last 200 messages, group them by host, and show me the first example of each.”

Searching and extracting values

  • “Search history for any response whose JSON body contains $.user.email and list the unique values.”
  • “In messages 1200–1500, extract $.data[*].id from each JSON response and give me the combined list with duplicates removed.”
  • “Find every request with an Authorization: Bearer header and capture the token using a regex — save the results as a table.”
  • “Pull //book/title/text() from every XML response on catalog.example.com using XPath.”
  • “Look at the SSE channel for stream.example.com and extract the event field from every message.”

Modifying and replaying requests

  • “Take message 842, open it in an editor, change the user_id query parameter to 42, and send it.”
  • “Create an editor for a POST to https://api.example.com/login with a JSON body containing {{username}} and {{password}} from the current environment, then send it.”
  • “Reproduce message 318 ten times in parallel using sendBatch and tell me the status code distribution.”
  • “Export message 512 as a curl command so I can share it.”

Rewrites, scripting, and interception

  • “Create a rewrite rule that adds X-Debug: 1 to every request to *.staging.example.com.”
  • “Mock GET https://api.example.com/feature-flags to return {"beta": true} with status 200.”
  • “Write a script that runs onResponse for api.example.com, logs any response where $.error is present, and sets a flag on the history message.”
  • “Turn on request interception for POST *.example.com/checkout only, and show me what’s currently in the queue.”
  • “Forward the first pending intercept but replace the body with the contents of message 902.”

Tests and transforms

  • “Create a test collection from message 611 that substitutes §email§ with the values [email protected], [email protected], and an empty string, then run it.”
  • “Poll the running test every few seconds until it finishes and summarize the failures.”
  • “Take the Authorization header value from message 750, base64-decode it, split on :, and give me the username.”
  • “Save a transform recipe that gzip-decompresses input then pretty-prints it as JSON, and call it decode-gzip-json.”

Cookies, variables, and configuration

  • “List cookies for example.com and delete any whose name starts with _tmp.”
  • “Set apiToken in the current environment to the access_token field from the response of message 988.”
  • “Enable TLS interception for *.example.com but exclude telemetry.example.com.”
  • “Add a host resolution that points api.example.com at 127.0.0.1 so I can hit a local server.”
  • “Check whether the Proxygen CA is trusted, and install it if it isn’t.”

Tools

The MCP server exposes the following tools, grouped by area.

Certificate

Tool name Description
certificateStatus Check whether the Proxygen CA is installed and trusted for TLS interception.
certificateInstall Install the Proxygen CA into the login keychain and set trust settings.

Channel

Tool name Description
channelList List active TCP connections currently passing through the proxy (same data as the Connection Monitor panel). Snapshot at call time.

Console

Tool name Description
consoleRead Read log items from the Console tool: proxy status, connection events, intercept/script matches, errors. Filter by level or search text.
consoleClear Delete all items from the Console log.

Tool name Description
cookieList List cookies from the project’s cookie jar with optional domain/name filtering.
cookieGet Get a single cookie from the project’s cookie jar by UUID.
cookieSet Create or update a cookie in the project’s cookie jar. Omitted optional fields revert to defaults when updating.
cookieDelete Delete specific cookies by their UUIDs.
cookieClear Delete all cookies from the project’s cookie jar.

Diff

Tool name Description
diffGet Compute a text diff between two items (history messages or socket messages) and stage them in Proxygen’s Diff tool.

Document

Tool name Description
documentList List all open Proxygen projects with their IDs and names. Pass a returned id as documentId on other tools to target that project.

Editor

Tool name Description
editorCreate Create a new editor with a prepared HTTP request. Prefer this over send when the request should stay visible in the UI.
editorCreateFromHistory Create an editor from a history message.
editorGet Full details of an editor, including request and last response.
editorUpdate Modify an existing editor’s request.
editorSend Send the request in an editor and return the response. The response is also visible in the Editor’s response pane.
editorList List all open editors in the project.
editorDelete Delete one or more editors.

History

Tool name Description
historySummary Quick overview of the project’s captured HTTP history: counts, hosts, status codes, content types, time range.
historyList List history messages with filtering, sorting, and pagination.
historyGet Full details of a single history message, including request and response headers and bodies.
historySearch Advanced rule-based search across history messages. Supports JSONPath and XPath positions in addition to the usual string/regex/wildcard matches.
historyExtract Extract values from matching messages using JSONPath, XPath, or regex capture groups.
historyUpdate Set flag and/or notes on history messages, either by UUIDs, numbers, or filter.
historyFilterSet Configure the history view filter so findings are surfaced in the UI. Pass reset: true to clear the filter.
historyDelete Delete specific history messages by UUID or number.
historyClear Clear all history messages from the project.
historySitemap Hierarchical URL tree grouped by host and path, useful for discovering endpoints.
historyExportCurl Export a history message as a curl command.

Host resolution

Tool name Description
hostResolutionList List custom host-to-IP overrides. Host patterns support * and ?; first match wins.
hostResolutionSet Create or update a hostname resolution. Matched by host, so an existing entry with the same host is replaced.
hostResolutionDelete Delete hostname resolutions by their host values.

Intercept

Tool name Description
interceptList List requests and responses paused in the Intercept queue waiting to be forwarded or dropped.
interceptGet Get full details of a pending intercepted message, with parsed request or response headers and body.
interceptForward Forward one or more pending intercepts to their destination, optionally replacing the raw message for a single intercept.
interceptDrop Drop pending intercepts so they never reach their destination.
interceptEnableSet Enable or disable interception of requests and responses.
interceptFilterSet Configure the Intercept filter (rules and hosts) so only matching messages pause in the queue.

Proxy

Tool name Description
proxyStatus Current proxy state, configured listeners, and active connection count.
proxyStart Start the proxy listeners.
proxyStop Stop all proxy listeners.
proxyConfigureTls Configure which hosts have TLS intercepted (MitM). Supports wildcards.
proxyConfigureWrite Configure what traffic is written to history, including content type filtering.

Rewrite

Tool name Description
rewriteCreate Create a rewrite rule that modifies requests, modifies responses, mocks, or drops traffic.
rewriteList List all rewrite rules in the project.
rewriteGet Full details of a rewrite rule, including match conditions and actions.
rewriteUpdate Modify an existing rewrite rule.
rewriteDelete Delete rewrite rules by index.

Script

Tool name Description
scriptCreate Create a JavaScript script that runs on matching proxy traffic (onRequest, onResponse).
scriptList List all scripts with match conditions and enabled state.
scriptGet Full details of a script, including source code.
scriptUpdate Modify an existing script.
scriptDelete Delete scripts by index.

Send

Tool name Description
send Send an HTTP request directly, bypassing the proxy and leaving no artifact in the project. Use editorCreate + editorSend instead when you want the request to be visible in the UI.
sendBatch Send multiple HTTP requests concurrently with configurable parallelism.

Show

Tool name Description
show Bring a Proxygen UI surface to the front and optionally select a specific item inside it.

Sockets

Tool name Description
socketsSummary Overview of WebSocket and SSE channels and messages in the project.
socketsList List socket messages with filtering and sorting.
socketsGet Full details of a single socket message.
socketsSearch Advanced rule-based search across socket messages.
socketsExtract Extract values from matching socket messages using JSONPath, XPath, or regex. Supports combining or collectioning results.
socketsUpdate Set flag and/or notes on socket messages.
socketsFilterSet Configure the Sockets view filter so findings are surfaced in the UI.
socketsDelete Delete specific socket messages by UUID.
socketsClear Clear all socket channels and messages from the project.

Test

Tool name Description
testList List all test collections, tests, and requests in the project.
testCreate Create a test configuration (not run). Uses §placeholder§ markers in the raw request for payload substitution (distinct from {{variable}} environment variables).
testGet Details of a test collection, its tests, requests, and configuration.
testRun Run a test by collection ID.
testStatus Poll status of the current test run: progress, pass/fail counts, elapsed time.
testResults Detailed paginated results from the current or last test run.
testStop Stop the currently running test.
testDelete Delete test collections by UUID.

Transform

Tool name Description
transformApply Apply chained data transformations: encoding, hashing, compression, text ops, string manipulation.
transformListOperations List all available transform operations with descriptions and parameters.
transformListRecipes List all saved transform recipes.
transformCreateRecipe Create a persistent Transform recipe.
transformDeleteRecipe Delete transform recipes by UUID.

Variable

Tool name Description
variableEnvironmentSet Set the active variable environment.
variableList List all variables in the current and default environment.
variableGet Get a variable’s resolved value by name.
variableSet Set a variable value in the current or a specific environment.
variableDelete Delete one or more variables by name.