HTTPeep MCP Guide: Integrating with Codex, Claude, Kimi, and OpenCode

What is HTTPeep MCP

HTTPeep has a built-in MCP (Model Context Protocol) service that allows AI agents to directly read and modify HTTPeep's runtime state and configuration, eliminating the need to switch between GUI and terminal.

Unlike common "read-only packet capture contexts," HTTPeep's MCP doesn't just let you view session lists—it can actually perform operational tasks, such as:

• Starting, stopping, restarting, and pausing the proxy
• Reading and modifying Forward Rules
• Managing DNS Override and environment groups
• Managing Bypass and downstream lists
• Viewing and modifying system proxy and downstream proxy configurations
• Checking and installing root certificates
• Reading and modifying MCP's own settings, starting or stopping the LAN MCP service

Two Integration Methods

HTTPeep MCP currently supports two transport modes:

1. Local stdio Mode

Recommended as the default.

Features:

• No fixed port dependency
• Simple configuration
• Ideal for local agents like Codex, Claude, Kimi, and OpenCode
• Command is always:

httpeep-cli mcp serve

If you installed the HTTPeep desktop app, it automatically installs the built-in httpeep-cli to your user PATH, so you typically don't need to download the CLI separately.

Prerequisites

Before configuring, it's recommended to verify:

httpeep-cli --help
httpeep-cli mcp doctor

If httpeep-cli is not found:

1. Launch the HTTPeep desktop app once
2. Go to Settings -> MCP
3. Click "Repair CLI / PATH"

Using HTTPeep MCP with Codex

Codex's official documentation states that the CLI and IDE extensions share the same MCP configuration. For HTTPeep, the local stdio mode is recommended.

The most straightforward approach is to use the Codex CLI:

codex mcp add httpeep -- httpeep-cli mcp serve
codex mcp list

If you prefer manual configuration file management, you can also edit ~/.codex/config.toml directly:

[mcp_servers.httpeep]
command = "httpeep-cli"
args = ["mcp", "serve"]

If you've already configured other MCP servers in Codex, simply add an httpeep entry the same way.

It's recommended to add a note in your project's AGENTS.md to help Codex use HTTPeep MCP more reliably:

When viewing or modifying proxy, rules, DNS Override, Bypass, certificates, or MCP settings, prefer using HTTPeep MCP.

Using HTTPeep MCP with Claude

If you're using Claude Code, the recommended approach is to add the local stdio MCP directly via CLI:

claude mcp add --transport stdio httpeep -- httpeep-cli mcp serve
claude mcp list

If you prefer configuration file management, you can also add it in claude_desktop_config.json:

