Add auth-aware MCP client transport layer

[senamakel]

Summary

• add a shared openhuman::mcp_client registry so core can track named remote MCP servers instead of hardcoding one-off integrations
• implement auth-aware HTTP MCP client behavior including initialize, session reuse, 404 reinitialize/retry, auth challenge discovery, and tool-call header mirroring
• add stdio MCP transport support so local subprocess MCP servers can be used through the same registry abstraction
• route the existing gitbooks_* tools through the shared MCP client and expose generic agent bridge tools: mcp_list_servers, mcp_list_tools, and mcp_call_tool
• add focused unit and e2e-style Rust coverage for HTTP lifecycle, auth discovery, stdio transport, registry behavior, and tool registration

Problem

• OpenHuman previously only had a thin MCP server and one bespoke GitBook MCP consumer.
• Agents could not treat external MCP servers as a first-class capability surface inside core.
• Auth, session lifecycle, and stdio transport handling were missing from the client side, which made real MCP interoperability incomplete.

Solution

• introduce config-backed MCP server definitions with transport/auth settings and client identity metadata
• implement a protocol-aware HTTP MCP client with initialize + notifications/initialized, session header handling, auth challenge discovery, and retry on expired sessions
• implement a stdio MCP client that launches a subprocess and exchanges newline-delimited JSON-RPC over stdin/stdout
• add a transport-agnostic registry that picks HTTP or stdio per server and reuse it from generic MCP bridge tools and the GitBook docs tools
• keep remote MCP access behind explicit bridge tools for now rather than materializing every remote MCP tool into the native registry; that follow-up stays separate

Submission Checklist

If a section does not apply to this change, mark the item as N/A with a one-line reason. Do not delete items.

• Tests added or updated (happy path + at least one failure / edge case) per Testing Strategy
• Diff coverage ≥ 80% — changed lines (Vitest + cargo-llvm-cov merged via diff-cover) meet the gate enforced by .github/workflows/coverage.yml. Run pnpm test:coverage and pnpm test:rust locally; PRs below 80% on changed lines will not merge.
  CI remains the enforcement source here; local focused validation was run, but full local coverage was not.
• Coverage matrix updated — added/removed/renamed feature rows in docs/TEST-COVERAGE-MATRIX.md reflect this change (or N/A: behaviour-only change)
  N/A: no feature IDs or matrix rows changed for this infrastructure-layer work.
• All affected feature IDs from the matrix are listed in the PR description under ## Related
  N/A: no existing feature IDs were changed by this infrastructure-layer work.
• 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 manual smoke surface changed.
• Linked issue closed via Closes #NNN in the ## Related section
  N/A: no tracked GitHub issue was linked for this branch.

Impact

• Runtime/platform impact: Rust core, Tauri shell consumers of core, and agent tooling.
• Security impact: adds explicit per-server auth handling and preserves auth/session logic in core rather than pushing it to prompts.
• Compatibility impact: existing GitBook docs MCP path now runs through the shared client layer; legacy behavior is preserved by seeding gitbooks into the registry automatically.

Related

• Closes:
  N/A: no linked issue.
• Follow-up PR(s)/TODOs:
  • materialize remote MCP tools directly into the native agent tool registry instead of only through mcp_call_tool
  • add interactive OAuth/token-refresh flows backed by core-managed secrets rather than static config values

---

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

Keep this section for AI-authored PRs. For human-only PRs, mark each field N/A.

Linear Issue

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

Commit & Branch

• Branch: feat/mcp-core-first-level-integration
• Commit SHA: b2f867f6

Validation Run

• pnpm --filter openhuman-app format:check
• pnpm typecheck
• Focused tests:
  • cargo test --manifest-path Cargo.toml mcp_client --lib
  • cargo test --manifest-path Cargo.toml stdio_client_talks_to_openhuman_mcp_server --lib
  • cargo test --manifest-path Cargo.toml gitbooks --lib
  • cargo test --manifest-path Cargo.toml all_tools_registers_generic_mcp_bridge_tools_when_servers_exist --lib
  • cargo test --manifest-path Cargo.toml list_servers_renders_registry_entries --lib
• Rust fmt/check (if changed): cargo fmt --all, plus pre-push pnpm rust:check
• Tauri fmt/check (if changed): pre-push pnpm rust:check covered app/src-tauri

Validation Blocked

• command: pnpm test:coverage / pnpm test:rust
• error: not run locally in this pass; only focused MCP/client checks were run
• impact: diff-coverage and broader regression signal remain for CI to enforce

Behavior Changes

• Intended behavior change: core can now act as an MCP client across named HTTP and stdio servers with auth/session lifecycle support
• User-visible effect: agent tooling can inspect and call configured remote MCP servers through the new MCP bridge tools; GitBook docs MCP runs through the shared client path

Parity Contract

• Legacy behavior preserved: gitbooks_search and gitbooks_get_page remain available and now reuse the shared MCP client transport
• Guard/fallback/dispatch parity checks: legacy GitBook config seeds the registry automatically; HTTP sessions reinitialize on 404; stdio subprocess transport ignores non-JSON stdout noise while waiting for protocol frames

Duplicate / Superseded PR Handling

• Duplicate PR(s): N/A
• Canonical PR: this PR
• Resolution (closed/superseded/updated): updated

[coderabbitai]

Warning

Rate limit exceeded

@senamakel has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 9 minutes and 27 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9f54a66f-4957-4d2f-b566-45a971448983

📥 Commits

Reviewing files that changed from the base of the PR and between fe8237a and b2f867f.

📒 Files selected for processing (17)

• src/openhuman/config/mod.rs
• src/openhuman/config/schema/mod.rs
• src/openhuman/config/schema/tools.rs
• src/openhuman/config/schema/types.rs
• src/openhuman/mcp_client/client.rs
• src/openhuman/mcp_client/mod.rs
• src/openhuman/mcp_client/registry.rs
• src/openhuman/mcp_client/stdio.rs
• src/openhuman/mcp_server/protocol.rs
• src/openhuman/mcp_server/stdio.rs
• src/openhuman/mcp_server/tools.rs
• src/openhuman/mod.rs
• src/openhuman/tools/impl/network/gitbooks.rs
• src/openhuman/tools/impl/network/mcp.rs
• src/openhuman/tools/impl/network/mod.rs
• src/openhuman/tools/ops.rs
• src/openhuman/tools/ops_tests.rs

---

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