PR #72515: fix(mcp): reject mixed command+url transport config (#72111)

• Repository: openclaw/openclaw
• Author: Bojun-Vvibe
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/72515

Description (problem / solution / changelog)

Closes #72111.

Problem

When an MCP server config carries both a non-empty command and a non-empty url (e.g. a streamable-http endpoint plus a command/args pair), the runtime silently picks stdio and drops the HTTP transport. The user sees:

MCP server connection timed out after 30000ms

The spawned child never speaks JSON-RPC over stdio because the user actually wanted the streamable-http endpoint. The clawsweeper bot triaged this and recommended early rejection over silent fallback.

Root cause

resolveMcpTransportConfig in src/agents/mcp-transport-config.ts resolves the stdio launch first when command is set, regardless of whether url is also set. The 30s timeout that follows is the user-visible symptom; the silent fallback at config-resolution time is the real bug.

Reproducer

In ~/.openclaw/openclaw.json:

{
  \"mcp\": {
    \"servers\": {
      \"broken\": {
        \"command\": \"node\",
        \"args\": [\"something.js\"],
        \"url\": \"https://my-mcp.example.com/mcp\"
      }
    }
  }
}

Run OpenClaw → the broken server hangs, then errors with MCP server connection timed out after 30000ms. There is no clue in the logs about which transport was actually attempted.

Fix

Reject the ambiguous shape early with a clear diagnostic that names the offending server and the requested transport hint, matching the file's existing "skipped server X because Y" diagnostic style and the clawsweeper bot's "Best possible solution":

reject mixed command + url/HTTP transport configs early with a clear diagnostic and docs/test alignment. The current silent stdio precedence should not remain the user-visible timeout path.

Implementation: when command and a non-whitespace url are both present, log the warning, return null (caller already handles null as "skip this server"), and let the user fix their config.

Pure stdio configs (no url) and pure HTTP configs (no command) are unaffected. Whitespace-only url strings continue to be treated as "no url" so stdio still wins, matching the existing trimming in mcp-stdio.ts.

Diff: +17 lines in mcp-transport-config.ts, +52 in tests.

Verification

pnpm vitest run src/agents/mcp-transport-config.test.ts
# 11 passed (7 original + 4 new)

pnpm check
# 0 errors, 0 warnings; all policy guards green

Tests added (4 new)

1. Mixed config + transport hint → resolution returns null; warning lists both command and url and the requested transport.
2. Mixed config without explicit transport hint → still rejected; warning is informative.
3. Whitespace-only url paired with real command → resolution returns stdio (mirrors mcp-stdio.ts trimming).
4. Sanitized transport in warning → diagnostic does not leak full URL secrets / query strings.

Risk notes

• Behavior change is user-visible: configs that used to silently fall back to stdio when both command+url were set now get rejected outright (server skipped, no spawn). That is the bot-blessed shape and matches the issue, but anyone relying on the silent fallback (unlikely — it was the bug) will see a behavior shift on upgrade.
• Did NOT touch src/agents/mcp-stdio.ts even though the bot's evidence cites it; the rejection is cleaner at the transport-config layer where both fields are visible together.
• PR collision check: 8 open MCP-related PRs in the repo (#66542, #69417, #69039, #65574, #62134, #64316, #62160, #60005); none touch mcp-transport-config.ts validation logic for the mixed shape. Safe to land independently.

Changed files

• src/agents/mcp-transport-config.test.ts (modified, +52/-0)
• src/agents/mcp-transport-config.ts (modified, +14/-0)