fix(mcp-v2): clearer MCP error when target host hasn't enabled remote access

[saddlepaddle]

Summary

Improves the error message MCP callers see when the cloud relay can't reach a user's host because the host hasn't enabled the remote-access tunnel.

Root cause

Cloud MCP can only reach a user's host when the desktop's exposeHostServiceViaRelay setting is on (Pro plan + Settings → Security → "Allow remote workspaces to access this device"). That field defaults to false, so until a user explicitly toggles it on, the host-service never opens a tunnel to the relay.

When MCP hits an un-tunneled host, the relay returns 503 host not connected and describeRelayFailure in packages/mcp-v2/src/host-service-client.ts previously rendered that as Host {hostId} is not online.

Why the previous message was misleading

The host's heartbeat to the API can be perfectly healthy — the host process is running, the user is signed in, the device shows online in the UI. "Not online" implied the user's machine was off or the app was closed, sending people down the wrong debugging path. The actual fix is one toggle in Settings.

Change

Single-line edit to the 503 + "host not connected" branch in describeRelayFailure. New string:

Host {hostId} has not enabled remote access. Toggle "Allow remote workspaces to access this device" in Settings → Security on that machine.

workspaces_create / workspaces_delete tool descriptions are intentionally left untouched — the error itself now carries the guidance, and tool descriptions are token-cost-per-call.

Predecessor

Follows #3918, which fixed the relay path for workspaces and OAuth client_name tracking.

Test plan

• Trigger an MCP workspaces_create against a host with the remote-access toggle off; confirm the new error string is returned instead of "is not online"
• Confirm other branches (401/403/404/generic) are unchanged

Summary by CodeRabbit

• Bug Fixes
  • Improved error messaging for remote connection failures with clearer, actionable guidance on enabling remote workspace access in system settings.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 94e15f8d-a48f-42c6-b20e-6e68f9a34264

📥 Commits

Reviewing files that changed from the base of the PR and between c5336f6 and 40624d8.

📒 Files selected for processing (1)

• packages/mcp-v2/src/host-service-client.ts

---

📝 Walkthrough

Walkthrough

Updated an error message in the host service client to provide users with specific, actionable troubleshooting steps when a host is not connected, replacing a generic notification with detailed instructions referencing the remote access security settings toggle.

Changes

Cohort / File(s)	Summary
Error Message Enhancement packages/mcp-v2/src/host-service-client.ts	Updated describeRelayFailure error message for 503 "host not connected" cases with specific setting path guidance ("Settings → Security" and "Allow remote workspaces to access this device" toggle) instead of generic "not online" response.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Poem

🐰 A message refined, so clear and so bright,
Users now know which toggle to sight,
No more confusion in error's dark night,
Settings and security, guidance made right! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and specifically describes the primary change: improving the MCP error message when remote access is disabled on the host.
Description check	✅ Passed	The description is comprehensive and well-structured, covering root cause, previous behavior, the change, and test plan, though missing explicit Related Issues and Type of Change sections.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/mcp-v2-relay-tunnel-error

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 6/8 reviews remaining, refill in 10 minutes and 3 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[greptile-apps]

Greptile Summary

This PR improves the error message returned by describeRelayFailure in host-service-client.ts when the relay responds with a 503 "host not connected" — replacing the misleading "is not online" wording with a clear, actionable message that points users to the exposeHostServiceViaRelay toggle in Settings → Security. The change is a single-line string edit with no logic changes.

Confidence Score: 5/5

Safe to merge — single-line string change with no logic impact.

The change is a trivial string update in a single branch of an error-formatting function. No logic, control flow, or data handling is affected, and the new message is clearly more actionable than the old one.

No files require special attention.

Important Files Changed

Filename	Overview
packages/mcp-v2/src/host-service-client.ts	Single-line string change in describeRelayFailure — replaces "is not online" with a more actionable message that tells users to enable the remote-access toggle in Settings → Security.

Sequence Diagram

sequenceDiagram
    participant MCP as MCP Caller
    participant Relay as Cloud Relay
    participant Host as User's Host

    MCP->>Relay: POST /hosts/{routingKey}/trpc/{procedure}
    alt exposeHostServiceViaRelay = false (tunnel not open)
        Relay-->>MCP: 503 "host not connected"
        Note over MCP: describeRelayFailure()<br/>NEW: "Host X has not enabled remote access.<br/>Toggle 'Allow remote workspaces...' in Settings → Security"
    else exposeHostServiceViaRelay = true (tunnel open)
        Relay->>Host: Forward request
        Host-->>Relay: Response
        Relay-->>MCP: 200 OK (or other status)
    end

Loading

_{Reviews (1): Last reviewed commit: "fix(mcp-v2): point users at remote-acces..." | Re-trigger Greptile}

[github-actions]

🧹 Preview Cleanup Complete

The following preview resources have been cleaned up:

• ✅ Neon database branch

Thank you for your contribution! 🎉