# interceptpilot-mcp

> Local MCP server for InterceptPilot

Latest version **0.1.1** (published 2026-09-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install interceptpilot-mcp
pnpm add interceptpilot-mcp
yarn add interceptpilot-mcp
bun add interceptpilot-mcp
```

Provides the command `interceptpilot-mcp`.

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2026-09-14 |
| First published | 2026-09-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >=18 |
| Dependencies | 3 |
| Unpacked size | 79.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Maintainers | anderson_alpin |
| Keywords | mcp, model-context-protocol, interceptpilot, chrome-extension, api-mock, network-interception |

## Links

- npm: https://www.npmjs.com/package/interceptpilot-mcp
- Repository: https://github.com/AndersonAlpin/interceptpilot-mcp
- Homepage: https://github.com/AndersonAlpin/interceptpilot-mcp#readme
- Issues: https://github.com/AndersonAlpin/interceptpilot-mcp/issues
- npm.io page: https://npm.io/package/interceptpilot-mcp

## Dependencies (3)

- [ws](https://npm.io/package/ws.md) 8.21.0
- [zod](https://npm.io/package/zod.md) 4.4.3
- [@modelcontextprotocol/sdk](https://npm.io/package/@modelcontextprotocol/sdk.md) 1.30.0

## Alternatives

- [pagerjs](https://npm.io/package/pagerjs.md) — 60 weekly downloads
- [whistle.savefor-mock](https://npm.io/package/whistle.savefor-mock.md) — 4 weekly downloads
- [fakeforge-br](https://npm.io/package/fakeforge-br.md) — 0 weekly downloads
- [screenframe3d](https://npm.io/package/screenframe3d.md) — 0 weekly downloads
- [@lyra-mock-api/core](https://npm.io/package/@lyra-mock-api/core.md) — 0 weekly downloads

## Recent versions

- 0.1.1 (latest) — 2026-09-14
- 0.1.0 — 2026-09-14

## README

# interceptpilot-mcp

Local [MCP](https://modelcontextprotocol.io) 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:

   ```json
   {
     "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

```txt
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

```bash
npm install
npm test
```

## License

[MIT](./LICENSE)

---
_Source: https://npm.io/package/interceptpilot-mcp · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._