Skip to content
Probe Docs

MCP Server

probe-mcp is a separate Rust binary that exposes Probe’s traffic to AI agents over the Model Context Protocol (JSON-RPC 2.0 over stdio). With it, Claude Code, Cursor, or any MCP-compatible client can read the captured requests, replay them, set breakpoints, manage Map Local / Map Remote / throttle rules, and run scripts — without you copy-pasting JSON into chat.

It ships inside the Probe install. You don’t need to download anything separately or pass tokens by hand.

What the AI can do

Section titled “What the AI can do”

probe-mcp exposes 61 tools today, grouped by feature:

GroupExamples
Traffic inspectionList, search, get full detail, diff two requests, summary
Capture controlStart/stop, get status
Replay & exportReplay a captured request, export as cURL or raw HTTP
Breakpoints & interceptsCreate breakpoints, list/resume paused requests
Host & client filtersBlock/unblock by host, block/unblock by client label
ThrottleSet/get/disable global throttle, list scoped throttle rules
ScriptingExecute ad-hoc JS, list/add/update/delete script rules
SessionsList active session tabs, list saved sessions, fetch entries
ComposeList/get/create collections, add requests and environments, send
Map LocalList, check match, create/update/delete/toggle, master switch
Map RemoteList, check match, create/update/delete/toggle, master switch

The full per-tool schema lives in MCP Tool Reference.

How it works

Section titled “How it works”
┌──────────────┐  stdio JSON-RPC  ┌──────────┐  HTTP w/ bearer   ┌───────────┐
│ Claude /     │ ───────────────▶ │ probe-   │ ────────────────▶ │  Probe    │
│ Cursor / ... │                  │ mcp      │  127.0.0.1:<rand> │  REST API │
└──────────────┘                  └──────────┘                   └───────────┘
                                       │
                                       │ reads on startup
                                       ▼
                          ~/.probe/api-handshake.json
                          (port + bearer token)

When Probe starts, it spins up an internal axum HTTP server on 127.0.0.1 at a random port and writes the port and a freshly-generated bearer token into ~/.probe/api-handshake.json (mode 0600 on Unix). When your MCP client launches probe-mcp, it reads that file, verifies Probe’s PID is still alive, and forwards every tool call as an authenticated REST request.

The handshake is rotated each time Probe starts, so a stolen token expires the moment the user quits.

Three steps to wire it up

Section titled “Three steps to wire it up”
  1. Install Probe. The probe-mcp binary is bundled with the app — nothing extra to install.
  2. Add it to your AI client’s config. One JSON block per client. See MCP Setup for Claude Code, Cursor, Continue, and generic stdio clients.
  3. Ask the AI a traffic question. Try: “What were the last five requests Probe captured? Replay the most recent failed one with a fresh Authorization header.”

Live UI updates from MCP writes

Section titled “Live UI updates from MCP writes”

Composer collections are JSON files in ~/.probe/compose/. When you ask the AI to build a request and it calls a Compose tool that writes a new collection or adds a request, Probe’s compose directory watcher sees the file change and reloads the in-memory collections — the new request appears in the Composer sidebar without you having to restart the app or click Reload.

The watcher coalesces filesystem events with a short debounce, so a burst of writes from one MCP call (typical when an agent creates a collection and immediately adds three requests) reloads once, not three times. This is what makes the round-trip — “ask Claude to draft a request → see it in the Composer → tweak and send” — feel like a single workflow instead of two disconnected tools.

The same watcher catches edits made in any other tool or sync target writing into ~/.probe/compose/. There’s no special-casing for MCP — anything that drops a JSON file in there shows up.

What’s NOT exposed

Section titled “What’s NOT exposed”

A few intentional gaps:

  • No raw filesystem access beyond the handshake. The MCP can only read what the REST API returns — captured traffic, rule state, sessions on disk via list_saved_sessions.
  • No system proxy toggle. Starting/stopping the proxy and flipping the system proxy setting are UI-only on purpose.
  • Rule writes are ephemeral. Map Local, Map Remote, breakpoints, and ignored hosts created via MCP live in Rust’s in-memory store. Probe’s UI owns persistence — any UI edit (or app restart) clobbers MCP-added rules. Ask the user to re-save in the UI if they need a rule to survive a restart.

Next steps

Section titled “Next steps”