> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemoclaw/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemoclaw/_mcp/server. # About Managed MCP Servers > Understand how NemoClaw connects sandboxed agents to authenticated Streamable HTTP MCP servers. NemoClaw lets a sandboxed agent use authenticated Streamable HTTP MCP servers without copying external service credentials into the sandbox. The integration has three parts: * An OpenShell provider stores credentials outside the sandbox. * A generated OpenShell network policy grants the MCP endpoint through `protocol: mcp` and applies explicit JSON-RPC MCP method rules. * An agent adapter writes the MCP endpoint into OpenClaw config. This integration depends on the OpenShell MCP/JSON-RPC L7 policy support from [NVIDIA/OpenShell#1865](https://github.com/NVIDIA/OpenShell/pull/1865). NemoClaw v0.0.74 defaults to the pinned stable OpenShell `0.0.72` release, which exposes native `protocol: mcp` policy handling and provider-backed credential replacement. The optional OpenShell development channel is compatibility evidence only and is not a shipping target. NemoClaw accepts Streamable HTTP MCP endpoints only. It does not launch an MCP server, stdio adapter, bridge, credential proxy, data-plane relay, or listener on the host. The sandbox agent connects directly to the configured endpoint, and OpenShell enforces policy and replaces credentials in its existing sandbox egress path. No NemoClaw host process remains running after an `mcp` lifecycle command returns. ## Accepted Architecture The native OpenShell design was [accepted on June 30, 2026](https://github.com/NVIDIA/NemoClaw/issues/566#issuecomment-4847534784) as the normative design for NemoClaw v0.0.74. It supersedes the original host-side stdio-to-HTTP proxy proposed in NVIDIA/NemoClaw#566. NemoClaw does not accept an inline secret-and-command tuple, persist the raw bearer value supplied through `--env`, or operate a host-side MCP data-plane process. Host-side MCP bridges, proxies, relays, listeners, and stdio translation are explicitly out of scope. | Decision boundary | Accepted native OpenShell design | Superseded host proxy design | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | Credential boundary | OpenShell stores the raw value and resolves a sandbox placeholder only on an authorized request. | A NemoClaw host process would receive and retain the raw value while proxying traffic. | | Policy enforcement | OpenShell evaluates the destination, path, adapter identity, pinned addresses, and MCP methods before credential replacement. | The proxy would become a second authorization implementation outside OpenShell policy. | | Data-plane exposure | The sandbox connects through OpenShell's existing egress path; NemoClaw leaves no host listener or MCP traffic process. | A host listener and stdio-to-HTTP relay would expand the data plane and local attack surface. | | Failure behavior | Provider, policy, and adapter mutations fail closed and preserve retryable registry state when ownership or readiness cannot be proven. | Proxy failure could strand a listener, subprocess, or partially persisted secret-bearing launch state. | | Crash recovery | Randomized provider ownership records and per-sandbox lifecycle locks let lifecycle commands reconcile durable state. | Recovery would also have to discover orphan host processes and reconstruct their secret-bearing invocation state. | The decision record is tracked in [NVIDIA/NemoClaw#566](https://github.com/NVIDIA/NemoClaw/issues/566), and [NVIDIA/NemoClaw#5876](https://github.com/NVIDIA/NemoClaw/pull/5876) implements it. ## Authenticated MCP Security Boundary Authenticated MCP is the intended configuration. The agent stores only the `openshell:resolve:env:KEY` placeholder. OpenShell keeps the raw credential in its provider store and combines credential replacement with generated MCP policy at egress. For the normal MCP client path, OpenShell evaluates the effective policy for the destination host and port, adapter binary, literal endpoint path, and MCP method before replacing placeholders in allowed HTTP request headers. The generated policy grants only the configured destination, path, adapter binaries, pinned addresses, explicit MCP method profile, and a 131,072-byte maximum request body. NemoClaw accepts canonical HTTPS MCP URLs and writes the credential placeholder only into the `Authorization` header. ### DNS Pinning Contract The MCP integration pins its OpenShell DNS enforcement contract to [`NVIDIA/OpenShell@8cb16de9eae4c44d7d31e1493747d8c10abb5963`](https://github.com/NVIDIA/OpenShell/tree/8cb16de9eae4c44d7d31e1493747d8c10abb5963). OpenShell uses one socket-address list throughout resolution, validation, and connection: * [`crates/openshell-supervisor-network/src/proxy.rs:2476-2502`](https://github.com/NVIDIA/OpenShell/blob/8cb16de9eae4c44d7d31e1493747d8c10abb5963/crates/openshell-supervisor-network/src/proxy.rs#L2476-L2502) produces the list. * [`crates/openshell-supervisor-network/src/proxy.rs:2527-2567`](https://github.com/NVIDIA/OpenShell/blob/8cb16de9eae4c44d7d31e1493747d8c10abb5963/crates/openshell-supervisor-network/src/proxy.rs#L2527-L2567) validates every address. * [`crates/openshell-supervisor-network/src/proxy.rs:2622-2630`](https://github.com/NVIDIA/OpenShell/blob/8cb16de9eae4c44d7d31e1493747d8c10abb5963/crates/openshell-supervisor-network/src/proxy.rs#L2622-L2630) returns the validated list unchanged. The CONNECT path passes that list directly to [`TcpStream::connect` at `crates/openshell-supervisor-network/src/proxy.rs:822-832`](https://github.com/NVIDIA/OpenShell/blob/8cb16de9eae4c44d7d31e1493747d8c10abb5963/crates/openshell-supervisor-network/src/proxy.rs#L822-L832). The explicit HTTP-forward path carries the same list from [`crates/openshell-supervisor-network/src/proxy.rs:3885-3893`](https://github.com/NVIDIA/OpenShell/blob/8cb16de9eae4c44d7d31e1493747d8c10abb5963/crates/openshell-supervisor-network/src/proxy.rs#L3885-L3893) to [`crates/openshell-supervisor-network/src/proxy.rs:4123-4125`](https://github.com/NVIDIA/OpenShell/blob/8cb16de9eae4c44d7d31e1493747d8c10abb5963/crates/openshell-supervisor-network/src/proxy.rs#L4123-L4125). There is no second hostname resolution between validation and connection in either path. ### Stable OpenShell 0.0.72 Limitations OpenShell v0.0.72 attributes network policy with `/proc//exe` and process ancestors, so script-based adapters require Node or Python interpreter grants rather than immutable package-entrypoint identities. NemoClaw compensates with an exact HTTPS destination, path, MCP method profile, DNS pins, and a unique least-privilege credential for each server. Remove the interpreter grants when OpenShell exposes stable script or package entrypoint attribution. OpenShell v0.0.72 attaches static provider credentials at sandbox scope rather than reserving a credential key exclusively for one endpoint. It also does not expose an immutable provider binding on an attachment, provide a `tls: require` policy mode, bind the HTTP `Host` header to the policy destination, or include query parameters in MCP path matching. NemoClaw rejects credential-key reuse between managed MCP servers, creates a dedicated provider for each definition, reports the residual risk in `status`, and requires a unique least-privilege token and environment key. Do not grant a broader inspected-HTTP route to the same adapter runtime because that route could resolve the sandbox-scoped placeholder. The generated configuration uses the canonical HTTPS URL, but malicious code running as an allowed interpreter can deliberately change the scheme, `Host` header, or query string within the supported OpenShell policy contract. OpenShell v0.0.72 updates, attaches, detaches, and deletes providers by mutable name instead of an atomic immutable identity. NemoClaw compensates with randomized provider names, the per-sandbox lifecycle lock, and immediate ownership checks against the recorded provider ID, type, and credential-key metadata before mutations. NemoClaw fails closed and preserves retryable state when those checks do not match, but the checks do not provide compare-and-swap behavior against another OpenShell client. Do not concurrently replace or mutate a managed provider through another OpenShell client while an MCP lifecycle command is running. Use an MCP service you trust with the credential it receives. MCP response bodies and SSE streams return through OpenShell's existing sandbox egress path. As with any authenticated API, a server that possesses a credential can deliberately return that value in its response. This does not expose the raw credential to the sandbox before the request is authorized and sent to that server. ## Agent Adapters OpenClaw uses `mcporter config add` in the sandbox. ## Next Steps * [Add an MCP Server](add-an-mcp-server) for endpoint and credential requirements. * [Manage MCP Servers](manage-mcp-servers) for status, rotation, restart, removal, rebuild, and destroy behavior. * [Troubleshoot MCP Servers](../../reference/troubleshoot-mcp-servers) for failure remediation.