{
  "mcpServers": {
    "httpeep": {
      "type": "stdio",
      "command": "httpeep-cli",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

If you've already configured HTTPeep MCP in Claude Desktop, you can import it directly in Claude Code:

claude mcp add-from-claude-desktop
claude mcp list

Using HTTPeep MCP with Kimi

Kimi CLI's official documentation already supports MCP subcommands, making it straightforward to integrate with a local stdio server.

To add HTTPeep:

kimi mcp add --transport stdio httpeep -- httpeep-cli mcp serve

To verify it was added successfully:

kimi mcp list

If you're using Kimi Code for VS Code, you can also add a stdio server in the extension's MCP Servers panel, entering httpeep-cli as the command and mcp serve as the arguments.

If you prefer loading configuration from a file, you can prepare an mcp.json:

{
  "mcpServers": {
    "httpeep": {
      "command": "httpeep-cli",
      "args": ["mcp", "serve"]
    }
  }
}

Then launch with:

kimi --mcp-config-file /path/to/mcp.json

Using HTTPeep MCP with OpenCode

OpenCode's official documentation supports configuring MCP servers in global or project-level opencode.json / opencode.jsonc files. HTTPeep recommends using type: "local".

Common locations include:

• Global config: ~/.config/opencode/opencode.json
• Project config: opencode.json or opencode.jsonc in the project root

Example:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "httpeep": {
      "type": "local",
      "command": ["httpeep-cli", "mcp", "serve"],
      "enabled": true
    }
  }
}

If you want to enable HTTPeep MCP only for specific agents, you can use OpenCode's tools or per-agent configuration for further restrictions.

Current HTTPeep MCP Capabilities

Below are the main capability groups currently available in HTTPeep MCP.

1. Proxy Runtime Control

• View proxy status
• Start proxy
• Stop proxy
• Restart proxy
• Pause/resume traffic capture
• Read and modify proxy configuration

Tool prefix:

httpeep.proxy_*

2. Forward Rules Management

• List rules
• Replace entire ruleset
• Add or update individual rules
• Delete rules

Tool prefix:

httpeep.rules_*

3. DNS Override and Environment Group Management

• Get full DNS configuration
• Replace entire DNS configuration
• Set default environment
• Add/delete environment groups
• Add/delete global host overrides
• Add/delete environment-scoped host overrides

Tool prefix:

httpeep.dns_*

4. Bypass and Downstream List Management

• Get current bypass mode
• Set bypass mode
• Get full bypass store
• Replace full bypass store
• Test single or multiple domains for bypass behavior
• Get and set downstream mode
• Get downstream store

Tool prefix:

httpeep.bypass_*
httpeep.downstream_*

5. Downstream Proxy Configuration

• View current downstream proxy configuration
• Set downstream proxy configuration

Tool prefix:

httpeep.upstream_*

Here, upstream refers to the downstream proxy configuration that HTTPeep uses when forwarding traffic outward.

6. System Proxy Control

• View system proxy status
• Enable system proxy
• Disable system proxy
• Configure system proxy capabilities by protocol

Tool prefixes:

httpeep.proxy_get_system_proxy_status
httpeep.proxy_enable_system_proxy
httpeep.proxy_disable_system_proxy
httpeep.proxy_set_system_proxy_protocols

7. Root Certificate Management

• Check whether the root certificate is installed and trusted
• Install and automatically trust the root certificate

Tools:

httpeep.cert_status
httpeep.cert_install_and_trust

Platform notes:

• macOS / Windows: Uses system trust installation logic
• Linux: Attempts automatic installation first; if permissions are insufficient, returns manual installation instructions

8. MCP Settings and Runtime

• Get MCP settings
• Update MCP settings
• Get MCP runtime status
• Start, stop, restart LAN MCP
• Get built-in CLI information
• Repair CLI PATH installation

Tool prefix:

httpeep.mcp_*

9. Read-Only Diagnostic Tools

In addition to write capabilities, HTTPeep also retains its original diagnostic tools:

• httpeep.health_snapshot
• httpeep.sessions_list
• httpeep.session_detail
• httpeep.stats_overview
• httpeep.logs_tail
• httpeep.events_poll

These tools are suitable for:

• Troubleshooting recent failed sessions
• Reading error logs
• Real-time event polling
• Statistical analysis by domain, process, or device

Recommended Usage

If you're using an AI agent with HTTPeep to debug network issues locally, the recommended workflow is:

1. Launch the HTTPeep desktop app
2. Verify that httpeep-cli is in your PATH
3. Configure httpeep-cli mcp serve in your AI client
4. Let the agent directly view sessions, generate rules, modify bypass or DNS override

FAQ

1. httpeep-cli not found

Open the HTTPeep desktop app, then run "Repair CLI / PATH" in Settings -> MCP.

2. Why recommend stdio instead of HTTP by default?

Because local agents using stdio are more stable—they don't depend on ports and aren't affected by firewalls, listening addresses, or port conflicts. HTTP mode is better suited for "cross-device" or "remote agent" scenarios.

Conclusion

HTTPeep's goal is not just to be a packet capture tool, but to become a network debugging workbench that AI agents can directly control.

If you're already using Codex, Claude, Kimi, or OpenCode, integrating HTTPeep MCP allows you to delegate many previously manual tasks to the agent:

• First, review recent failed requests
• Then analyze whether bypass is needed
• Automatically add a Forward Rule
• Modify DNS Override environments
• Finally, restart the proxy directly to verify results

This is where HTTPeep MCP delivers the most value: making "viewing traffic" and "modifying configuration" a continuous AI workflow, rather than fragmented across multiple interfaces and commands.