Reference

Troubleshoot MCP Servers

View as Markdown

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. Rotate it with mcp restart when in doubt.

For identical HTTP 401 or 403 responses, a confirmed-valid credential means the OpenShell gateway on this host is not rewriting openshell:resolve:env:KEY 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 and the original credential is not registered in OpenShell, export the same variable name used during add and retry.

Add Transaction Is Incomplete

If status reports an incomplete add transaction, rerun the original mcp add command with the same URL and environment-variable name. Re-export the value if the provider still needs to be created.

To abandon the transaction, run mcp remove <server> --force. NemoClaw cleans only resources whose ownership it can prove and keeps the registry entry when residual cleanup remains.

Agent MCP Capability Is Missing

If add or restart reports that mcporter, the Hermes transaction helper, or Deep Agents managed MCP capability v2 is unavailable, rebuild the sandbox onto a current image before retrying. An existing Deep Agents v1 entry remains removable, destroyable, and eligible for rebuild teardown when NemoClaw can identify the exact registry-owned legacy entry.

The rebuilt image must pass the v2 capability check before its MCP runtime is restored.

The rebuild installs the current projection path and reconstructs /sandbox/.deepagents/.nemoclaw-mcp.json from the host registry. Rebuild a Deep Agents sandbox, then retry the managed MCP command:

$nemo-deepagents <name> rebuild
$nemo-deepagents <name> mcp add <server-name> --url <url> --env <credential-env>

NemoClaw does not auto-load user-owned /sandbox/.deepagents/.mcp.json or project MCP files into managed configuration. Use nemo-deepagents <name> mcp ... for servers that need OpenShell credential replacement and egress policy.

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 side effect, the MCP command loads the exact generated policy with policy set --wait and exact-matches effective state.

A runtime that rejects protocol: mcp therefore fails closed.

Private or Plain-HTTP MCP URL Is Rejected

If nemo-deepagents <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 exact 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 OpenClaw mcporter run 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. OpenShell v0.0.85 cannot represent a direct IPv6 literal proxy target. See Add an MCP Server for the full endpoint requirements.

DNS Pins Drift

If mcp status <server> reports private address pins: drift, review the endpoint address change before updating access. Status, restart, rebuild, and restore do not add the new addresses.

Remove and re-add the server with the same exact trusted host to perform a new preflight and record new pins:

$export LOCAL_MCP_TOKEN='replace-with-secret-manager-value'
$nemo-deepagents <sandbox> mcp remove <server>
$nemo-deepagents <sandbox> mcp add <server> \
>  --url https://mcp-host.corp.example/mcp \
>  --env LOCAL_MCP_TOKEN \
>  --trusted-private-host mcp-host.corp.example
$unset LOCAL_MCP_TOKEN

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 rotate public edge addresses and are not durable for exact address pinning. A named tunnel can keep one hostname while its resolved addresses still 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 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.