interceptpilot-mcp

Local MCP server for the InterceptPilot Chrome extension. It lets AI agents (Claude Code, Codex, Cursor and any other MCP client) read the extension's sanitized test context, inspect captured requests, rules and logs, and propose or run actions such as enabling a mock, importing a collection or capturing a tab.

Everything stays on your machine: the server talks to the extension over a local WebSocket on 127.0.0.1, protected by a session key that the extension generates.

Setup

1. Open the InterceptPilot Full App, go to AI Bridge and click Start.

2. Click Copy configuration. You get something like:

   {
     "mcpServers": {
       "interceptpilot": {
         "command": "npx",
         "args": ["-y", "interceptpilot-mcp", "--port", "37177", "--key", "<SESSION_KEY>"]
       }
     }
   }

3. Add it to your MCP client and restart the client:

   • Claude Code: claude mcp add-json interceptpilot '<the "interceptpilot" object>', or paste it into ~/.claude.json.

   • Cursor: .cursor/mcp.json (project) or ~/.cursor/mcp.json (global).

   • Claude Desktop: claude_desktop_config.json.

   • Codex: ~/.codex/config.toml, as [mcp_servers.interceptpilot] with the same command and args.

4. Back in the extension, the AI Bridge status changes to Connected.

The key is per session. Regenerating it in the extension invalidates the configuration you copied before. Never paste a real key into issues, logs or documentation.

Related MCP server: console-stream-mcp

How it works

AI client
  -> MCP adapter (this package, stdio)
  -> shared local daemon (one per port)
  -> WebSocket connection from the extension
  -> InterceptPilot

The MCP client starts the adapter. The adapter starts the local daemon when none is listening on the configured port; several adapters (several chats or clients) share one daemon and one key. If the extension disconnects, the daemon stays up and the tools return a safe error until the extension reconnects.

The daemon exits on its own after 10 minutes with no adapter and no extension connected. When you update the package, the newer adapter asks an older daemon to stop and starts a fresh one, so both always run the same version.

Options

Tools

What each tool exposes depends on the permissions you set in the extension. By default query-string values, headers, bodies, cookies, Authorization values and tab titles are never sent, and every action that changes state opens a proposal you confirm in the Full App. Session permissions let you skip the confirmation for specific groups of actions.

Reading

Actions

Security

• Local only: the daemon listens on 127.0.0.1.

• The session key is required from both the extension and every adapter, and is never echoed in logs, errors or tool results.

• Sanitized by default; sensitive data is only sent when the matching permission is on.

• State changes are proposals confirmed by you unless you enable the matching session permission.

• The daemon accepts an allowlist of commands. There are no tools to clear logs, drive the debugger or reload arbitrary pages.

Troubleshooting

Extension not connected. Open the Full App, go to AI Bridge and click Start. Tools return a safe error until the extension connects.

Daemon did not start. Run it by hand to see the error: npx -y interceptpilot-mcp daemon --port <PORT> --key <KEY>.

Port in use. A healthy daemon on the port is reused by other adapters. If an old process is stuck, stop it or change the port in both the AI Bridge page and the client configuration.

"An older interceptpilot-mcp daemon is running on port … and could not be replaced automatically." A daemon from version 0.1.0 is still running; that version cannot be stopped remotely. End the node process that runs interceptpilot-mcp daemon (or restart the machine) and start the MCP client again. Later versions replace themselves without this step.

Invalid or regenerated key. Copy the configuration again from the AI Bridge page.

Client using an old configuration. Update the client configuration and restart the client. Permission changes happen in the extension and do not require a new key.

Development

npm install
npm test

License

MIT