MCPAPI ReferenceHTTP ProxyDeveloper ToolsAI Agent

HTTPeep MCP Complete Tool Reference: All 66 Tools Explained

Complete reference for all HTTPeep MCP tools—proxy control, session queries, performance diagnostics, forwarding rules, DNS override, bypass, certificates, and MCP settings. With parameter details and example outputs.

Overview

HTTPeep exposes 66 MCP tools across 9 categories. This reference is a quick-lookup guide for developers who have already connected their AI agent to HTTPeep and want to know exactly what each tool does and what parameters it accepts.

New to HTTPeep MCP? See the setup guide first to connect your AI agent.

The tools are grouped as follows:

| Category | Tools | Purpose | |----------|-------|---------| | Proxy Control | 12 | Start/stop/configure the proxy engine | | Session Queries | 5 | List, inspect, export, and replay sessions | | Performance | 3 | Slow APIs, logs, live events | | Forward Rules | 10 | Route/rewrite/block traffic rules | | Bypass | 6 | Skip proxy for specific hosts | | DNS Override | 9 | Map hostnames to custom IPs | | Downstream Proxy | 5 | Chain to another proxy | | Certificates | 2 | TLS/HTTPS certificate management | | MCP Settings | 8 | Control the MCP service itself |

Data Masking

By default, HTTPeep's MCP masks sensitive fields before returning data to the AI agent. This affects:

  • Authorization header values (shown as [MASKED])
  • Cookie and Set-Cookie header values
  • Request/response body fields matching configured patterns (e.g., password, token, secret)

To check or modify the current masking settings:

httpeep_mcp_get_settings   # View current masking config
httpeep_mcp_update_settings # Update masking rules

Masking is per-session and does not modify stored data—only the values returned via MCP.

Proxy Control (12 Tools)

httpeep_proxy_start

Start the proxy engine. No parameters required.

// Response
{ "success": true, "port": 8080, "message": "Proxy started" }

httpeep_proxy_stop

Stop the proxy engine. Captured sessions are preserved.

httpeep_proxy_restart

Restart the proxy (stop + start in one call). Useful after config changes.

httpeep_proxy_status

Returns current proxy state including port, uptime, session count, and whether system proxy is active.

{
  "running": true,
  "paused": false,
  "port": 8080,
  "uptime_seconds": 3600,
  "session_count": 142,
  "system_proxy_active": true
}

httpeep_proxy_set_paused

Pause or resume traffic capture without stopping the proxy.

// Parameters
{ "paused": true }

httpeep_proxy_get_config

Returns the full proxy configuration (port, TLS settings, capture filters, etc.).

httpeep_proxy_update_config

Update proxy configuration. Changes take effect on next restart.

// Parameters (all optional, only send what you want to change)
{
  "port": 8080,
  "capture_body": true,
  "max_body_size_kb": 512,
  "ignore_connect_errors": false
}

httpeep_proxy_enable_system_proxy

Set HTTPeep as the system proxy (HTTP + HTTPS). Equivalent to enabling "System Proxy" in the UI.

httpeep_proxy_disable_system_proxy

Remove HTTPeep from system proxy settings.

httpeep_proxy_get_system_proxy_status

Check whether the OS system proxy is currently pointing to HTTPeep.

httpeep_proxy_set_system_proxy_protocols

Choose which protocols to intercept at the system level.

// Parameters
{ "http": true, "https": true, "socks": false }

httpeep_health_snapshot

Returns a combined health snapshot: proxy status, cert validity, MCP status, system proxy state, and recent error counts.

Session Queries (5 Tools)

httpeep_sessions_list

The primary tool for querying captured traffic. Supports rich filtering.

// Parameters (all optional)
{
  "host": "api.example.com",       // Filter by hostname (exact or contains)
  "method": "POST",                 // HTTP method filter
  "status_gte": 400,               // Status code ≥
  "status_lte": 599,               // Status code ≤
  "path_contains": "/api/v2",      // URL path substring
  "limit": 20,                     // Default 20, max 100
  "offset": 0,                     // Pagination offset
  "since_ms": 1712000000000,       // Only sessions after this timestamp
  "order": "desc"                  // "desc" (newest first) or "asc"
}

Returns an array of SessionSummaryMcp objects (see Data Structures below).

httpeep_session_detail

Get the full detail of a single session including request/response headers, body, and timing.

// Parameters
{ "session_id": "abc123def456" }

Returns a SessionDetailMcp object.

httpeep_session_replay

Re-send a captured request, optionally with modifications.

// Parameters
{
  "session_id": "abc123def456",
  "override_headers": {
    "Authorization": "Bearer new-token-here"
  },
  "override_body": "{\"key\": \"new-value\"}"
}

httpeep_sessions_export

Export sessions to HAR format for sharing or archiving.

