Manage SandboxesMCP Servers

Manage MCP Servers

View as Markdown

Use the host-side MCP commands to inspect and change registered servers.

List and Inspect Servers

$nemohermes my-sandbox mcp list
$nemohermes my-sandbox mcp status github --json

list --json and status --json never include environment values. They report provider presence, provider attachment, whether live policy matches registered policy, environment readiness, and adapter registration state.

The per-server warnings array reports the current sandbox-scoped provider risk and the OpenShell capabilities required to remove that warning. The env.missing field lists recorded host variable names that are currently unset.

An existing valid provider can remain ready when a host variable is unset because OpenShell retains the credential. The JSON value support.mode: "bridge" identifies the agent’s config-adapter capability, not a host-side traffic bridge.

For a trusted private server, status resolves the endpoint without changing managed state. Text output reports private address pins: match, drift, or unresolved. JSON output reports the same value in trustedPrivateTarget.state and includes the recorded pins. Status never adds a new address to the policy.

Discover Advertised Tools

Pass --tools with one server name to request the server’s advertised tool names:

$nemohermes my-sandbox mcp status github --tools
$nemohermes my-sandbox mcp status github --tools --json

The shared discovery runtime uses the managed registration’s existing OpenShell credential provider and generated policy. OpenShell injects the credential at the policy boundary; it is not passed to the runtime through arguments, environment values, or an authorization option. The same runtime and thin adapter ancestry are used across OpenClaw, Hermes, and LangChain Deep Agents Code sandboxes.

Run discovery only against a configured endpoint you trust to advertise names while authenticated. The endpoint controls every returned tool name and can derive those names from the request or credential it receives; NemoClaw validates and bounds the returned text but cannot prove that an authenticated endpoint did not encode credential-derived data in an otherwise valid name.

A discovery result is a point-in-time list from the configured MCP server, not an attestation of the exact tools visible to the model in an active agent session. Agent configuration, progressive disclosure, runtime filters, and session state can further limit model-visible tools.

NemoClaw runs the standard MCP initialize, notifications/initialized, and paginated tools/list lifecycle. It retains and returns tool names only, never prints the other tool-definition fields returned by tools/list, and never calls a tool. The client bounds total time, per-request time, cumulative response bytes, pages, tool count, cursor length, and tool-name length. It attempts to close the MCP session and transport on both success and failure. Cleanup errors do not replace the bounded discovery result.

JSON output adds a per-server toolDiscovery object without changing the existing status fields:

1{
2  "toolDiscovery": {
3    "ok": true,
4    "count": 2,
5    "tools": ["createJiraIssue", "getJiraIssue"],
6    "truncated": false
7  }
8}

Discovery is opt-in and sends authenticated network traffic to the configured endpoint. --tools requires one server name and suppresses the named-server credential-resolution probe that would otherwise run by default. Pass --probe --tools when you intentionally want both live checks.

An older sandbox image that does not contain the shared discovery client reports that a rebuild is required. Run nemohermes my-sandbox rebuild and retry the command.

A discovery failure sets toolDiscovery.ok to false and leaves the ordinary provider, policy, environment, and adapter status available. Bounded partial results set truncated to true and include a redacted detail value.

Verify Credential Resolution

Provider presence and metadata cannot prove that OpenShell rewrites openshell:resolve:env:KEY when a request leaves the sandbox. mcp status <server> requests a differential wire-level credential-resolution probe by default.

Before sending probe traffic, NemoClaw verifies exact generated policy, expected provider attachment, provider ID, generic type, valid resource version, and exactly one matching credential key. If readiness does not match, it reports ok: null with probe skipped and sends no request.

When readiness passes, the probe sends the same idempotent MCP initialize request twice from inside the sandbox through the adapter runtime. One request carries the real placeholder header, and the control request carries a deliberately unresolvable literal bearer.

A working rewrite makes the two requests reach the endpoint with different bearers. Only a placeholder HTTP 2xx paired with a rejected control verifies resolution because an accepted request proves a valid credential was on the wire.

Every non-2xx placeholder outcome is inconclusive. Identical HTTP 400, 401, or 403 rejections tell you to verify the stored credential first.

For HTTP 401 or 403, a confirmed-valid credential means the host is not rewriting placeholders. HTTP 400 remains inconclusive because the endpoint may reject the probe request itself.

The probe never captures or prints endpoint response bodies. It refuses to run against a persisted URL that no longer satisfies the authenticated-endpoint boundary.

The verdict appears as provider.credentialResolution in JSON and as a credential resolution: line in text output. Pass --no-probe to skip the probe or --probe to request it for every server in multi-server status.

The bare mcp list and mcp status forms never probe, so they stay fast. Endpoint outages, policy denials, timeouts, unreachable sandboxes, and endpoints that accept both probes report ok: null with evidence in detail.

