MCPAI AgentCodexClaudeKimiOpenCode

HTTPeep MCP 使用指南：接入 Codex、Claude、Kimi 与 OpenCode

本文介绍如何把 HTTPeep 的 MCP 服务接入 Codex、Claude、Kimi 和 OpenCode，并说明 HTTPeep MCP 当前支持的代理控制、规则管理、DNS Override、Bypass、证书与 MCP 设置能力。

什么是 HTTPeep MCP

HTTPeep 内置了 MCP（Model Context Protocol）服务，AI agent 可以直接读取和修改 HTTPeep 的运行状态与配置，而不需要你在 GUI 和终端之间来回切换。

和常见的“只读抓包上下文”不同，HTTPeep 的 MCP 不只是能看会话列表，还能真正执行运维动作，例如：

  • 启动、停止、重启、暂停代理
  • 读取和修改 Forward Rules
  • 管理 DNS Override 与环境组
  • 管理 Bypass 与 downstream 列表
  • 查看和修改系统代理、下游代理配置
  • 检查并安装根证书
  • 读取和修改 MCP 自身设置，启动或停止局域网 MCP 服务

两种接入方式

HTTPeep MCP 目前支持两种传输方式：

1. 本机 stdio 模式

推荐默认使用。

特点：

  • 不依赖固定端口
  • 配置简单
  • 适合 Codex、Claude、Kimi、OpenCode 这类本机 agent
  • 命令固定为：
httpeep-cli mcp serve

如果你安装的是 HTTPeep 桌面版，应用会自动把内置 httpeep-cli 安装到用户 PATH 中，一般不需要额外下载 CLI。

2. 局域网 streamable-http 模式

适合需要让其他设备、远端 agent，或局域网内的开发环境访问 HTTPeep MCP 的场景。

默认地址：

http://127.0.0.1:46263/mcp

启用方式：

  1. 打开 HTTPeep
  2. 进入 Settings -> MCP
  3. 打开“局域网 MCP”开关

说明：

  • 只有开启后，HTTPeep 才会常驻启动这个 HTTP MCP 服务
  • 如果端口 46263 被占用，GUI 会提示错误
  • 本机默认 stdio 模式不受这个端口影响

安装前准备

开始配置之前，建议先确认：

httpeep-cli --help
httpeep-cli mcp doctor

如果 httpeep-cli 找不到：

  1. 先启动一次 HTTPeep 桌面应用
  2. 到 Settings -> MCP
  3. 点击“修复 CLI / PATH”

在 Codex 中使用 HTTPeep MCP

Codex 官方文档说明，CLI 和 IDE 扩展共享同一份 MCP 配置。对于 HTTPeep，推荐使用本机 stdio 模式。

最直接的方式是用 Codex CLI 添加：

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

如果你更习惯手动维护配置文件，也可以直接编辑 ~/.codex/config.toml：

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

如果你已经在 Codex 中配置过其他 MCP server，直接按同样方式新增一个 httpeep 条目即可。

如果你要改用局域网 HTTP MCP，也可以这样添加：

codex mcp add httpeep --url http://127.0.0.1:46263/mcp

建议在项目的 AGENTS.md 中加一句提示，帮助 Codex 更稳定地使用 HTTPeep MCP：

需要查看或修改代理、规则、DNS Override、Bypass、证书或 MCP 设置时，优先使用 HTTPeep MCP。

在 Claude 中使用 HTTPeep MCP

如果你用的是 Claude Code，推荐直接通过 CLI 添加本地 stdio MCP：

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

如果你更习惯通过配置文件维护，也可以在 claude_desktop_config.json 中添加：

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

如果你已经在 Claude Desktop 中配置好了 HTTPeep MCP，也可以在 Claude Code 中直接导入：

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

如果你更习惯在 Claude.ai 里统一管理，也可以把 HTTPeep 的局域网 MCP 打开后，按 HTTP MCP 地址接入。

在 Kimi 中使用 HTTPeep MCP

Kimi CLI 官方文档已经支持 MCP 子命令，接入本地 stdio server 最直接。

添加 HTTPeep：

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

查看是否添加成功：

kimi mcp list

如果你使用的是 Kimi Code for VS Code，也可以在扩展的 MCP 服务器 面板里新增一个 stdio server，命令填写 httpeep-cli，参数填写 mcp serve。

如果你想通过配置文件一次性加载，也可以准备一个 mcp.json：

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

然后启动：

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

如果你已经启用了 HTTPeep 的局域网 MCP，也可以按 Kimi 的 HTTP MCP 方式直接接入：

kimi mcp add --transport http httpeep http://127.0.0.1:46263/mcp

在 OpenCode 中使用 HTTPeep MCP

OpenCode 官方文档支持在全局或项目级 opencode.json / opencode.jsonc 中配置 MCP server。HTTPeep 推荐使用 type: "local"。

常见位置包括：

  • 全局配置：~/.config/opencode/opencode.json
  • 项目配置：项目根目录下的 opencode.json 或 opencode.jsonc

