Skip to content
ProbeDocs

MCP Setup (Claude / Cursor)

probe-mcp is a stdio JSON-RPC binary bundled inside the Probe install. To use it, point your AI client at the binary's path. No tokens, ports, or extra config — probe-mcp reads ~/.probe/api-handshake.json automatically, and reads it again whenever Probe's port or token changes, so you never have to restart your AI client after restarting Probe.

Find the binary path

Section titled “Find the binary path”

The binary lives inside the app bundle:

/Applications/Probe.app/Contents/MacOS/probe-mcp

If you installed Probe somewhere else, replace the prefix with that path.

Configure your client

Section titled “Configure your client”

The fastest way is the CLI — claude mcp add registers the server without editing any file. Everything after -- is the command Claude Code runs.

Terminal window
claude mcp add probe -- /Applications/Probe.app/Contents/MacOS/probe-mcp

Add --scope user to make it available in every project (defaults to the current project's .mcp.json).

Prefer to edit config by hand? Claude Code reads .mcp.json from your project root (or ~/.claude.json for a user-level config):

{
  "mcpServers": {
    "probe": {
      "command": "/Applications/Probe.app/Contents/MacOS/probe-mcp",
      "args": []
    }
  }
}

Verify it's wired up

Section titled “Verify it's wired up”
  1. Make sure Probe is running (the proxy may be stopped: the API and every non-traffic tool still work). probe-mcp also starts without it, but every tool answers Probe is not running … Start Probe, then retry. until the app is up.
  2. Restart your AI client so it picks up the new config. (This is only needed after a config change, not after restarting Probe.)
  3. Ask the AI: "What tools do you have available from probe?"
  4. You should see 117 tools listed, all prefixed probe_….

If the AI says it doesn't see any Probe tools:

  • Confirm Probe is open and capturing.
  • Check that ~/.probe/api-handshake.json exists (ls ~/.probe/ on macOS).
  • Run probe-mcp directly from a terminal — it prints what it found (or why it couldn't reach Probe) to stderr.

Auth and security

Section titled “Auth and security”

You don't pass any credentials. probe-mcp reads the bearer token straight from ~/.probe/api-handshake.json, which Probe creates with 0600 permissions on Unix (owner read/write only) from the first byte — it writes a fresh owner-only file and renames it into place, so the token is never readable by other users, even briefly. On Windows the file sits in your user profile, which only your account (and administrators) can read. Each proxy start generates a new port and token; quitting Probe removes the file. To point probe-mcp at an isolated Probe instance, set PROBE_DATA_DIR in the server's env block — it then reads <PROBE_DATA_DIR>/api-handshake.json.

The REST API only listens on 127.0.0.1, so it's reachable from local processes only.

What a connected AI can reach

Section titled “What a connected AI can reach”

An AI connected to Probe is trusted roughly like you: it can see captured traffic, send requests and run scripts. Probe still keeps a few things out of its reach by default:

  • Local files. Files transfers and Map Local rules created or edited over MCP may only read from ~/Downloads, ~/.probe/transfers and (Map Local) ~/.probe/map-local; downloads only write to the first two. Refusals name the allowed folders and never say whether a file elsewhere exists. Paths you pick in the app are not limited.
  • Secret variable values. Secret Composer variables are masked (••••••••) in send results and flow run reports, so they don't end up in a chat or a log by accident. This is not a barrier against an AI that sets out to read them: a script can print a transformed value, the captured traffic of its own Composer sends shows the real URL and headers (it is not masked), and a server that echoes the request returns the value. Don't connect an AI you wouldn't trust with those secrets.

Next steps

Section titled “Next steps”