// Parameters
{
  "session_ids": ["abc123", "def456"],  // Optional: specific sessions
  "format": "har"                        // Currently only "har"
}

httpeep_stats_overview

Summary statistics: total sessions, error rate, top hosts, top status codes.

Performance Diagnostics (3 Tools)

httpeep_stats_slow_apis

Find the slowest requests in recent sessions.

// Parameters
{
  "threshold_ms": 500,    // Only return requests slower than this
  "limit": 10,            // Max results
  "since_minutes": 30     // Look back window
}
// Response item
{
  "session_id": "abc123",
  "method": "GET",
  "url": "https://api.example.com/v2/reports",
  "status": 200,
  "duration_ms": 1840,
  "request_size_bytes": 0,
  "response_size_bytes": 24500
}

httpeep_logs_tail

Retrieve the most recent entries from HTTPeep's internal log.

// Parameters
{
  "lines": 50,              // Number of log lines
  "level": "warn"           // "debug" | "info" | "warn" | "error"
}

Useful for diagnosing proxy errors that don't appear in the session list (e.g., TLS handshake failures, connection timeouts).

httpeep_events_poll

Long-poll for new session events. Returns new sessions since the last poll cursor.

// Parameters
{ "cursor": "last-event-id-from-previous-poll", "timeout_ms": 5000 }

Use this for real-time monitoring: poll in a loop to get a live feed of new sessions as they arrive.

Forward Rules (10 Tools)

Forward rules let you rewrite, redirect, block, or rate-limit traffic based on URL patterns.

httpeep_rules_list

List all current forward rules.

httpeep_rules_upsert

Create or update a forward rule.

// Parameters
{
  "id": "rule-001",           // Optional: omit to auto-generate
  "name": "Redirect staging",
  "enabled": true,
  "match": {
    "host": "api.myapp.com",
    "path_pattern": "/v2/*",
    "methods": ["GET", "POST"]
  },
  "action": {
    "type": "forward",         // "forward" | "block" | "rate_limit" | "rewrite"
    "target_host": "staging-api.myapp.com",
    "target_port": 443
  }
}

httpeep_rules_delete

Delete a rule by ID.

{ "id": "rule-001" }

httpeep_rules_delete_all

Remove all forward rules.

httpeep_rules_replace_all

Atomically replace the entire ruleset. Useful for applying a pre-configured set.

httpeep_rules_export

Export current rules as JSON (for backup or sharing).

httpeep_rules_import

Import rules from a JSON export.

httpeep_rules_reset

Reset rules to the factory default (empty ruleset).

httpeep_rules_test

Test whether a given request URL would match any rule, and which action would apply.

// Parameters
{
  "method": "GET",
  "url": "https://api.myapp.com/v2/users"
}

httpeep_rules_validate

Validate a rule object's syntax without saving it.

Bypass Rules (6 Tools)

Bypass rules let specific hosts skip the proxy entirely (traffic goes direct, unlogged).

httpeep_bypass_get_mode

Returns the current bypass mode: "whitelist" (only listed hosts bypass) or "blacklist" (all bypass except listed).

httpeep_bypass_set_mode

Switch between whitelist and blacklist bypass mode.

{ "mode": "whitelist" }

httpeep_bypass_get_store

List all hostnames/patterns in the bypass list.

httpeep_bypass_replace_store

Replace the entire bypass list.

{
  "entries": [
    "localhost",
    "*.internal.myapp.com",
    "127.0.0.1"
  ]
}

httpeep_bypass_test

Test whether a single host would be bypassed under current rules.

{ "host": "metrics.internal.myapp.com" }

httpeep_bypass_batch_test

Test multiple hosts at once.

{
  "hosts": ["api.myapp.com", "localhost", "fonts.googleapis.com"]
}

DNS Override (9 Tools)

DNS override lets you map hostnames to custom IP addresses—useful for environment switching, staging/production testing, and simulating different server setups.

Concepts

  • Global overrides: Apply regardless of active environment
  • Environments: Named groups of overrides that can be switched atomically
  • Active environment: Only one environment is "active" at a time

httpeep_dns_get_configs

Returns all DNS override configurations: global hosts, all environments, and the currently active environment.

httpeep_dns_upsert_global_host

Add or update a global hostname override.

{
  "host": "api.myapp.com",
  "ip": "10.0.1.45",
  "comment": "Points to staging server"
}

httpeep_dns_delete_global_host

Remove a global hostname override.

{ "host": "api.myapp.com" }

httpeep_dns_upsert_environment

Create or update a named environment (e.g., "staging", "local-dev").

{
  "name": "staging",
  "description": "Staging environment overrides"
}

httpeep_dns_delete_environment

Delete an environment and all its host overrides.

httpeep_dns_upsert_environment_host

Add or update a host override within a specific environment.

{
  "environment": "staging",
  "host": "api.myapp.com",
  "ip": "10.0.1.45"
}

