> ## Documentation Index
> Fetch the complete documentation index at: https://docs.httpmon.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools reference

> Complete reference for httpmon's 14 MCP server tools

Full parameter and return value documentation for each MCP tool. See [MCP server](/features/mcp-server) for setup instructions.

## Read tools

### list\_requests

Paginated listing of captured flows.

**Parameters:**

| Param    | Type   | Default | Description                                                            |
| -------- | ------ | ------- | ---------------------------------------------------------------------- |
| `filter` | string |         | Filter expression (same syntax as [quick filter](/features/filtering)) |
| `offset` | int    | `0`     | Skip first N results                                                   |
| `limit`  | int    | `50`    | Max results (0–200)                                                    |

**Returns:** `{ items: FlowSummary[], total: int }`

### search\_requests

Substring search on host and path.

**Parameters:**

| Param    | Type   | Default    | Description          |
| -------- | ------ | ---------- | -------------------- |
| `query`  | string | *required* | Search term          |
| `offset` | int    | `0`        | Skip first N results |
| `limit`  | int    | `50`       | Max results (0–200)  |

**Returns:** `{ items: FlowSummary[], total: int }`

### get\_request

Full details for a single flow including headers and bodies.

**Parameters:**

| Param           | Type   | Default    | Description                                  |
| --------------- | ------ | ---------- | -------------------------------------------- |
| `id`            | string | *required* | Flow ID                                      |
| `max_body_size` | int    | `0`        | Truncate body to N bytes (0 = no limit)      |
| `dump`          | bool   | `false`    | Write bodies to temp files instead of inline |

**Returns:** `{ meta: FlowMeta, request: { headers, body }, response: { headers, body } }`

When `dump` is true, body fields contain file paths instead of content.

### get\_request\_count

Count flows matching a filter.

**Parameters:**

| Param    | Type   | Default | Description       |
| -------- | ------ | ------- | ----------------- |
| `filter` | string |         | Filter expression |

**Returns:** `{ total: int }`

### export\_har

Export flows to HAR 1.2 format.

**Parameters:**

| Param         | Type      | Default | Description              |
| ------------- | --------- | ------- | ------------------------ |
| `filter`      | string    |         | Filter expression        |
| `request_ids` | string\[] |         | Export specific flow IDs |

**Returns:** HAR document as JSON string.

***

## Simulation tools

### replay\_request

Resend a captured request or compose a new one. The request routes through the proxy and appears in the flow list.

**Parameters (replay existing):**

| Param        | Type   | Description       |
| ------------ | ------ | ----------------- |
| `request_id` | string | Flow ID to replay |

**Parameters (compose new):**

| Param     | Type   | Description            |
| --------- | ------ | ---------------------- |
| `method`  | string | HTTP method            |
| `url`     | string | Full URL               |
| `headers` | object | Header key-value pairs |
| `body`    | string | Request body           |

**Returns:** `{ status_code: int }`

### mock\_response

Intercept matching URLs and return a synthetic response. Creates an internal script that calls `ctx.respondWith()`.

**Parameters:**

| Param           | Type   | Default    | Description          |
| --------------- | ------ | ---------- | -------------------- |
| `match_pattern` | string | *required* | URL glob pattern     |
| `status`        | int    | `200`      | Response status code |
| `headers`       | object |            | Response headers     |
| `body`          | string |            | Response body        |

**Returns:** `{ script_id: string }`

### set\_throttle

Apply bandwidth throttling.

**Parameters:**

| Param        | Type   | Default | Description                     |
| ------------ | ------ | ------- | ------------------------------- |
| `preset`     | string |         | Preset name: `3g`, `4g`, `wifi` |
| `bps`        | int    |         | Custom bytes per second         |
| `latency_ms` | int    |         | Added latency in milliseconds   |

Use `preset` for standard profiles or `bps` + `latency_ms` for custom values.

**Returns:** `{ bps: int, latency_ms: int, active: bool }`

### get\_throttle

Query current throttle state.

**Parameters:** none

**Returns:** `{ bps: int, latency_ms: int, active: bool }`

***

## Script tools

Scripts are identified by opaque IDs (16-character hex strings), not file paths.

### list\_scripts

List all scripts with metadata.

**Parameters:** none

**Returns:** `{ scripts: [{ name, script_id, match_patterns, enabled, category }] }`

### create\_script

Write a new JavaScript hook.

**Parameters:**

| Param            | Type      | Default    | Description         |
| ---------------- | --------- | ---------- | ------------------- |
| `name`           | string    | *required* | Script display name |
| `match_patterns` | string\[] | *required* | URL glob patterns   |
| `code`           | string    | *required* | JavaScript source   |
| `enabled`        | bool      | `true`     | Enable on creation  |

**Returns:** `{ script_id: string }`

### get\_script

Fetch a script's source and metadata.

**Parameters:**

| Param       | Type   | Description |
| ----------- | ------ | ----------- |
| `script_id` | string | Script ID   |

**Returns:** `{ name, match_patterns, enabled, categories, source }`

### toggle\_script

Enable or disable a script without deleting it.

**Parameters:**

| Param       | Type   | Description |
| ----------- | ------ | ----------- |
| `script_id` | string | Script ID   |

**Returns:** `{ enabled: bool }`

### delete\_script

Remove a script file.

**Parameters:**

| Param       | Type   | Description |
| ----------- | ------ | ----------- |
| `script_id` | string | Script ID   |

**Returns:** `{ deleted: bool }`

***

## Data types

### FlowSummary

Returned by `list_requests` and `search_requests`.

| Field          | Type   | Description                         |
| -------------- | ------ | ----------------------------------- |
| `id`           | string | Flow ID                             |
| `method`       | string | HTTP method                         |
| `host`         | string | Request host                        |
| `path`         | string | Request path                        |
| `status`       | int    | Response status code (0 if pending) |
| `content_type` | string | Response content type               |
| `size`         | int    | Response body size in bytes         |
| `duration_ms`  | int    | Round-trip time in milliseconds     |
| `process`      | string | Process name (if resolved)          |
| `process_pid`  | int    | Process ID (if resolved)            |