示例：

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

如果你希望只在特定 agent 中启用 HTTPeep MCP，可以结合 OpenCode 的 tools 或 per-agent 配置做进一步限制。

如果你要接局域网 HTTP MCP，则改成 remote：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "httpeep": {
      "type": "remote",
      "url": "http://127.0.0.1:46263/mcp",
      "enabled": true
    }
  }
}

HTTPeep MCP 目前有哪些能力

下面是当前 HTTPeep MCP 的主要能力分组。

1. 代理运行态控制

  • 查看代理状态
  • 启动代理
  • 停止代理
  • 重启代理
  • 暂停/恢复抓包
  • 读取和修改代理配置

对应工具前缀：

httpeep.proxy_*

2. Forward Rules 管理

  • 获取规则列表
  • 整体替换规则
  • 新增或更新单条规则
  • 删除规则

对应工具前缀：

httpeep.rules_*

3. DNS Override 与环境组管理

  • 获取整份 DNS 配置
  • 整体替换 DNS 配置
  • 设置默认环境
  • 新增、删除环境组
  • 新增、删除全局 Host Override
  • 新增、删除环境级 Host Override

对应工具前缀：

httpeep.dns_*

4. Bypass 与 downstream 列表管理

  • 获取当前 bypass mode
  • 设置 bypass mode
  • 获取完整 bypass store
  • 替换完整 bypass store
  • 测试单个或多个域名是否会 bypass
  • 获取和设置 downstream mode
  • 获取 downstream store

对应工具前缀：

httpeep.bypass_*
httpeep.downstream_*

5. 下游代理配置

  • 查看当前 downstream proxy 配置
  • 设置 downstream proxy 配置

对应工具前缀：

httpeep.upstream_*

这里的 upstream 指的是 HTTPeep 代理向外转发时使用的下游代理配置。

6. 系统代理控制

  • 查看系统代理状态
  • 启用系统代理
  • 关闭系统代理
  • 按协议设置系统代理能力

对应工具前缀：

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

7. 根证书能力

  • 检查根证书是否已安装、是否受信任
  • 安装并尽量自动信任根证书

对应工具：

httpeep.cert_status
httpeep.cert_install_and_trust

平台说明：

  • macOS / Windows：直接走系统信任安装逻辑
  • Linux：优先尝试自动安装；若权限不足，会返回手动安装提示

8. MCP 自身设置与运行态

  • 获取 MCP 设置
  • 更新 MCP 设置
  • 获取 MCP 运行状态
  • 启动、停止、重启局域网 MCP
  • 获取内置 CLI 信息
  • 修复 CLI PATH 安装

对应工具前缀：

httpeep.mcp_*

9. 只读诊断能力

除了写能力，HTTPeep 也继续保留原有的诊断型工具：

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

这些工具适合做：

  • 最近异常会话排查
  • 错误日志读取
  • 实时事件轮询
  • 某个域名、进程或设备的统计分析

推荐使用方式

如果你是在本机用 AI agent 配合 HTTPeep 调试网络问题，推荐：

  1. 启动 HTTPeep 桌面应用
  2. 确认 httpeep-cli 已经在 PATH 中
  3. 在 AI 客户端中配置 httpeep-cli mcp serve
  4. 让 agent 直接查看会话、生成规则、修改 bypass 或 DNS override

如果你需要让其他设备或局域网 agent 访问 HTTPeep：

  1. 在 HTTPeep 设置里开启“局域网 MCP”
  2. 使用 http://127.0.0.1:46263/mcp 或你的自定义地址接入

常见问题

1. httpeep-cli 找不到

先打开 HTTPeep 桌面应用，然后在 Settings -> MCP 中执行一次“修复 CLI / PATH”。

2. 局域网 MCP 启动失败

通常是以下原因：

  • 46263 端口被占用
  • 你把代理端口也设成了 46263
  • CLI 路径损坏

可先执行：

httpeep-cli --format json mcp doctor

3. 为什么推荐 stdio，而不是默认 HTTP

因为本机 agent 使用 stdio 更稳定，不依赖端口，也不会受到防火墙、监听地址和端口冲突影响。HTTP 模式更适合“跨设备”或“远端 agent”场景。

结语

HTTPeep 的目标不是只做一个抓包工具，而是做一个可以被 AI agent 直接调用的网络调试工作台。

如果你已经在使用 Codex、Claude、Kimi 或 OpenCode，把 HTTPeep MCP 接进去之后，很多原本需要手工完成的动作都可以直接交给 agent：

  • 先看最近失败请求
  • 再分析是否需要 bypass
  • 自动补一条 Forward Rule
  • 修改 DNS Override 环境
  • 最后直接重启代理验证结果

这就是 HTTPeep MCP 最有价值的地方：让“看流量”和“改配置”变成一个连续的 AI 工作流，而不是分裂在多个界面和命令之间。

← 返回博客列表