Manage SandboxesMCP Servers

About Managed MCP Servers

View as Markdown

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 LangChain Deep Agents Code config.

This integration depends on the OpenShell MCP/JSON-RPC L7 policy support from NVIDIA/OpenShell#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 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 boundaryAccepted native OpenShell designSuperseded host proxy design
Credential boundaryOpenShell 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 enforcementOpenShell 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 exposureThe 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 behaviorProvider, 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 recoveryRandomized 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, and NVIDIA/NemoClaw#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.

OpenShell uses one socket-address list throughout resolution, validation, and connection:

The CONNECT path passes that list directly to TcpStream::connect at crates/openshell-supervisor-network/src/proxy.rs:822-832. The explicit HTTP-forward path carries the same list from crates/openshell-supervisor-network/src/proxy.rs:3885-3893 to crates/openshell-supervisor-network/src/proxy.rs:4123-4125. 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/<pid>/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

The managed image pins Deep Agents Code 0.1.34 and keeps NemoClaw definitions in /sandbox/.deepagents/.nemoclaw-mcp.json. The launcher validates canonical HTTPS endpoints and exact OpenShell credential placeholders, then supplies Deep Agents Code with a process-local, integrity-bound snapshot for server starts and restarts.

It prefers a sealed in-memory file when available; the anonymous read-only descriptor fallback verifies inode, size, and SHA-256 digest and fails closed on drift. NemoClaw never auto-loads user-owned /sandbox/.deepagents/.mcp.json or project MCP files into managed configuration.

1{
2  "mcpServers": {
3    "github": {
4      "type": "http",
5      "url": "https://api.githubcopilot.com/mcp/",
6      "headers": {
7        "Authorization": "Bearer openshell:resolve:env:GITHUB_MCP_TOKEN"
8      }
9    }
10  }
11}

External credential values remain in OpenShell provider state, not sandbox files or the NemoClaw registry.

Next Steps