> ## 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 server

> Expose httpmon to LLM agents via the Model Context Protocol

httpmon includes a built-in [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets LLM agents inspect captured traffic, replay requests, manage scripts, and control throttling — all programmatically.

## Starting the MCP server

Pass `--mcp` to enable the server on the default address (`127.0.0.1:9551`):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
httpmon --mcp
```

Use `--mcp-addr` for a custom address:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
httpmon --mcp-addr 127.0.0.1:9000
```

When the MCP server is active, the status bar shows **MCP :9551** (or your custom port).

## Authentication

The MCP server uses bearer token authentication. A 32-byte random hex token is generated on first use and stored in `~/.httpmon/config.json` (in the `mcp_token` field).

Every request must include the token:

```
Authorization: Bearer <token>
```

Print the token without starting the proxy:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
httpmon --mcp-token
```

The token is also printed to stderr on startup:

```
MCP server listening on 127.0.0.1:9551 (token: 3f8a2c...)
```

## Available tools

The server exposes 14 tools organized into three categories:

### Read tools

Inspect captured traffic without side effects.

| Tool                | Description                                 |
| ------------------- | ------------------------------------------- |
| `list_requests`     | Paginated flow listing with optional filter |
| `search_requests`   | Substring search on host and path           |
| `get_request`       | Full flow details (headers, bodies)         |
| `get_request_count` | Count flows matching a filter               |
| `export_har`        | Export flows to HAR 1.2 JSON                |

### Simulation tools

Replay requests and control proxy behavior.

| Tool             | Description                                            |
| ---------------- | ------------------------------------------------------ |
| `replay_request` | Resend a captured request or compose a new one         |
| `mock_response`  | Intercept matching URLs and return synthetic responses |
| `set_throttle`   | Apply bandwidth throttling (preset or custom)          |
| `get_throttle`   | Query current throttle state                           |

### Script tools

Manage JavaScript hooks.

| Tool            | Description                          |
| --------------- | ------------------------------------ |
| `list_scripts`  | All scripts with metadata and status |
| `create_script` | Write a new JavaScript hook          |
| `get_script`    | Fetch script source and metadata     |
| `toggle_script` | Enable or disable a script           |
| `delete_script` | Remove a script                      |

For full parameter and return value documentation, see the [MCP tools reference](/reference/mcp-tools).

## Transport

The server uses HTTP Streamable transport (JSON-RPC 2.0 over HTTP POST). It listens on localhost only by default for security.

## Integration

See [MCP integration guide](/features/mcp-integration) for configuration snippets for Claude Desktop, Cursor, and Claude Code.