httpeep_dns_delete_environment_host

Remove a specific host override from an environment.

httpeep_dns_set_default_environment

Activate an environment (or clear the active environment).

{ "environment": "staging" }  // Pass null to deactivate all environments

httpeep_dns_replace_configs

Atomically replace all DNS override configurations (global + environments).

Downstream Proxy (5 Tools)

Configure HTTPeep to forward all traffic through another proxy (e.g., a corporate proxy, Burp Suite, or a cloud proxy service).

httpeep_downstream_get_mode

Returns current downstream mode: "direct", "system", or "custom".

httpeep_downstream_set_mode

Switch downstream mode.

{ "mode": "custom" }

httpeep_downstream_get_store

Get the configured downstream proxy details.

httpeep_upstream_get_config

Get upstream proxy configuration (authentication, exceptions).

httpeep_upstream_set_config

Configure the upstream proxy.

{
  "host": "proxy.corp.example.com",
  "port": 8888,
  "auth": {
    "username": "user",
    "password": "pass"
  },
  "no_proxy": ["localhost", "*.internal.corp"]
}

Certificate Management (2 Tools)

httpeep_cert_status

Returns the status of HTTPeep's root CA certificate.

{
  "exists": true,
  "trusted_by_os": true,
  "expires_at": "2028-04-13T00:00:00Z",
  "fingerprint": "SHA256:abc123..."
}

httpeep_cert_install_and_trust

Trigger the root CA installation and OS trust flow. On macOS this opens the Keychain prompt; on Windows, the certificate store dialog.

MCP Settings (8 Tools)

httpeep_mcp_get_settings

Returns current MCP configuration including masking rules, LAN service status, and allowed origins.

httpeep_mcp_update_settings

Update MCP settings.

{
  "mask_auth_headers": true,
  "mask_cookie_headers": true,
  "body_mask_patterns": ["password", "secret", "token", "api_key"]
}

httpeep_mcp_get_runtime_status

Returns the running status of the MCP service(s): stdio, LAN HTTP port, connected clients.

httpeep_mcp_get_bundled_cli_info

Returns version and path information for the bundled httpeep-cli binary.

httpeep_mcp_repair_cli_path_installation

Re-run the CLI PATH installation if httpeep-cli isn't found in your shell. Equivalent to Settings → MCP → Repair CLI/PATH.

httpeep_mcp_start_lan_service

Start the LAN MCP HTTP server (allows other machines on the network to connect).

{ "port": 9090 }  // Optional: defaults to configured port

httpeep_mcp_stop_lan_service

Stop the LAN MCP HTTP server.

httpeep_mcp_restart_lan_service

Restart the LAN MCP HTTP server (pick up config changes).

Data Structures

SessionSummaryMcp

Returned by httpeep_sessions_list:

{
  "session_id": "abc123def456",
  "method": "POST",
  "url": "https://api.example.com/v2/users",
  "host": "api.example.com",
  "status": 200,
  "duration_ms": 234,
  "request_size_bytes": 512,
  "response_size_bytes": 1024,
  "timestamp": "2026-04-13T10:30:00Z",
  "is_https": true,
  "flags": {
    "has_error": false,
    "is_websocket": false,
    "is_streaming": false
  }
}

SessionDetailMcp

Returned by httpeep_session_detail:

{
  "session_id": "abc123def456",
  "method": "POST",
  "url": "https://api.example.com/v2/users",
  "request": {
    "headers": {
      "Content-Type": "application/json",
      "Authorization": "[MASKED]",
      "User-Agent": "MyApp/1.0"
    },
    "body": "{\"name\": \"Alice\", \"email\": \"alice@example.com\"}",
    "body_truncated": false
  },
  "response": {
    "status": 201,
    "headers": {
      "Content-Type": "application/json",
      "X-Request-Id": "req_xyz789"
    },
    "body": "{\"id\": \"usr_001\", \"name\": \"Alice\"}",
    "body_truncated": false
  },
  "timing": {
    "started_at": "2026-04-13T10:30:00.000Z",
    "dns_ms": 12,
    "connect_ms": 45,
    "tls_ms": 38,
    "ttfb_ms": 180,
    "total_ms": 234
  },
  "tls": {
    "protocol": "TLSv1.3",
    "cipher": "TLS_AES_128_GCM_SHA256",
    "server_cert_subject": "CN=api.example.com"
  },
  "flags": {
    "has_error": false,
    "is_websocket": false,
    "is_streaming": false,
    "bypass_active": false
  }
}

Key timing fields:

  • dns_ms — DNS resolution time
  • connect_ms — TCP connection establishment
  • tls_ms — TLS handshake (0 for plain HTTP)
  • ttfb_ms — Time to first byte (server processing time)
  • total_ms — Full round-trip duration

For practical usage examples and debugging workflows using these tools, see Give Your AI Agent Network Vision.

← Back to blog