interceptpilot-mcp

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.

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

Option	Meaning
--key <KEY>	Session key shown by the AI Bridge page. Required.
--port <PORT>	Local daemon port. Default 37177.
--no-daemon-autostart	Do not start the daemon automatically (debugging).
daemon	Run only the daemon: npx -y interceptpilot-mcp daemon --port <PORT> --key <KEY>.
--version, --help	Print the version or this usage.

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

Tool	Use it to
get_current_test_context	See capture status and mode, the active tab origin and path, the active collection, rule counts and the AI Bridge status.
list_captured_requests	List the requests captured in the active context.
search_captured_requests	Search captured requests with safe filters and pagination.
list_collections	List collections with rule counts.
get_active_collection	Get the active collection.
list_rules	List rules with sanitized match and action summaries.
search_rules	Search rules by metadata, match, action and diagnostics.
list_sanitized_logs	Read recent logs from the active context.
search_sanitized_logs	Search logs with safe filters and pagination.
list_recent_rule_results	See which rules matched recent requests and what was applied.
search_rule_results	Search rule results with safe filters and pagination.
explain_rule_match	Compare a rule with a captured request and learn why it matched or not.
get_import_bundle_schema	Get the import bundle schema. Works without the extension connected.
get_import_bundle_examples	Get safe example bundles. Works without the extension connected.

Actions

Tool	Use it to	Skips confirmation when
import_bundle	Propose a rule or collection bundle.	"Apply imports without confirmation" is on.
request_enable_rule, request_disable_rule, request_set_only_active_rule, request_set_active_collection	Toggle rules or switch the active collection.	"Rule and collection actions without confirmation" is on.
request_update_rule, request_update_collection	Edit safe fields of a rule or collection, with a before/after diff. responseBody and responseHeaders cannot be edited.	"Rule and collection actions without confirmation" is on.
request_delete_rule, request_delete_collection	Delete a rule or collection.	"Delete rules and collections without confirmation" is on.
request_reload_captured_tab	Reload only the captured tab to validate a mock. Never reloads other or internal pages.	"Reload captured tab without confirmation" is on.
request_start_capture, request_restart_capture, request_stop_capture, request_capture_current_tab, request_set_capture_mode	Control capture on the eligible web tab; modes are auto, full and light.	"Capture control without confirmation" is on.

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