Rotate a Credential

Export the replacement under the same host environment name used by mcp add, then restart that server:

$export GITHUB_MCP_TOKEN='replacement-value'
$nemohermes my-sandbox mcp restart github
$unset GITHUB_MCP_TOKEN

restart requires a successful provider update, waits until the sandbox receives a new opaque provider revision, reapplies policy, and refreshes the adapter. An ambiguous or failed update is not treated as successful merely because another writer advanced the provider revision.

For a trusted-private entry, restart replays the exact address pins recorded by mcp add. It does not resolve that endpoint again or widen its policy from ambient DNS. For a public entry, restart resolves the hostname again and refreshes the generated policy with the current validated public addresses.

The raw value passes only through the OpenShell provider command’s process environment and is not added to argv, NemoClaw state, or sandbox config. Revoke the old credential upstream after restart succeeds.

If the provider was deleted, restart recreates it from the exported value.

When the host variable is unset, restart reuses an existing provider whose current ID, type, and credential-key metadata match the registry. If the provider is missing, export the recorded variable before retrying.

Running restart without a server name refreshes every managed server. Export only the variables whose credentials you intend to replace.

Change Endpoint Pins

For a trusted-private server, review every destination change before NemoClaw records new pins. Neither status, restart, rebuild, nor restore changes the recorded address set.

If the endpoint moves to another address, remove and re-add the server:

$export LOCAL_MCP_TOKEN='replace-with-secret-manager-value'
$nemohermes my-sandbox mcp remove local-tools
$nemohermes my-sandbox mcp add local-tools \
>  --url https://mcp-host.corp.example/mcp \
>  --env LOCAL_MCP_TOKEN \
>  --trusted-private-host mcp-host.corp.example
$unset LOCAL_MCP_TOKEN

Removing the server deletes the registry-owned provider, policy, and adapter state after the existing ownership checks pass. The re-add performs a new DNS preflight and records the reviewed exact address set.

Remove a Server

$nemohermes my-sandbox mcp remove github

Removing a server blocks new requests and reconnects but does not terminate a response or SSE stream that is already open. For immediate revocation, revoke the upstream credential first, then run nemohermes <sandbox> rebuild --yes or destroy the sandbox to terminate an existing stream.

remove --force may remove a modified same-name adapter entry so an operator can clear local config. Provider deletion still requires the exact recorded provider ID, type, and credential key.

Policy deletion still requires exact owned content. Force never claims an unowned or drifted provider or same-key live policy.

If cleanup leaves a residual, the command exits nonzero and preserves the registry entry so cleanup can be retried. It never detaches the provider from other sandboxes.

Rebuild with Managed MCP State

rebuild preserves providers that match the recorded ID, type, and credential-key metadata. It removes adapter entries and detaches providers before replacing the sandbox, then reattaches providers, waits for credential readiness, reapplies policy, and restores adapters. For a trusted-private entry, the restored policy uses the recorded exact address pins and does not widen them from current DNS answers. Public entries continue to resolve and validate their endpoint addresses during restoration.

If sandbox replacement fails, NemoClaw attempts to restore the previous attachment and adapter state at the path used by the surviving image. A later mcp restart can retry an incomplete post-rebuild restore.

Destroy a Sandbox with MCP State

Destroy removes adapter entries and detaches providers that match recorded metadata before asking OpenShell to delete the sandbox. If deletion is refused, NemoClaw attempts to restore previous MCP state, reports rollback failures, and preserves recovery state. Provider deletion and registry cleanup happen only after OpenShell confirms the sandbox is gone.

An interrupted destroy can leave a durable transaction marker. A prepared-only marker means deletion is not durably confirmed. If the sandbox is still live, remove each affected server with force until the managed manifest is empty:

$nemohermes my-sandbox mcp remove <server> --force

A pending marker means the registry records that OpenShell deletion was already confirmed. mcp remove --force refuses that state because provider or policy cleanup can still be owed. Finish the idempotent destroy instead:

$nemohermes my-sandbox destroy

While either marker remains, rebuild refuses before backup or deletion and prints the applicable recovery command.

Respect the Lifecycle Lock

If a mutating command times out waiting for the per-sandbox lifecycle lock, confirm that no mcp, rebuild, or destroy command for that sandbox is still running, then retry.

recover also owns this lock while it repairs the gateway and forwards.

recover keeps the lock while it validates and releases any Hermes cron restore gate.

Every mutating command recovers a lock whose local process is provably dead or whose PID now has a different process-start identity.

NemoClaw does not expose a force-unlock flag. A live owner, different host or PID namespace, or incomplete legacy owner record fails closed because removing it could overlap a provider, policy, or adapter mutation.

For state shared across hosts or PID namespaces, resolve the owner on that host or stop sharing the state directory before retrying. Do not delete the lock file while ownership is ambiguous.