MCP Setup
Set up AI agent integration with HTTPeep MCP, Step-by-step setup for Codex, Claude Code, Kimi, and OpenCode — including config files, CLI commands, and how to fix common PATH issues.
This page walks you through connecting an AI agent to HTTPeep's MCP server. All agents use the local stdio transport by default, which means your agent launches httpeep-cli mcp serve automatically — you don't need to start it manually or open a port.
Prerequisites
Before configuring any agent, make sure the following are true:
- The HTTPeep desktop app is installed and running
httpeep-cliis available in your shell's PATH
Verify httpeep-cli is installed
httpeep-cli --versionIf this returns a version number, you're ready to configure your agent.
Fix a missing httpeep-cli
The HTTPeep desktop app installs httpeep-cli automatically on first launch. If the command isn't found:
Launch it from your Applications folder, taskbar, or Start Menu.
Open Settings from the menu, then select the MCP tab.
This re-runs the PATH installation. Once complete, restart your terminal and run httpeep-cli --version again to confirm.
Run the MCP doctor
Before or after configuring your agent, run the diagnostics check:
httpeep-cli mcp doctorExpected output when everything is working:
MCP Doctor Report
─────────────────────────────────────────────
✓ httpeep-cli found at /usr/local/bin/httpeep-cli (v0.8.4)
✓ Proxy engine reachable (port 8080)
✓ MCP service responding
✓ stdio transport: OK
✓ LAN service: running on port 9090
─────────────────────────────────────────────
All checks passed.If any check fails, the doctor output tells you which component is unreachable and what to fix.
Agent setup
The fastest way to add HTTPeep to Codex is with the CLI:
codex mcp add httpeep -- httpeep-cli mcp serveVerify it was added:
codex mcp listManual configuration — if you prefer to edit the config file directly, add this to ~/.codex/config.toml:
[mcp_servers.httpeep]
command = "httpeep-cli"
args = ["mcp", "serve"]If you've already configured other MCP servers in Codex, add the httpeep entry alongside them in the same file.
Add a note to your project's AGENTS.md to help Codex apply HTTPeep tools more reliably:
When viewing or modifying proxy, rules, DNS Override, Bypass, certificates,
or MCP settings, prefer using HTTPeep MCP.Codex reads AGENTS.md at the start of every session and uses it to guide tool selection.
Add HTTPeep using the Claude CLI:
claude mcp add --transport stdio httpeep -- httpeep-cli mcp serveVerify it was added:
claude mcp listManual configuration — add this entry to claude_desktop_config.json:
{
"mcpServers": {
"httpeep": {
"type": "stdio",
"command": "httpeep-cli",
"args": ["mcp", "serve"],
"env": {}
}
}
}Already configured in Claude Desktop? Import it directly into Claude Code:
claude mcp add-from-claude-desktop
claude mcp listAdd HTTPeep using the Kimi CLI:
kimi mcp add --transport stdio httpeep -- httpeep-cli mcp serveVerify it was added:
kimi mcp listKimi Code for VS Code — open the MCP Servers panel in the extension settings, add a new stdio server with:
- Command:
httpeep-cli - Arguments:
mcp serve
File-based configuration — create an mcp.json file:
{
"mcpServers": {
"httpeep": {
"command": "httpeep-cli",
"args": ["mcp", "serve"]
}
}
}Then launch Kimi with:
kimi --mcp-config-file /path/to/mcp.jsonOpenCode reads MCP configuration from a JSON file at either the global or project level. Add the httpeep entry with "type": "local".
Global config — ~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"httpeep": {
"type": "local",
"command": ["httpeep-cli", "mcp", "serve"],
"enabled": true
}
}
}Project config — opencode.json or opencode.jsonc in the project root. Use this to enable HTTPeep only for specific projects:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"httpeep": {
"type": "local",
"command": ["httpeep-cli", "mcp", "serve"],
"enabled": true
}
}
}If you have an existing opencode.json, add the "httpeep" block inside the existing "mcp" object.
FAQ
MCP Overview
AI & MCP: give your AI agent network control, HTTPeep's built-in MCP server lets AI agents read live traffic, modify forward rules, manage DNS, and control the proxy — not just observe it.
Troubleshooting
Common issues and recovery paths for certificates, proxy setup, CLI, and MCP integration.