Skip to content

Enterprise Networking & Observability Update (Proxy, Harpoon, OAuth, Admin UI)

Choose a tag to compare

View all tags
@denyska-oai denyska-oai released this 07 Feb 01:34
· 182 commits to master since this release
v.0.0.3
aba0bd2

Executive summary

Since v0.0.2, tunnel-client has moved from a single-lane MCP bridge to a more enterprise-ready platform with:

  • first-class outbound proxy controls and proxy health visibility
  • Harpoon, an embedded allowlisted outbound HTTP Client MCP service used for OAUth discovery and registration
  • custom CA bundle support for private PKI environments
  • expanded OAuth discovery diagnostics and runtime visibility
  • a significantly upgraded monitoring/admin UI for day-2 operations

This release is focused on enterprise network compatibility, safer outbound access patterns, and better operator observability.

Major features

1) Outbound proxy support (enterprise networking)

tunnel-client now supports explicit outbound proxy routing across major traffic paths:

  • global proxy: --http-proxy
  • control plane: --control-plane.http-proxy
  • MCP default and per-channel overrides: --mcp.http-proxy, --mcp.server-url="...,http-proxy=..."
  • Harpoon: --harpoon.http-proxy

Key behaviors:

  • explicit proxy settings can be sourced directly or from env:VARNAME
  • deterministic precedence is now documented and enforced
  • when an explicit proxy is set for a route, environment proxy rules (including NO_PROXY) are ignored for that route
  • proxy identity and route mode (direct vs proxy) are exposed in the admin UI
  • proxy reachability checks run continuously (--proxy.check-interval) with status/history visible in UI and metrics

Why it matters:

  • easier deployment in locked-down enterprise networks
  • faster diagnosis of proxy outages and route misconfiguration

2) Harpoon added (embedded constrained outbound HTTP MCP)

Harpoon is a built-in MCP server/channel (harpoon) for controlled outbound HTTP calls.

What Harpoon is:

  • an embedded tool surface for calling pre-registered targets by label
  • not a free-form HTTP client for arbitrary destinations
  • used for OAuth flows that require controlled outbound calls, including:
    • OAuth discovery
    • OAuth client registration
    • token refresh

What it provides:

  • target allowlisting via --harpoon.target="label=...,url=...,desc=..."
  • request guardrails (method/header restrictions, timeout, size, redirect limits)
  • optional payload capture for debugging (--harpoon.capture-payloads)
  • optional additional transport exposure for Harpoon MCP (--harpoon.additional-transport=http-streamable)
  • private-host registration filters to help govern what can be auto-included

Operational behavior:

  • the harpoon channel is enabled only when at least one valid target is registered
  • otherwise harpoon commands return unsupported_channel

Why it matters:

  • enables controlled outbound integrations without exposing raw arbitrary egress
  • improves security posture for tool-driven HTTP workflows

3) Custom CA bundles for private PKI

tunnel-client now supports additive trust extension with:

  • --ca-bundle /path/to/ca-bundle.pem (or CA_BUNDLE)

Scope:

  • applies to outbound TLS connections used by control plane, MCP HTTP, OAuth discovery, and Harpoon
  • does not replace system trust; it extends it

Visibility:

  • trust metadata is logged at startup
  • admin UI System tab reports bundle path, certificate count, parse status/errors, and certificate metadata

Why it matters:

  • supports enterprises with internal/intermediate CAs and TLS-intercepting proxies

4) OAuth discovery improvements and diagnostics

OAuth handling has been expanded with a dedicated discovery pipeline and visibility:

  • startup discovery of OAuth Protected Resource Metadata
  • discovery URL prioritization and retry handling
  • discovery state exposed in admin UI (/api/oauth) with timeline/status details
  • auth-server metadata fetch integration and surfaced selection details
  • discovered host information can be published for internal routing/registration flows

Existing OAuth forwarding behavior remains in place:

  • Authorization forwarding for MCP calls
  • discovery URL/resource rewriting to tunnel-service endpoints for the same tunnel

Why it matters:

  • easier OAuth onboarding/debugging with clear runtime diagnostics instead of opaque failures

5) Monitoring/admin UI overhaul

The embedded web UI was significantly upgraded (Svelte/TypeScript build pipeline + embedded static assets).

New or expanded operator views:

  • Overview: control plane status, tunnel metadata, channel availability, proxy mode/source
  • Metrics: key poll/queue/worker health from Prometheus metrics
  • OAuth: discovery timeline and metadata fetch detail
  • Harpoon: status, targets, recent calls, policy/proxy visibility
  • System: TLS trust report, proxy identity map, route reachability + history
  • Logs: live SSE stream with filter/pause/search and optional attribute expansion

Why it matters:

  • substantially better day-2 operability from a single local console (/ui)

Additional notable changes

  • channel-aware routing introduced (main, harpoon, and additional configured channels)
  • response payloads now include resolved channel
  • JSON-RPC notifications can be forwarded during streaming flows when connector requests text/event-stream
  • SSE behavior is now explicit and documented: connector must request SSE; GET /v1/mcp is not a streaming endpoint
  • expanded test coverage across proxy, Harpoon, OAuth, CA bundles, and UI behavior

Operator impact / migration notes

  • main channel binding is now explicitly required
  • proxy behavior is more explicit and can differ from legacy env-only expectations when route-level proxies are configured
  • Harpoon requires explicit target registration before use
  • if relying on streamed progress, ensure connector sends Accept: text/event-stream

Full Changelog: v0.0.2...v.0.0.3

Assets 9
Loading