Add opt-in live MCP tool discovery to mcp status

[ericksoa]

Problem Statement

nemoclaw <sandbox> mcp status <server> can report that a managed MCP server is configured, policy-authorized, credential-ready, and registered with the selected agent adapter without showing whether the endpoint actually advertises the tools the user needs.

This gap is observable when two valid endpoints for the same service both pass status checks but expose materially different tool inventories. Today, users must know an adapter-specific command such as mcporter list <server> --schema, and that workaround returns full untrusted schemas even when only tool names are needed.

Discussion #6734 established the user need and proposed an opt-in diagnostic. This issue records the intended supported behavior and implementation boundary so the feature can be delivered consistently across every current NemoClaw agent type.

Related context:

• Discussion: Proposal: Add opt-in live MCP tool discovery to mcp status (--tools) #6734
• Credential-resolution diagnostic: fix(mcp): probe wire-level credential resolution in mcp status and add (#6379) #6382
• Original all-green/unusable-runtime report: [DGX Spark][Sandbox] managed MCP unusable at runtime — OpenShell never resolves the openshell:resolve:env: credential placeholder (sends it literally); mcp status stays all-green #6379

Desired Behavior

Add an opt-in, named-server flag:

$ nemoclaw <sandbox> mcp status <server> --tools

The command must perform a live MCP initialization and enumerate the server's advertised tools, then append a concise, names-only result to the existing status output:

tool discovery: successful
tools discovered: 18
  - createJiraIssue
  - getJiraIssue
  - searchJiraIssuesUsingJql

The JSON form must add a stable field without changing existing status fields:

{
  "toolDiscovery": {
    "ok": true,
    "count": 18,
    "tools": [
      "createJiraIssue",
      "getJiraIssue",
      "searchJiraIssuesUsingJql"
    ],
    "truncated": false
  }
}

On failure, toolDiscovery.ok must be false and detail must contain a bounded, credential-safe explanation. The rest of the server status should still be returned so users can distinguish configuration, policy, credential, adapter-registration, and live-discovery failures.

The result means the names advertised by the MCP server at the time of this diagnostic. It does not promise the exact set visible to a model after an agent adapter applies its own naming, prefixing, or filtering.

Supported Scope and Consistency Contract

The first implementation must support all currently shipped agent types through one shared discovery behavior:

• OpenClaw (mcporter adapter)
• Hermes (hermes-config adapter)
• LangChain Deep Agents Code (deepagents-config adapter)

The wire-level MCP behavior, limits, parsing, and result format must be shared. Adapter-specific code may only launch that shared diagnostic inside the adapter's existing runtime/policy ancestry. The implementation must not maintain three independent MCP clients or infer tool names from generated agent configuration.

Use a pinned official Model Context Protocol SDK for the shared live client so initialization, protocol negotiation, streamable HTTP/SSE handling, session identifiers, pagination, and session cleanup are handled consistently. If an existing sandbox image does not contain the diagnostic runtime, report that the sandbox must be rebuilt; do not fall back to a host request or a different adapter-specific path.

MCP Lifecycle Requirements

The diagnostic must:

1. connect through the managed server's resolved URL, existing credential provider, and existing network policy;
2. perform initialize and send notifications/initialized;
3. preserve negotiated protocol/session metadata required by subsequent requests;
4. call tools/list, following pagination within the configured bounds;
5. close the client/session on success or failure where the transport supports it;
6. return tool names only.

The generated MCP policy already permits initialize, notifications/initialized, and tools/list; this feature must not broaden it to new methods.

Security and Resource Boundaries

The diagnostic must never:

• call tools/call or invoke any discovered tool;
• print or return credentials, authorization headers, credential placeholders, environment values, request arguments, tool results, descriptions, schemas, annotations, or other remote metadata;
• follow a redirect outside the already validated managed endpoint;
• bypass the sandbox, gateway, credential provider, network policy, or adapter runtime boundary.

It must enforce bounded values for:

• total elapsed time;
• response bytes;
• pagination depth;
• number of returned tool names;
• cursor length;
• individual tool-name length.

Malformed responses, repeated cursors, duplicate names, control characters, and responses that exceed a safety limit must fail closed with a bounded detail. If a limit is reached after partial enumeration, return the safe partial names with ok: false and truncated: true; do not present an incomplete inventory as successful.

Flag Interaction

• Plain mcp status remains unchanged and performs no new network request.
• --tools is valid only with one named server.
• Tool discovery itself exercises credential resolution. To avoid duplicate live traffic, --tools should replace the status command's implicit credential probe.
• If a user explicitly combines --probe --tools, run and report both diagnostics.

Acceptance Criteria

• nemoclaw <sandbox> mcp status <server> --tools works with OpenClaw, Hermes, and LangChain Deep Agents Code sandboxes.
• All three adapters use the same image-baked discovery client and the same JSON/result contract.
• Successful discovery returns a deterministic names-only inventory and accurate count.
• MCP initialization, initialized notification, protocol/session handling, pagination, and cleanup follow the negotiated transport lifecycle.
• No discovered tool is invoked, and no remote schema or credential-bearing value is emitted.
• Time, size, page, tool-count, cursor, and name limits are enforced and covered by negative tests.
• Authentication, malformed-response, repeated-cursor, redirect, timeout, and truncation failures return bounded credential-safe details.
• Plain mcp status, mcp status <server>, --probe, and --json retain their existing behavior except for the explicitly defined --tools interaction.
• Old sandbox images without the shared client fail with an explicit rebuild-required message.
• CLI help and user documentation explain the opt-in network activity and the server-advertised (not model-visible) meaning of the result.
• Unit/integration coverage protects parsing, rendering, safety limits, adapter launch commands, and result mapping.
• Live E2E coverage exercises a paginated fake MCP server through all three current agent types and proves that tools/list occurs without any tools/call.

Constraints and Non-goals

• Do not add a separate top-level MCP client or general-purpose tool invocation command.
• Do not expose full tool schemas or descriptions.
• Do not compare the inventory with a user-defined required-tool list in this change.
• Do not claim exact model-visible names or reachability beyond the point-in-time diagnostic.
• Do not add adapter-specific behavior beyond the minimal launch boundary.
• Do not broaden network policy or credential-provider permissions.

Implementation Idea

Add a small shared TypeScript/Node diagnostic runtime, pin its MCP SDK dependency and lockfile, and bake the same artifact into every current agent image. Extend the existing MCP bridge status action with a toolDiscovery result and a per-adapter launcher that runs the shared client under the same policy ancestry already used for credential probing. Reuse the existing URL validation, managed-policy lookup, credential-provider resolution, adapter readiness, redaction, and sandbox-exec boundaries.

Keep the change direct: one flag, one shared wire client, one result contract, thin launch mapping, and no new user-selectable modes.

Verification Plan

• Focused unit tests for CLI parsing, output rendering, result contracts, adapter launch mapping, pagination, limits, malformed input, and redaction.
• Existing MCP bridge status/probe tests to prove backward compatibility.
• E2E-support tests for the fake MCP server lifecycle and no-call assertion.
• Live opt-in agent matrix for OpenClaw, Hermes, and LangChain Deep Agents Code.
• Repository diff checks, package/build contracts, and documentation validation required by the touched paths.

Checklist

• I searched existing issues and this is not a duplicate.
• I described the problem and desired behavior.