PROXYCAT / DEVELOPER GUIDE

Your traffic.
Your localhost API.

Capture in the app. Inspect and automate from your terminal. These examples talk directly to ProxyCat running on your own machine.

LOCAL APP

Full interactive reference ↗

Capture, search, rules, throttling, sessions and MCP. Requires ProxyCat to be running.

http://localhost:5050/docs HOSTED ACCOUNTS

Account API reference ↗

Sign-up, sign-in, billing and device licenses. Your captured traffic stays on your machine.

api.proxycat.app

START HERE

Capture your first request

Open ProxyCat and check that capture is running. The default management API is on 5050; the traffic proxy is on 8888. If you changed either port, replace it in the examples below. On Windows, use curl.exe to avoid PowerShell’s curl alias.

1. Check the local proxy

Look for proxyRunning: true and check proxyPort in the response.

curl --noproxy "*" http://localhost:5050/api/ProxyApi/status

2. Send a request through ProxyCat

Route a plain HTTP request through the traffic listener. The --noproxy setting prevents an inherited bypass list from skipping the explicit proxy.

curl --noproxy "" --proxy http://127.0.0.1:8888 http://example.com/

3. Read the capture

The response contains total and a requests array. Copy a request’s id for the next examples.

curl --noproxy "*" "http://localhost:5050/api/ProxyApi/requests?limit=10&offset=0"

The HTTP example does not need certificate installation. Any response, including a redirect, should appear as a capture.

Two ports, two jobs. Send application traffic through 8888. Send management calls directly to 5050; do not proxy them back through ProxyCat. API calls do not consume your daily capture allowance.

WORK WITH YOUR CAPTURE

Inspect, search and repeat

Inspect one request

Replace REQUEST_ID with an ID from the list. Full details include headers and decoded body text when available.

curl --noproxy "*" http://localhost:5050/api/ProxyApi/requests/REQUEST_ID

Search the capture

Search URLs, headers and body text. The local reference also documents method, hostname and status-range filters.

curl --noproxy "*" "http://localhost:5050/api/Tools/search?q=example.com&limit=10"

Replay the captured GET

Replace REQUEST_ID with the HTTP example’s ID. Replay sends the original request directly to its destination and returns the result.

curl --noproxy "*" -X POST http://localhost:5050/api/Tools/replay/REQUEST_ID

Replay does not apply proxy rewrite or throttle rules. Replaying a write request can repeat its action on the destination server.

See your local interactive reference for request schemas, rewrite rules, network conditions and session operations. Free capture limits still apply; HAR export, saved sessions and Slack alerts require Pro.

TLS, WITH TRUST

Move on to HTTPS

Open HTTPS Setup in ProxyCat to install and trust the root certificate generated by this instance. Configure your browser or device to use the traffic proxy, then open an HTTPS page and inspect the capture.

Some runtimes use a separate certificate store and need the ProxyCat CA configured explicitly. Follow the app’s certificate guide for your platform; keep TLS certificate validation enabled. If the root certificate changes, clients must trust the new certificate.

Certificate pinning and apps that ignore device proxy settings may prevent interception. A certificate or connection error is different from an upstream site’s CAPTCHA or traffic warning.

CONNECT YOUR AI WORKSPACE

Ask your client about captured traffic

MCP (Model Context Protocol) connects your chosen AI client to local capture metadata through ProxyCat’s bundled stdio adapter. It does not connect your AI client to the hosted accounts API.

In ProxyCat, open Connect AI and choose Enable for this session.
Copy the generated configuration into a client supporting local stdio MCP servers. Use the generated executable and connection-file paths; they vary by installation.
Capture traffic and ask: “Show the 5xx requests to api.example.com.” or “Compare the latest two POSTs to api.example.com.”

proxycat_statusProxy state, version and capture count.

proxycat_list_requestsMetadata with exact hostname, method and status-range filters; paginate with limit and offset.

proxycat_get_requestMetadata for a capture ID returned by the list tool.

Read-only, session-scoped access. MCP includes hostnames, methods, status, timestamps, timings and byte counts. It omits URL paths, queries, headers and bodies. Your AI client may send that metadata to its provider. Choose Disconnect to revoke access; closing ProxyCat ends access too.

IF SOMETHING DOESN’T CONNECT

Check the right connection

Localhost refuses the connection: Start ProxyCat and confirm its API port. A localhost link always points to the device where you open it.
The capture list is empty: Check proxyRunning, the proxy port, capture filters and remaining daily allowance. Requests sent directly to a website bypass the proxy.
A capture route returns 404 on api.proxycat.app: That host serves accounts and billing. Use http://localhost:5050 for your local capture API.
MCP says access is off or expired: Enable it again in Connect AI and refresh the generated configuration in your client. Each session has its own access token.
The management API returns 403: Run the command on the same machine and use localhost. Management calls from remote devices or forwarded through the proxy are blocked.

Your traffic.Your localhost API.