fix(observability): demote MCP auth-required 401

[YOMXXX]

Summary

• Demotes canonical MCP HTTP 401 auth-required errors to expected ProviderUserState.
• Keeps generic/unrelated HTTP 401 failures reportable.
• Adds focused regression coverage for the McpUnauthorizedError display shapes with and without resource metadata.
• Includes isolated docs link fixes required to unblock the repository-wide Markdown Link Check on current upstream/main.

Problem

Remote MCP servers can return HTTP 401 when the user needs to complete OAuth/sign-in. The MCP connection path already records that as needs_auth for the UI, but the RPC boundary re-raised the typed error display string and expected_error_kind did not classify it. That made expected user-state show up as Sentry errors.

The required Markdown Link Check also fails on current upstream/main because several localized README files still point to a Reddit URL returning 403 and a Star History URL fragment that no longer resolves. Those docs changes are separated in docs commits and do not affect runtime behavior.

Solution

• Add a narrow expected_error_kind matcher anchored on mcp unauthorized for + http 401.
• Classify that envelope as ProviderUserState, matching other third-party auth/user-state demotions.
• Add a debug breadcrumb for the classification decision without logging the full endpoint string.
• Add a negative test so generic HTTP 401 messages do not get swallowed by this MCP-specific arm.
• Replace stale localized README links and the redirected Cursor Cloud Agents docs link with link-check-safe targets.

Submission Checklist

• Tests added or updated (happy path + at least one failure / edge case) per Testing Strategy
• Diff coverage ≥ 80% — changed Rust lines are covered by focused Rust tests; CI coverage gate remains authoritative.
• Coverage matrix updated — N/A: observability-only Sentry classification change plus docs link cleanup; no feature matrix row added/removed/renamed.
• All affected feature IDs from the matrix are listed in the PR description under ## Related — N/A: no feature matrix IDs apply.
• No new external network dependencies introduced (mock backend used per Testing Strategy)
• Manual smoke checklist updated if this touches release-cut surfaces (docs/RELEASE-MANUAL-SMOKE.md) — N/A: no release smoke surface changed.
• Linked issue closed via Closes #NNN in the ## Related section

Impact

Desktop/core RPC observability only. Users still see the MCP server auth-required state via the existing needs_auth path; Sentry no longer treats that expected state as an application defect. No migration, network, or compatibility impact. Docs link updates only affect README link-check health.

Related

• Closes Demote MCP-connect 401 (needs sign-in) from Sentry error (TAURI-RUST-CGP) #4174
• Follow-up PR(s)/TODOs: none

---

AI Authored PR Metadata (required for Codex/Linear PRs)

Linear Issue

• Key: N/A
• URL: N/A

Commit & Branch

• Branch: fix/GH-4174-mcp-401-expected
• Commit SHA: 7c9c1caf3d9bc720072a5ad0ea97028a957f111c

Validation Run

• pnpm --filter openhuman-app format:check — N/A: frontend not changed.
• pnpm typecheck — N/A: frontend not changed.
• Focused tests:
  • GGML_NATIVE=OFF cargo test --manifest-path Cargo.toml --lib classifies_mcp_unauthorized_401_as_provider_user_state
  • GGML_NATIVE=OFF cargo test --manifest-path Cargo.toml --lib does_not_classify_unrelated_401_as_mcp_user_state
  • GGML_NATIVE=OFF cargo test --manifest-path Cargo.toml --lib core::observability::tests
• Rust fmt/check (if changed):
  • cargo fmt --manifest-path Cargo.toml --check
  • git diff --check
  • GGML_NATIVE=OFF cargo check --manifest-path Cargo.toml
• Tauri fmt/check (if changed): N/A: Tauri shell not changed.

Validation Blocked

• command: N/A
• error: N/A
• impact: N/A

Behavior Changes

• Intended behavior change: MCP auth-required HTTP 401 errors are treated as expected provider/user state by central observability.
• User-visible effect: none beyond reduced false-positive Sentry noise; existing MCP needs_auth UI behavior is preserved.

Parity Contract

• Legacy behavior preserved: generic/unrelated HTTP 401 errors remain reportable.
• Guard/fallback/dispatch parity checks: regression tests cover both canonical MCP 401 shapes and an unrelated 401 guard.

Duplicate / Superseded PR Handling

• Duplicate PR(s): none found for this branch.
• Canonical PR: this PR.
• Resolution (closed/superseded/updated): N/A

Summary by CodeRabbit

• Bug Fixes

  • Improved handling of certain MCP OAuth/401 connection errors so they’re recognized as expected user-state issues instead of being treated as reportable failures.
  • Added coverage to ensure only the intended unauthorized message pattern is classified this way.

• Documentation

  • Updated a cloud agents guide link to point to the latest documentation page.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds an early classifier arm in expected_error_kind that matches MCP unauthorized HTTP 401 messages (conjunctive check for mcp unauthorized for and http 401) and returns ExpectedErrorKind::ProviderUserState, preventing these from reaching Sentry. Two unit tests are added. A Cursor Cloud Agents doc link is also updated.

MCP 401 Demotion

Layer / File(s)	Summary
MCP 401 classifier arm and tests src/core/observability.rs	Doc comments added to expected_error_kind; new early conjunctive matcher returns ProviderUserState for MCP unauthorized HTTP 401 messages with a debug log; two unit tests verify matching and non-matching 401 cases.

Docs Link Update

Layer / File(s)	Summary
Cursor Cloud Agents link docs/agent-workflows/cursor-cloud-agents.md	Playbook URL updated from docs.cursor.com/agents/cloud to cursor.com/docs/cloud-agent.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐇 A sneaky 401 crept into my burrow,
Sentry cried loud but the cause wasn't thorough—
"MCP needs sign-in!" I twitched my small nose,
Classified ProviderUserState, and off the noise goes.
No more false alarms for a rabbit at rest! 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The localized docs link update is unrelated to #4174's observability fix and appears to be extra scope.	Move the Markdown link fix to a separate PR or explicitly tie it to the repository-wide link-check requirement.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately summarizes the main observability fix for MCP 401 auth-required errors.
Linked Issues check	✅ Passed	The observability classifier and tests match #4174 by demoting canonical MCP 401 unauthorized errors while keeping generic 401s reportable.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

---

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

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

[YOMXXX]

The localized README link fixes are intentionally included because the repository-wide required Markdown Link Check fails on current upstream/main for those stale links, even though #4174 is an observability fix. They are isolated in the docs commit and unblock the required gate; no product behavior changes.