Troubleshoot MCP Servers
Use the reported status or lifecycle error to choose the matching remediation.
Credential Resolution Is Unknown
If mcp status <server> reports identical placeholder and control rejections, first confirm the stored credential is valid.
Restart validates and reloads the current provider-backed registration; it never consumes an exported replacement credential.
To replace the credential, follow the conservative remove and re-add procedure:
Preserve the original denied-tool selectors and --trusted-private-host declaration on the re-add.
See Rotate a Credential for the complete provider-cleanup sequence.
For identical HTTP 401 or 403 responses, a confirmed-valid credential means the OpenShell gateway on this host is not rewriting the recorded resolver placeholder on egress. Every agent request receives the same authentication failure even when provider, attachment, readiness, and adapter checks report healthy.
This is a host-side OpenShell defect rather than a NemoClaw registration problem. Verify the OpenShell installation on the host, tracked upstream as OpenShell issue 2161.
An identical HTTP 400 remains inconclusive because the endpoint may reject the probe’s initialize request.
Compare status for the same server on a known-good host.
A credential resolution: unknown verdict with an endpoint or policy detail means the probe could not reach a judgment.
Fix the reported endpoint or policy condition, then rerun status.
A detail containing CONNECT 503 means OpenShell failed closed before TLS setup because gateway TLS termination state was unavailable.
Inspect the OpenShell gateway’s ephemeral CA generation and CA-file initialization, repair the reported condition, and rerun mcp status <server>.
Provider Is Missing During Restart
If restart reports a missing provider, remove the native registration and re-add it with the same URL, credential environment name, denied-tool selectors, and trusted-private declaration. Restart does not recreate providers.
Provider Uses the Legacy Generic Profile
If restart or rebuild reports that the provider uses the profile-less legacy generic type, remove that server and add it again with the recorded credential variable exported.
OpenShell cannot bind that provider to an MCP endpoint, and NemoClaw accepts it only for cleanup.
Rebuild Cannot Prove a Credential Handle
If rebuild reports that it could not prove a credential handle, a fresh sandbox process did not expose the exact OpenShell credential identity required for adapter cleanup. NemoClaw leaves the affected adapter and every provider unchanged. It attempts to restore adapter entries prepared earlier in the operation and reports rollback failures.
Inspect the managed server:
If status cannot reach the sandbox, repair the reported gateway condition first. Export the replacement under the same environment-variable name, then remove and re-add the server so a fresh provider binding and agent placeholder are created:
Run status again.
OpenShell can retain the same s… stable handle after a provider update; verify endpoint authorization with the named mcp status probe.
Retry rebuild only after provider.credentialReady and adapter.registered are both true.
If the re-add still cannot prove the credential handle, repair the reported OpenShell provider, policy, or adapter condition before retrying teardown.
Hermes Add Outcome Is Unknown
If Hermes reports an unknown outcome after losing its OpenShell exec relay, do not rerun mcp add.
Do not force-remove or remove and re-add the server.
NemoClaw proved neither committed state nor absence, so another mutation can conflict with the in-flight or committed transaction.
Inspect the current state without changing it:
Preserve the reported diagnostic. Repair any reported sandbox readiness, gateway health, provider, policy, attachment, or adapter problem before another MCP lifecycle command. Keep the registration unchanged while status remains unavailable, conflicting, or incomplete.
Add Transaction Is Incomplete
For an interrupted mcp add that does not report an unknown outcome, inspect the native source and live status first.
If no native registration exists, rerun the original command with the same URL, environment-variable name, and any --deny-tool options.
If the native registration exists, remove it and then re-add it after re-exporting the credential.
To abandon the transaction, run mcp remove <server> --force.
NemoClaw disables the native agent entry first and cleans only live resources whose ownership it can prove. It preserves the workspace provider and reports any residual policy or attachment cleanup.
Agent MCP Capability Is Missing
If add or restart reports that the OpenClaw native writer, Hermes transaction helper, or Deep Agents native MCP capability v3 is unavailable, rebuild the sandbox onto a current image before retrying.
When an older OpenClaw or Deep Agents sandbox has a legacy MCP file, preview mcp migrate, then use mcp migrate --apply when you intend to convert it. To delete one named legacy entry instead, run mcp remove <server>; NemoClaw removes it only when a matching committed registry row proves ownership and otherwise preserves it. A native definition that conflicts with the legacy definition stops migration before mutation.
If Hermes reports that reconcile-finality capability version 1 is unavailable, the MCP mutation did not start. Rebuild the sandbox onto a current image, then retry the original MCP command:
Rebuild uses the older helper only to remove exact managed entries from the retiring sandbox. The replacement helper must report capability version 1 before it restores those entries.
If a Hermes sandbox is alive but its gateway is not running after a supervisor or container restart, run nemohermes <sandbox> recover before retrying the MCP command.
Recovery re-establishes the managed service lifecycle, API forwarding, and the exit-75 reload loop used for transactional MCP configuration changes.
Collect Sandbox Logs
Read recent sandbox logs while you reproduce an MCP failure:
The command reads agent gateway output and OpenShell audit events, so policy denials appear beside gateway logs. If NemoClaw cannot enable OpenShell audit logs, it prints a warning and the policy denial events can be missing.
Policy or Provider Ownership Drifted
If generated policy or provider metadata drifted, restart fails closed instead of overwriting same-name state.
Resolve the reported OpenShell ownership or content mismatch, then retry.
remove --force can continue cleaning other independently owned resources, but it does not claim or delete the drifted resource.
Registry entries created by an earlier preview with a host-alias URL or a credential name that is now reserved remain visible so they can be removed safely. Status reports the unsupported boundary, and restart and rebuild fail closed.
Remove the legacy entry before rebuilding or destroying the sandbox, then add a public HTTPS DNS endpoint with a dedicated service credential name.
MCP Policy Capability Is Unavailable
Install the required OpenShell build and rerun onboarding.
NemoClaw checks inspectable installed OpenShell artifacts for protocol: mcp capability and does not enable managed MCP from a version number alone.
For image-backed or compressed supervisors without an inspectable host artifact, the onboarding check is provisional.
Before a credential or provider mutation, the MCP command imports or verifies the endpointless profile and loads the generated policy without a credential binding by using policy set --wait.
After provider attachment, it applies and matches the endpoint-bound policy before credential use.
A runtime that rejects protocol: mcp therefore fails closed.
Private or Plain-HTTP MCP URL Is Rejected
If nemohermes <sandbox> mcp add rejects an http:// URL, use HTTPS before you retry.
This requirement applies to OpenClaw, Hermes, and Deep Agents Code so OpenShell forwards the bearer credential over TLS.
If the endpoint resolves to RFC1918, carrier-grade network address translation (CGNAT), or IPv6 unique local addresses, add its host with --trusted-private-host.
The declared host must equal the normalized hostname from --url.
NemoClaw rejects a private endpoint without that explicit declaration before provider, policy, registry, or adapter mutation.
An agent-native registration path, such as editing OpenClaw openclaw.json inside the sandbox, may accept a plain-HTTP or local URL, but it bypasses NemoClaw credential replacement and generated egress policy.
A URL that the agent-native path accepts is therefore not registrable through managed mcp add.
For a host-local server, keep the MCP process on loopback when practical.
Place an operator-managed HTTPS reverse proxy on a stable private address that the OpenShell gateway can route to.
The certificate must match the original endpoint hostname and chain to a trust root available to the managed runtime.
For a private CA, set NEMOCLAW_CORPORATE_CA_BUNDLE before onboarding, or rebuild the existing sandbox after setting it.
The managed image installs that CA for both the OpenShell upstream proxy and sandbox TLS clients.
Restrict the proxy listener to the OpenShell gateway or required deployment subnet with host firewall rules.
Direct 127.0.0.1, ::1, and hostnames that resolve to loopback remain rejected.
Sandbox loopback is not the host service, and --trusted-private-host does not create a route to it.
Use a DNS hostname for an IPv6 unique local address.
NemoClaw has not qualified direct IPv6-literal MCP URLs and rejects them.
See Add an MCP Server for the full endpoint requirements.
DNS Pins Drift
If mcp status <server> reports public address pins: drift, refresh only its live policy pins:
The refresh preserves all other policy fields, including denied tools, and retains the existing agent configuration and credentials. Successful tool discovery verifies recovery. Status, restart, rebuild, and restore preserve the live pins. If refresh cannot confirm a write, inspect status and the live OpenShell policy before retrying.
If status reports public address pins: rejected, DNS resolved to a private or special-use address.
Investigate the destination change; refresh does not approve that address.
If status reports public address pins: unresolved, DNS is unavailable and the recorded pins remain unchanged.
Retry status after DNS recovers.
If status reports private address pins: drift, review the endpoint address change before updating access.
Status, restart, rebuild, and restore do not add new trusted-private addresses.
Remove and re-add the server with the same trusted host to perform a new preflight and record new pins:
A CONNECT 403 after an address change can mean that OpenShell rejected a current DNS answer outside allowed_ips.
Do not add a provider’s complete address range or broaden the policy to bypass the denial.
Cloudflare Quick Tunnels and named tunnels can rotate public edge addresses while keeping one hostname. A managed MCP server can require another explicit pin refresh after each public address change. Use stable private DNS and a routed private HTTPS endpoint for a host-local MCP server.
If status reports matching pins but the request still receives CONNECT 403, inspect the OpenShell policy and audit logs.
Do not treat matching DNS pins as evidence that the path, method, adapter identity, or provider attachment also matches.
Lifecycle Lock Times Out
Confirm that no mcp add, mcp update, mcp restart, mcp remove, rebuild, or destroy command for the sandbox is still running, then retry the original command.
NemoClaw recovers a lock only when its local process is provably dead or its PID has a different process-start identity.
It does not expose a force-unlock flag. Resolve a live or ambiguous owner on the host that owns it, and do not delete the lock file manually.
Related Topics
- Add an MCP Server for endpoint and credential requirements.
- Manage MCP Servers for normal lifecycle operations.
- About Managed MCP Servers for the accepted security boundary.