Define the supported user journey for host-local managed MCP servers #8406

Problem statement

A NemoClaw operator can run a custom Model Context Protocol (MCP) server on the host but cannot connect it through managed MCP without another deployment layer.

Managed MCP accepts authenticated public HTTPS endpoints. It rejects loopback, private, and OpenShell host-alias targets. The documentation tells the operator to expose a local MCP server through public HTTPS, but it does not define a durable deployment pattern.

The resulting user journey is predictable:

1. The operator runs an MCP server on host loopback.
2. mcp add rejects the local URL.
3. The operator exposes the server through a Cloudflare Quick Tunnel.
4. mcp add initially succeeds and records the current public DNS answers in allowed_ips.
5. Cloudflare later returns an address outside those pins, or a tunnel restart creates a new hostname.
6. OpenShell correctly fails closed with CONNECT 403.
7. The operator has no documented durable path that keeps the server host-local and preserves managed credential replacement and MCP policy enforcement.

This is not an agent-specific defect. The same contract applies to OpenClaw, Hermes, and LangChain Deep Agents Code. Scenario authors can also follow this path; a current Remy scenario implementation exposes its host-owned MCP broker through a Quick Tunnel.

History and requirement disposition

Issue #566 began with the host-local requirement:

• launch or reuse an MCP server on the host;
• keep its credentials outside the sandbox; and
• connect the sandbox through a narrow OpenShell policy.

The June 30 design decision accepted native OpenShell MCP integration and explicitly superseded the proposed host proxy, host-launched subprocess, plaintext host route, and secret-bearing restart model.

PR #5876 then implemented authenticated public HTTPS Streamable HTTP endpoints. OpenShell owns the MCP policy and provider-backed credential replacement. NemoClaw runs no host listener, relay, or MCP process.

That decision improved the security boundary. It also narrowed the delivered user journey from "connect a host-local MCP server" to "connect an already hosted HTTPS MCP server." Issue #566 closed without a separate issue that owned the remaining host-local journey.

The current confusion follows from that history. The managed MCP feature name and original request suggest local custom-server support, while the implemented contract supports externally reachable HTTPS services.

Relationship to existing issues

This issue owns the product journey and the disposition of each deployment option. It must not duplicate the implementation owned by these issues:

• feat(network): generalize trusted private hosts across MCP and policy protocols #8176 owns the accepted protocol-independent trusted-private destination capability.
• feat(mcp): support secure host-local endpoints through trusted-private routing #8267 owns the cross-agent managed MCP implementation for a stable routed private HTTPS endpoint.

This issue owns:

• the historical disposition of the Proposal: MCP server bridge for host-to-sandbox credential isolation #566 host-local requirement;
• the supported current and target user journeys;
• consistent documentation and diagnostics across all supported agents;
• qualification criteria that reject temporary tunnel success as deployment evidence; and
• the remaining loopback or broker-pinned-host requirement after feat(mcp): support secure host-local endpoints through trusted-private routing #8267.

Options considered

Cloudflare documents Quick Tunnels as development-only and recommends a managed tunnel for production use: https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/trycloudflare/

Desired behavior

An operator should be able to determine the supported deployment pattern before exposing a local service.

For the current release, NemoClaw should state that managed MCP requires a stable public HTTPS endpoint with a controlled address set. The documentation should provide a fixed-ingress pattern and reject Quick Tunnel as a persistent deployment recommendation.

After #8176 and #8267, NemoClaw should recommend a stable routed private HTTPS endpoint for host-local MCP servers. The command, lifecycle, diagnostics, and documentation must remain equivalent across OpenClaw, Hermes, and Deep Agents Code.

Loopback-only and broker-pinned hostnames should remain rejected until OpenShell provides an attested route. The diagnostic should name that missing capability rather than recommend another temporary public tunnel.

Recommended delivery sequence

1. Current documentation and diagnostics
   • State that the existing managed MCP contract targets hosted HTTPS MCP services.
   • Document a stable public endpoint or fixed-ingress gateway as the current path.
   • Warn that Quick Tunnels and rotating CDN address sets are not persistent managed MCP endpoints.
   • Distinguish DNS pin drift, tunnel hostname replacement, TLS failure, upstream reachability, and credential failure.
2. Routed private endpoints
   • Complete feat(network): generalize trusted private hosts across MCP and policy protocols #8176 and feat(mcp): support secure host-local endpoints through trusted-private routing #8267.
   • Publish one cross-agent host reverse-proxy recipe with exact address, TLS, firewall, and credential requirements.
3. Complete host-local journey
   • Define the OpenShell service identity or attested host-route requirement.
   • Preserve destination identity, MCP method and tool policy, provider-backed credential replacement, audit, and lifecycle revocation.
   • Add the corresponding NemoClaw lifecycle only after an accepted OpenShell contract exists.
4. Qualification
   • Require a real authenticated MCP initialize, tool discovery, and bounded tool call from inside each supported agent sandbox.
   • Exercise service restart, host restart, DNS drift, and endpoint replacement.
   • Do not accept a host-side /health request or credential-resolution status as end-to-end MCP evidence.

Constraints and non-goals

• Do not weaken default-deny networking, server-side request forgery protection, DNS-rebinding protection, credential isolation, or MCP method enforcement.
• Do not authorize arbitrary loopback, host-network, wildcard, suffix, CIDR, or user-authored allowed_ips access.
• Do not make NemoClaw a persistent MCP data-plane proxy or credential-bearing process.
• Do not treat automatic repinning as equivalent to destination identity.
• Do not create agent-specific trust rules.
• Do not make scenario-specific infrastructure a canonical NemoClaw behavior without an accepted product decision.

Acceptance criteria

• The Proposal: MCP server bridge for host-to-sandbox credential isolation #566 history records which original requirements feat(mcp): add OpenShell-managed MCP servers #5876 delivered and which remain open.
• Documentation names hosted public HTTPS MCP as the current managed MCP contract.
• Documentation provides one current fixed-ingress pattern with prerequisites, credential boundaries, lifecycle effects, and verification criteria.
• Documentation marks Quick Tunnels as development-only and named tunnels as insufficient without a controlled address set.
• CLI diagnostics distinguish DNS pin drift from credential, TLS, and upstream failures.
• feat(network): generalize trusted private hosts across MCP and policy protocols #8176 and feat(mcp): support secure host-local endpoints through trusted-private routing #8267 provide the documented stable routed private HTTPS journey across OpenClaw, Hermes, and Deep Agents Code.
• The remaining loopback and broker-pinned-host journey has a named OpenShell dependency or an accepted decision that it will remain unsupported.
• E2E tests execute authenticated MCP traffic after restart and DNS-drift events for every supported agent.
• Scenario qualification requires real sandbox-to-MCP traffic and rejects temporary-tunnel-only evidence.
• No accepted path adds a NemoClaw host data plane, broad address authorization, or automatic pin widening.

Concrete example

Before:

local MCP server -> Quick Tunnel -> managed MCP add -> later CONNECT 403

After the near-term work:

local MCP server -> stable private HTTPS route -> exact trusted pins -> managed MCP

After an attested OpenShell service route exists:

operator-owned MCP service -> OpenShell service identity -> managed MCP

Checklist

• Existing issues were searched.
• This issue links feat(network): generalize trusted private hosts across MCP and policy protocols #8176 and feat(mcp): support secure host-local endpoints through trusted-private routing #8267 as implementation dependencies instead of redefining their security primitives.
• The problem and desired behavior are described.